מודולים ראשיים

תיעוד מפורט של המודולים הראשיים בפרויקט.

File Management

class file_manager.BackupInfo(backup_id, user_id, created_at, file_count, total_size, backup_type, status, file_path, repo, path, metadata)

Bases: object

מידע על גיבוי

פרמטרים:

• backup_id (str)

• user_id (int)

• created_at (datetime)

• file_count (int)

• total_size (int)

• backup_type (str)

• status (str)

• file_path (str)

• repo (str | None)

• path (str | None)

• metadata (Dict[str, Any] | None)

__init__(backup_id, user_id, created_at, file_count, total_size, backup_type, status, file_path, repo, path, metadata)

פרמטרים:

• backup_id (str)

• user_id (int)

• created_at (datetime)

• file_count (int)

• total_size (int)

• backup_type (str)

• status (str)

• file_path (str)

• repo (str | None)

• path (str | None)

• metadata (Dict[str, Any] | None)

class file_manager.BackupManager

Bases: object

מנהל גיבויים

__init__()

cleanup_expired_backups(retention_days=None, *, max_per_user=None, budget_seconds=None)

ניקוי גיבויים ישנים ממערכת הקבצים ומ‑GridFS באופן מבוקר.

פרמטרים: - retention_days: ימים לשמירת גיבוי לפני מחיקה (ברירת מחדל: BACKUPS_RETENTION_DAYS או 30) - max_per_user: כמות מקסימלית של גיבויים לשמירה לכל משתמש (ברירת מחדל: BACKUPS_MAX_PER_USER או None) - budget_seconds: תקציב זמן לניקוי כדי לא לחסום את ה־worker (ברירת מחדל: BACKUPS_CLEANUP_BUDGET_SECONDS או 3)

החזרה: dict עם counters לסריקה/מחיקות ושגיאות.

Return type:

dict

פרמטרים:

• retention_days (int | None)

• max_per_user (int | None)

• budget_seconds (float | None)

save_backup_bytes(data, metadata)

שומר ZIP של גיבוי בהתאם למצב האחסון ומחזיר backup_id או None במקרה כשל.

אם storage==mongo: שומר ל-GridFS עם המטאדטה. אם storage==fs: שומר לקובץ תחת backup_dir.

Return type:

Optional[str]

פרמטרים:

• data (bytes)

• metadata (Dict[str, Any])

save_backup_file(file_path)

שומר קובץ ZIP קיים לאחסון היעד (Mongo/FS) ומחזיר backup_id אם הצליח.

Return type:

Optional[str]

פרמטרים:

file_path (str)

list_backups(user_id)

מחזירה רשימת קבצי ZIP ששייכים למשתמש המבקש בלבד.

כל פריט חייב להיות מסווג כשייך ל-user_id דרך אחד מהבאים: - metadata.json בתוך ה-ZIP עם שדה user_id תואם - דפוס מזהה בשם: backup_<user_id>_*

ZIPים ללא שיוך ברור למשתמש לא ייכללו כדי למנוע זליגת מידע.

Return type:

List[BackupInfo]

פרמטרים:

user_id (int)

restore_from_backup(user_id, backup_path, overwrite=True, purge=False, extra_tags=None)

משחזר קבצים מ-ZIP למסד הנתונים.

• purge=True: מסמן את כל הקבצים הקיימים של המשתמש כלא פעילים לפני השחזור

• overwrite=True: שמירה תמיד כגרסה חדשה עבור אותו שם (כברירת מחדל)

החזרה: dict עם restored_files ו-errors

Return type:

Dict[str, Any]

פרמטרים:

• user_id (int)

• backup_path (str)

• overwrite (bool)

• purge (bool)

• extra_tags (List[str] | None)

delete_backups(user_id, backup_ids)

מוחק מספר גיבויי ZIP לפי backup_id ממערכת הקבצים ומ-GridFS (אם בשימוש).

החזרה: {”deleted“: int, ”errors“: [str, …]}

Return type:

Dict[str, Any]

פרמטרים:

• user_id (int)

• backup_ids (List[str])

delete_backup(backup_id, user_id)

מחיקת גיבוי

Return type:

bool

פרמטרים:

• backup_id (str)

• user_id (int)

GitHub Integration

async github_upload_fix.github_upload_new_file(update, context)

בקשה להעלאת קובץ חדש לגיטהאב

async github_upload_fix.handle_document_fixed(update, context)

טיפול בקובץ שהתקבל

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

async github_upload_fix.upload_to_github_fixed(update, context, status_message)

העלאה מתוקנת לגיטהאב

async github_upload_fix.setup_minimal_commands(application)

מחיקת כל הפקודות והשארת רק stats למנהל

Return type:

None

פרמטרים:

application (telegram.ext.Application)

async github_upload_fix.stats_command_secured(update, context)

הצג סטטיסטיקות - רק לאמיר בירון

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

async github_upload_fix.check_commands(update, context)

בדיקת הפקודות הזמינות (רק לאמיר)

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

Backup System

backup_menu_handler.emit_event(event, severity='info', **fields)

Return type:

None

פרמטרים:

• event (str)

• severity (str)

• fields (Any)

class backup_menu_handler.BackupMenuHandler

Bases: object

תפריט גיבוי ושחזור מלא + נקודות שמירה בגיט

__init__()

async show_backup_menu(update, context)

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

async handle_callback_query(update, context)

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

async send_rating_prompt(update, context, backup_id)

שולח הודעת תיוג עם 3 כפתורים עבור גיבוי מסוים.

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

• backup_id (str)

Code Processing

מנהל תצוגה מקדימה של קוד Code Preview Manager

class code_preview.CodePreviewManager

Bases: object

מנהל תצוגה מקדימה של קוד

__init__()

Return type:

None

create_preview(code, file_name, programming_language)

יוצר תצוגה מקדימה של קוד

Return type:

Dict[str, Any]

פרמטרים:

• code (str)

• file_name (str)

• programming_language (str)

format_preview_message(file_name, preview_info)

יוצר הודעה מעוצבת לתצוגה מקדימה

Return type:

str

פרמטרים:

• file_name (str)

• preview_info (Dict[str, Any])

create_quick_info(file_data)

יוצר מידע מהיר על קובץ ללא תצוגת קוד

Return type:

str

פרמטרים:

file_data (Dict)

Search Engine

Repository Analysis

repo_analyzer.emit_event(event, severity='info', **fields)

פרמטרים:

• event (str)

• severity (str)

class repo_analyzer.RepoAnalyzer(github_token=None)

Bases: object

מנתח ריפוזיטורי GitHub ומציע שיפורים

פרמטרים:

github_token (str | None)

MAX_FILE_SIZE = 102400

MAX_FILES = 50

LARGE_FILE_LINES = 500

LONG_FUNCTION_LINES = 50

CODE_EXTENSIONS = {'.c', '.cpp', '.cs', '.go', '.java', '.js', '.jsx', '.kt', '.m', '.php', '.py', '.r', '.rb', '.rs', '.scala', '.swift', '.ts', '.tsx'}

CONFIG_FILES = {'Cargo.toml', 'Gemfile', 'Package.swift', 'Pipfile', 'build.gradle', 'composer.json', 'go.mod', 'package.json', 'pom.xml', 'pyproject.toml', 'requirements.txt'}

IMPORTANT_FILES = {'.dockerignore', '.github/workflows', '.gitignore', '.gitlab-ci.yml', 'Dockerfile', 'LICENSE', 'LICENSE.md', 'LICENSE.txt', 'README', 'README.md', 'README.rst', 'README.txt', 'azure-pipelines.yml', 'docker-compose.yaml', 'docker-compose.yml'}

__init__(github_token=None)

אתחול המנתח

פרמטרים:

github_token (str | None)

parse_github_url(url)

מחלץ owner ו-repo מ-URL של GitHub

Return type:

tuple[str, str]

פרמטרים:

url (str)

async fetch_and_analyze_repo(repo_url)

שולף ומנתח ריפוזיטורי מ-GitHub

Return type:

Dict[str, Any]

פרמטרים:

repo_url (str)

generate_improvement_suggestions(analysis_data)

מייצר הצעות לשיפור על בסיס הניתוח

Return type:

List[Dict[str, Any]]

פרמטרים:

analysis_data (Dict[str, Any])

Batch Processing

Large Files Handling

טיפול בקבצים גדולים עם ממשק כפתורים מתקדם Large Files Handler with Advanced Button Interface

class large_files_handler.LargeFilesHandler

Bases: object

מנהל קבצים גדולים עם ממשק מתקדם

__init__()

async show_large_files_menu(update, context, page=1)

מציג תפריט קבצים גדולים עם ניווט בין עמודים

Return type:

None

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

• page (int)

async handle_file_selection(update, context)

טיפול בבחירת קובץ גדול

Return type:

None

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

async view_large_file(update, context)

הצגת קובץ גדול - תצוגה מקדימה או שליחה כקובץ

Return type:

None

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

async download_large_file(update, context)

הורדת קובץ גדול

Return type:

None

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

async delete_large_file_confirm(update, context)

אישור מחיקת קובץ גדול

Return type:

None

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

async delete_large_file(update, context)

מחיקת קובץ גדול

Return type:

None

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

async show_file_info(update, context)

הצגת מידע מפורט על קובץ גדול

Return type:

None

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

async edit_large_file(update, context)

התחלת תהליך עריכת קובץ גדול

Return type:

int

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

Cache Management

מנהל Cache מתקדם עם Redis Advanced Cache Manager with Redis

class cache_manager.DynamicTTL

Bases: object

ניהול TTL דינמי לפי סוג תוכן וקונטקסט.

הערכים כאן מייצגים TTL בסיסי בשניות עבור סוגי תוכן שכיחים.

BASE_TTL: Dict[str, int] = {'bookmarks': 120, 'collections_detail': 30, 'collections_items': 180, 'collections_list': 60, 'file_content': 3600, 'file_list': 300, 'markdown_render': 1800, 'public_stats': 600, 'search_results': 180, 'settings': 60, 'sticky_summary': 60, 'tags': 300, 'user_stats': 600}

classmethod calculate_ttl(content_type, context=None)

חשב TTL בסיסי מוכוון קונטקסט.

מבטיח גבולות בטוחים: מינימום 60 שניות, מקסימום 7200 (שעתיים).

Return type:

int

פרמטרים:

• content_type (str)

• context (Dict[str, Any] | None)

class cache_manager.ActivityBasedTTL

Bases: object

התאמת TTL לפי שעות פעילות (best-effort).

classmethod get_activity_multiplier()

Return type:

float

classmethod adjust_ttl(base_ttl)

Return type:

int

פרמטרים:

base_ttl (int)

cache_manager.build_cache_key(*parts)

בניית מפתח cache יעיל ומובנה מהחלקים הנתונים.

• מסנן חלקים ריקים

• ממיר לתווים בטוחים (רווחים/סלאשים)

• מגביל אורך ומוסיף hash קצר במידת הצורך

Return type:

str

פרמטרים:

parts (Any)

class cache_manager.CacheManager

Bases: object

מנהל Cache מתקדם עם Redis

__init__()

enable_debug_for(seconds)

הפעל/הארך חלון דיבאג זמני ללוגים של HIT/MISS/SET.

• אם seconds <= 0: מכבה דיבאג (debug_until=0)

• אחרת: מאריך (לא מקצר) את החלון כך שיסתיים לפחות בעוד seconds שניות מהעכשיו

מחזיר את timestamp החדש של debug_until.

Return type:

float

פרמטרים:

seconds (int)

connect()

התחברות ל-Redis

get(key)

קבלת ערך מה-cache

Return type:

Optional[Any]

פרמטרים:

key (str)

set(key, value, expire_seconds=300)

שמירת ערך ב-cache

Return type:

bool

פרמטרים:

• key (str)

• value (Any)

• expire_seconds (int)

set_dynamic(key, value, content_type, context=None)

שמירה ב-cache עם TTL דינמי ותיעוד מינימלי במטריקות/לוגים.

Return type:

bool

פרמטרים:

• key (str)

• value (Any)

• content_type (str)

• context (Dict[str, Any] | None)

get_with_refresh(key, refresh_func, *, content_type, context=None)

קריאה מ-cache; אם חסר – מחשב, שומר דינמית ומחזיר.

Return type:

Any

פרמטרים:

• key (str)

• refresh_func (Callable[[], Any])

• content_type (str)

• context (Dict[str, Any] | None)

delete(key)

מחיקת ערך מה-cache

Return type:

bool

פרמטרים:

key (str)

delete_pattern(pattern)

מחיקת כל המפתחות שמתאימים לתבנית

Return type:

int

פרמטרים:

pattern (str)

invalidate_user_cache(user_id)

מחיקת כל ה-cache של משתמש ספציפי

Return type:

int

פרמטרים:

user_id (int)

clear_all()

ניקוי כל המטמון באופן מבוקר.

• אם Redis מושבת – מחזיר 0.

• אם Redis פעיל – מוחק את כל המפתחות באמצעות SCAN+DEL (best-effort).

Return type:

int

invalidate_file_related(file_id, user_id=None)

ביטול קאש לפי קובץ: תוכן/רינדור/רשימות.

דפוסים נפוצים מעוגנים לאחור בהתאם למפתחות הקיימים בקוד.

Return type:

int

פרמטרים:

• file_id (str)

• user_id (int | str | None)

clear_stale(max_scan=1000, ttl_seconds_threshold=60)

מחיקת מפתחות שכבר עומדים לפוג (”stale“) בצורה עדינה.

היגיון: - אם Redis מושבת – החזר 0. - סריקה מדורגת (SCAN) של עד max_scan מפתחות. - מחיקה רק למפתחות עם TTL חיובי קטן מ-ttl_seconds_threshold, או TTL שלילי המציין שאינו קיים. - לא מוחקים מפתחות ללא TTL (ttl == -1) כדי להימנע מפגיעה בקאש ארוך-חיים.

Return type:

int

פרמטרים:

• max_scan (int)

• ttl_seconds_threshold (int)

get_stats()

סטטיסטיקות cache

Return type:

Dict[str, Any]

cache_manager.dynamic_cache(content_type, key_prefix=None)

דקורטור ל-caching דינמי ל-Flask endpoints.

• בונה מפתח קאש יציב הכולל משתמש/נתיב/פרמטרים

• שומר רק טיפוסים serializable; עבור Response עם JSON שומר את ה-data בלבד

• Fail-open: לעולם לא מפיל endpoint על בעיות קאש

Return type:

Callable[[Callable[[ParamSpec(P)], TypeVar(R)]], Callable[[ParamSpec(P)], TypeVar(R)]]

פרמטרים:

• content_type (str)

• key_prefix (str | None)

cache_manager.cached(expire_seconds=300, key_prefix='default')

דקורטור לcaching פונקציות

פרמטרים:

• expire_seconds (int)

• key_prefix (str)

cache_manager.async_cached(expire_seconds=300, key_prefix='default')

דקורטור לcaching פונקציות async

פרמטרים:

• expire_seconds (int)

• key_prefix (str)

פקודות ניהול Cache לבוט Cache Management Commands for Bot

async cache_commands.cache_stats_command(update, context)

הצגת סטטיסטיקות cache

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

async cache_commands.clear_cache_command(update, context)

ניקוי cache של המשתמש

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

cache_commands.setup_cache_handlers(application)

הוספת handlers לפקודות cache

async cache_commands.cache_warm_command(update, context)

חימום קאש מהיר לסטטיסטיקות משתמש (/cache_warm).

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

async cache_commands.debug_cache_command(update, context)

/debug_cache <seconds> – הפעלת לוגים זמניים של HIT/MISS/SET (מנהלים בלבד).

שימוש: - /debug_cache 300 (5 דקות) - /debug_cache 0 (כיבוי)

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

User Statistics

class user_stats.UserStats

Bases: object

__init__()

log_user(user_id, username=None, weight=1)

רישום משתמש ב-MongoDB עם משקל לדגימה (weight).

פרמטרים:

weight (int)

get_weekly_stats()

סטטיסטיקת שבוע אחרון מ-MongoDB

get_all_time_stats()

סטטיסטיקות כלליות מ-MongoDB

Activity Reporting

קובץ פשוט לדיווח פעילות - העתק את הקובץ הזה לכל בוט

activity_reporter.get_mongo_client(mongodb_uri)

החזרת מופע MongoClient יחיד (singleton) לכל האפליקציה.

בכל קריאה מחזיר את אותו אובייקט, ויוצר רק בפעם הראשונה.

פרמטרים:

mongodb_uri (str)

activity_reporter.close_mongo_client()

סגירת החיבור הגלובלי בבטחה בזמן כיבוי השירות.

Return type:

None

class activity_reporter.SimpleActivityReporter(mongodb_uri, service_id, service_name=None)

Bases: object

__init__(mongodb_uri, service_id, service_name=None)

mongodb_uri: חיבור למונגו (אותו מהבוט המרכזי) service_id: מזהה השירות ב-Render service_name: שם הבוט (אופציונלי)

report_activity(user_id)

דיווח פעילות פשוט

activity_reporter.create_reporter(mongodb_uri, service_id, service_name=None)

יצירת reporter פשוט

Utilities

פונקציות עזר כלליות לבוט שומר קבצי קוד General Utility Functions for Code Keeper Bot

class utils.CodeErrorLogger

Bases: object

מערכת לוגים ייעודית לשגיאות עיבוד קוד

__init__()

log_code_processing_error(user_id, error_type, error_message, context=None)

רישום שגיאות עיבוד קוד

Return type:

None

פרמטרים:

• user_id (int)

• error_type (str)

• error_message (str)

• context (Dict[str, Any] | None)

log_code_activity(user_id, activity_type, details=None)

רישום פעילות עיבוד קוד

Return type:

None

פרמטרים:

• user_id (int)

• activity_type (str)

• details (Dict[str, Any] | None)

log_validation_failure(user_id, code_length, error_reason)

רישום כשל באימות קוד

פרמטרים:

• user_id (int)

• code_length (int)

• error_reason (str)

log_sanitization_success(user_id, original_length, cleaned_length)

רישום הצלחה בסניטציה

פרמטרים:

• user_id (int)

• original_length (int)

• cleaned_length (int)

class utils.TimeUtils

Bases: object

כלים לעבודה עם זמן ותאריכים

static format_relative_time(dt)

פורמט זמן יחסי (לפני 5 דקות, אתמול וכו«)

Return type:

str

פרמטרים:

dt (datetime)

static parse_date_string(date_str)

פרסור מחרוזת תאריך לאובייקט datetime

Return type:

Optional[datetime]

פרמטרים:

date_str (str)

static get_time_ranges(period)

קבלת טווח זמנים לפי תקופה

Return type:

Tuple[datetime, datetime]

פרמטרים:

period (str)

class utils.TextUtils

Bases: object

כלים לעבודה עם טקסט

static truncate_text(text, max_length=100, suffix='...')

קיצור טקסט עם סיומת

Return type:

str

פרמטרים:

• text (str)

• max_length (int)

• suffix (str)

static escape_markdown(text, version=2)

הגנה על תווים מיוחדים ב-Markdown

Return type:

str

פרמטרים:

• text (str)

• version (int)

static clean_filename(filename)

ניקוי שם קובץ מתווים לא חוקיים

Return type:

str

פרמטרים:

filename (str)

static extract_hashtags(text)

חילוץ תגיות מטקסט

Return type:

List[str]

פרמטרים:

text (str)

static highlight_text(text, query, tag='**')

הדגשת מילות חיפוש בטקסט

Return type:

str

פרמטרים:

• text (str)

• query (str)

• tag (str)

static format_file_size(size_bytes)

פורמט גודל קובץ (bytes -> KB/MB/GB)

Return type:

str

פרמטרים:

size_bytes (int)

static pluralize_hebrew(count, singular, plural)

צורת רבים עבריות

Return type:

str

פרמטרים:

• count (int)

• singular (str)

• plural (str)

class utils.SecurityUtils

Bases: object

כלים אמינות ובטיחות

static generate_secure_token(length=32)

יצירת טוקן מאובטח

Return type:

str

פרמטרים:

length (int)

static hash_content(content, algorithm='sha256')

יצירת hash לתוכן

Return type:

str

פרמטרים:

• content (str)

• algorithm (str)

static validate_user_input(text, max_length=10000, forbidden_patterns=None)

בדיקת קלט משתמש

Return type:

bool

פרמטרים:

• text (str)

• max_length (int)

• forbidden_patterns (List[str] | None)

static sanitize_code(code)

ניקוי קוד מתוכן מסוכן (בסיסי)

Return type:

str

פרמטרים:

code (str)

class utils.TelegramUtils

Bases: object

כלים לעבודה עם Telegram

async static send_typing_action(update, context)

שליחת אקשן »כותב…«

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

async static send_document_action(update, context)

שליחת אקשן »שולח מסמך…«

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

async static safe_answer(query, text=None, show_alert=False, cache_time=None)

מענה בטוח ל-CallbackQuery: מתעלם משגיאות »Query is too old«/«query_id_invalid«.

Return type:

None

פרמטרים:

• text (str | None)

• show_alert (bool)

• cache_time (int | None)

static get_user_mention(user)

קבלת מנשן למשתמש

Return type:

str

פרמטרים:

user (telegram.User)

static split_long_message(text, max_length=4096)

חלוקת הודעה ארוכה לחלקים

Return type:

List[str]

פרמטרים:

• text (str)

• max_length (int)

async static safe_edit_message_text(query, text, reply_markup=None, parse_mode=None)

עריכת טקסט הודעה בבטיחות: מתעלם משגיאת »Message is not modified«.

תומך גם במימושי בדיקות שבהם edit_message_text היא פונקציה סינכרונית שמחזירה None (לא awaitable), וגם במימושים אסינכרוניים רגילים.

Return type:

None

פרמטרים:

• text (str)

• parse_mode (str | None)

async static safe_edit_message_reply_markup(query, reply_markup=None)

עריכת מקלדת הודעה בבטיחות: מתעלם משגיאת »Message is not modified«.

Return type:

None

static extract_message_text_preserve_markdown(message, *, reconstruct_from_entities=True)

שחזור טקסט ההודעה תוך ניסיון להחזיר את מה שהמשתמש התכוון מבחינת תווי Markdown.

עקרונות:

• ברירת מחדל: נשתמש ב-text/caption (התוכן הגולמי כפי שנשלח לשרת לאחר עיבוד Markdown). זאת כדי לא לשמור מחרוזת ”מרונדרת“ (למשל *_name_*), שאינה משקפת קלט משתמש.

• במידה ו-reconstruct_from_entities=True ויש ישויות עיצוב (bold/italic), ננסה לשחזר תווי Markdown שהיוו כנראה את מקור העיצוב ע“י הוספת תחיליות/סיומות סביב הטקסט שסומן. מיפוי פשוט: bold → "__", italic → "_". שאר ישויות נשמרות כפי שהן.

• אם יש כיתוב (caption), נשתמש במקבילות caption_entities.

Return type:

str

פרמטרים:

• message (telegram.Message)

• reconstruct_from_entities (bool)

class utils.CallbackQueryGuard

Bases: object

Guard גורף ללחיצות כפולות על כפתורי CallbackQuery.

מבוסס על טביעת אצבע של המשתמש/הודעה/הנתון (callback_data) כדי לחסום את אותה פעולה בחלון זמן קצר, בלי לחסום פעולות שונות.

DEFAULT_WINDOW_SECONDS: float = 1.2

static should_block(update, context, window_seconds=None)

בודק האם יש לחסום את העדכון כלחיצה כפולה.

אם זו אותה טביעת אצבע בתוך חלון הזמן – נחסום; אחרת נסמן ונאפשר.

Return type:

bool

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

• window_seconds (float | None)

async static should_block_async(update, context, window_seconds=None)

בודק בצורה אטומית (עם נעילה) אם לחסום לחיצה כפולה של אותו משתמש.

חסימה מבוססת חלון זמן פר-משתמש ועל אותה טביעת אצבע (משתמש/צ׳אט/הודעה/הנתון), כדי למנוע כפילויות אמיתיות בלי לחסום לחיצות שונות ברצף מהיר (UX).

Return type:

bool

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

• window_seconds (float | None)

class utils.AsyncUtils

Bases: object

כלים לעבודה אסינכרונית

async static run_with_timeout(coro, timeout=30.0)

הרצת פונקציה אסינכרונית עם timeout

פרמטרים:

timeout (float)

async static batch_process(items, process_func, batch_size=10, delay=0.1)

עיבוד פריטים בקבוצות

Return type:

List[Any]

פרמטרים:

• items (List[Any])

• process_func (Callable)

• batch_size (int)

• delay (float)

class utils.PerformanceUtils

Bases: object

כלים למדידת ביצועים

static timing_decorator(func)

דקורטור למדידת זמן ביצוע

static measure_time(operation_name)

מדידת זמן עם context manager

פרמטרים:

operation_name (str)

class utils.ValidationUtils

Bases: object

כלים לוולידציה

static is_valid_filename(filename)

בדיקת תקינות שם קובץ

Return type:

bool

פרמטרים:

filename (str)

static is_safe_code(code, programming_language)

בדיקה בסיסית של בטיחות קוד

Return type:

Tuple[bool, List[str]]

פרמטרים:

• code (str)

• programming_language (str)

class utils.FileUtils

Bases: object

כלים לעבודה עם קבצים

async static download_file(url, max_size=10485760)

הורדת קובץ מ-URL

Return type:

Optional[bytes]

פרמטרים:

• url (str)

• max_size (int)

static get_file_extension(filename)

קבלת סיומת קובץ

Return type:

str

פרמטרים:

filename (str)

static get_mime_type(filename)

קבלת MIME type של קובץ

Return type:

str

פרמטרים:

filename (str)

async static create_temp_file(content, suffix='')

יצירת קובץ זמני

Return type:

str

פרמטרים:

• content (str | bytes)

• suffix (str)

class utils.ConfigUtils

Bases: object

כלים לקונפיגורציה

static load_json_config(file_path, default=None)

טעינת קונפיגורציה מקובץ JSON

Return type:

Dict[str, Any]

פרמטרים:

• file_path (str)

• default (Dict[str, Any] | None)

static save_json_config(file_path, config)

שמירת קונפיגורציה לקובץ JSON

Return type:

bool

פרמטרים:

• file_path (str)

• config (Dict[str, Any])

class utils.CacheUtils

Bases: object

כלים לקאש זמני

classmethod set(key, value, ttl=300)

שמירה בקאש עם TTL (שניות)

פרמטרים:

• key (str)

• value (Any)

• ttl (int)

classmethod get(key, default=None)

קבלה מהקאש

Return type:

Any

פרמטרים:

• key (str)

• default (Any)

classmethod delete(key)

מחיקה מהקאש

פרמטרים:

key (str)

classmethod clear()

ניקוי כל הקאש

utils.get_memory_usage()

קבלת נתוני זיכרון

Return type:

Dict[str, Any]

utils.setup_logging(level='INFO', log_file=None)

הגדרת לוגים

Return type:

Logger

פרמטרים:

• level (str)

• log_file (str | None)

utils.generate_summary_stats(files_data)

יצירת סיכום סטטיסטיקות

Return type:

Dict[str, Any]

פרמטרים:

files_data (List[Dict[str, Any]])

utils.detect_language_from_filename(filename)

זיהוי שפת תכנות לפי סיומת הקובץ (Filename-only). נסה קודם את הדטקטור הדומייני כדי לשמור אחידות, ונפילה למיפוי מקומי לתאימות.

Return type:

str

פרמטרים:

filename (str)

utils.get_language_emoji(language)

מחזיר אימוג’י מתאים לשפת התכנות

Return type:

str

פרמטרים:

language (str)

class utils.SensitiveDataFilter(name='')

Bases: Filter

מסנן שמטשטש טוקנים ונתונים רגישים בלוגים.

filter(record)

Determine if the specified record is to be logged.

Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

Return type:

bool

פרמטרים:

record (LogRecord)

utils.install_sensitive_filter()

התקנת המסנן על כל ה-handlers הקיימים.

utils.normalize_code(text, *, strip_bom=True, normalize_newlines=True, replace_nbsp=True, replace_all_space_separators=True, remove_zero_width=True, remove_directional_marks=True, trim_trailing_whitespace=True, remove_other_format_chars=True, remove_escaped_format_escapes=True, remove_variation_selectors=False)

נרמול קוד לפני שמירה.

פעולות עיקריות:

• הסרת BOM בתחילת הטקסט

• המרת CRLF/CR ל-LF

• החלפת רווחים לא-שוברים (NBSP/NNBSP) לרווח רגיל

• הסרת תווי רוחב-אפס וסימוני כיוון (LRM/RLM/LRE/RLE/PDF/RLO/LRO/LRI/RLI/FSI/PDI)

• הסרת תווי בקרה (Cc) פרט ל-t, n, r

• הסרת רווחי סוף שורה

Return type:

str

פרמטרים:

• text (str)

• strip_bom (bool)

• normalize_newlines (bool)

• replace_nbsp (bool)

• replace_all_space_separators (bool)

• remove_zero_width (bool)

• remove_directional_marks (bool)

• trim_trailing_whitespace (bool)

• remove_other_format_chars (bool)

• remove_escaped_format_escapes (bool)

• remove_variation_selectors (bool)

Lazy Loading

Integrations

Terminal Commands

Terminal commands: sandboxed command execution via Docker containers.

terminal_commands.emit_event(event, severity='info', **fields)

פרמטרים:

• event (str)

• severity (str)

async terminal_commands.run_in_sandbox(command, timeout_sec=10, max_output_chars=3500)

Run a shell command inside a locked-down Docker container and return (rc, output).

Return type:

Tuple[int, str]

פרמטרים:

• command (str)

• timeout_sec (int)

• max_output_chars (int)

async terminal_commands.terminal_enter(update, context)

Enter terminal mode if Docker is available.

Return type:

int

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

async terminal_commands.terminal_exit(update, context)

Exit terminal mode.

Return type:

int

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

async terminal_commands.terminal_run_command(update, context)

Run a command string inside the sandbox and send the output.

Return type:

int

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

async terminal_commands.terminal_command(update, context)

/terminal command to enter terminal mode.

Return type:

int

פרמטרים:

• update (telegram.Update)

• context (telegram.ext.ContextTypes.DEFAULT_TYPE)

terminal_commands.setup_terminal_handlers(application)

Register terminal conversation handlers and commands (disabled on Render).

פרמטרים:

application (telegram.ext.Application)

Autocomplete Manager