chutils 3.4.1__tar.gz → 3.4.2__tar.gz

{chutils-3.4.1 → chutils-3.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chutils
-Version: 3.4.1
+Version: 3.4.2
 Summary: Набор простых и удобных утилит для Python, который избавляет от рутины при работе с конфигурацией и логированием в новых проектах.
 Author-email: Chu4hel <sergeiivanov636@gmail.com>
 License-Expression: MIT

{chutils-3.4.1 → chutils-3.4.2}/api_map.md

@@ -1,9 +1,9 @@
 ---
 chutils_version: 3.4.1
 project_version: 3.4.1
-git_commit: 824417aa80b19bbfbb6cbb86151e5139be92b981 (dirty)
-generated_at: 2026-07-28T19:53:16.120390+00:00
-project_hash: 1001ffd89333fcf5c07c42b89dfebc67f38e7574da9f7166e3845fa464c5bc81
+git_commit: 35b0abb02583ebebbd7a918dd74a5056d6b40c5c (dirty)
+generated_at: 2026-07-30T21:04:30.356972+00:00
+project_hash: 73c182750cd7e4d409a97fe4e3797cb39064637a44fe36638c5c113466639683
 ---
 
 # Public API Map: chutils

chutils-3.4.2/conductor/tracks/telegram_access_20260729/index.md

@@ -0,0 +1,5 @@
+# Track telegram_access_20260729 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

chutils-3.4.2/conductor/tracks/telegram_access_20260729/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "telegram_access_20260729",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-07-29T00:04:00Z",
+  "updated_at": "2026-07-29T00:04:00Z",
+  "description": "Безопасность и ограничение доступа для Telegram ботов: @admin_only, AdminFilter с fallback-ом на chutils config"
+}

chutils-3.4.2/conductor/tracks/telegram_access_20260729/plan.md

@@ -0,0 +1,18 @@
+# Implementation Plan: Telegram Bot Access Control (`telegram_access_20260729`)
+
+## Phase 1: Core Access Control Logic & Exception Hierarchy
+- [ ] Task: Create `chutils.exceptions.telegram` module with `TelegramAccessDeniedError`
+- [ ] Task: Create core `chutils.telegram.access` module with `is_admin()` predicate logic and config fallback
+- [ ] Task: Implement `@admin_only` decorator for sync/async handler functions with refusal handling options (`refusal_text`, `silent`, raise exception)
+- [ ] Task: Unit tests for core `is_admin` and `@admin_only` decorator
+- [ ] Task: Conductor - User Manual Verification 'Phase 1: Core Access Control' (Protocol in workflow.md)
+
+## Phase 2: Framework Integrations & Lazy Exports
+- [ ] Task: Implement `AdminFilter` for `aiogram 3.x` with safe import handling if `aiogram` is not installed
+- [ ] Task: Register lazy exports in `src/chutils/telegram/__init__.py` and root `src/chutils/__init__.py`
+- [ ] Task: Unit tests for `aiogram` filter and framework compatibility
+- [ ] Task: Conductor - User Manual Verification 'Phase 2: Framework Integrations' (Protocol in workflow.md)
+
+## Phase 3: Documentation & Indexing
+- [ ] Task: Document `chutils.telegram` usage in `docs/` and update `api_map.md` / `project_index.json`
+- [ ] Task: Conductor - User Manual Verification 'Phase 3: Documentation' (Protocol in workflow.md)

chutils-3.4.2/conductor/tracks/telegram_access_20260729/spec.md

@@ -0,0 +1,24 @@
+# Track Specification: Telegram Bot Access Control (`telegram_access_20260729`)
+
+## Overview
+Добавление модуля `chutils.telegram` с универсальным механизмом проверки прав доступа и ограничения вызовов для Telegram-ботов (`@admin_only`, `AdminFilter`). Подсистема решает задачу безопасного разграничения доступа админов/пользователей с автоматическим фоллбэком на конфигурацию `chutils` и поддержкой популярнейших фреймворков (`aiogram 3.x`, `python-telegram-bot`, `telebot`).
+
+## Functional Requirements
+- **Декоратор `@admin_only`**:
+  - Поддержка синхронных и асинхронных функций-хэндлеров.
+  - Поддержка явного списка `admin_ids` (int) и `admin_usernames` (str без/с `@`).
+  - Поддержка кастомной функции-предиката `is_admin_func(user_id, username) -> bool`.
+  - Автоматический fallback на конфигурацию `chutils`: чтение списка админов из `get_config_value("Telegram", "admin_ids")` / `admin_usernames` при отсутствии явных аргументов.
+- **Отказ в доступе (Refusal Handling)**:
+  - Настройка кастомного ответа (`refusal_text="⛔ Доступ запрещен"`).
+  - Поддержка тихого режима (`silent=True`), когда неавторизованные запросы игнорируются без ответа.
+  - Поддержка выброса исключения `TelegramAccessDeniedError` для тонкой обработки в Middleware.
+- **Интеграция с Telegram-фреймворками**:
+  - `AdminFilter` для `aiogram 3.x` (реализация `BaseFilter`).
+  - Универсальная функция-предикат `is_admin(user_id, username, ...)` для использования в `python-telegram-bot`, `telebot` и чистых Webhook/Polling обновлениях.
+- **Типизация и Zero-Any**:
+  - Полная типизация через Python 3.10+ unions (`int | str`), отсутствие `Any` в бизнес-логике.
+
+## Out of Scope
+- Хранение прав пользователей в БД (управление ролями).
+- Пагинаторы и UI-клавиатуры (будут вынесены в отдельные треки).

chutils-3.4.2/conductor/tracks/telegram_formatting_20260729/index.md

@@ -0,0 +1,5 @@
+# Track telegram_formatting_20260729 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

chutils-3.4.2/conductor/tracks/telegram_formatting_20260729/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "telegram_formatting_20260729",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-07-29T00:11:00Z",
+  "updated_at": "2026-07-29T00:11:00Z",
+  "description": "chutils.telegram.formatting: Экранирование MarkdownV2/HTML (escape_markdown, escape_html) и умное разбиение сообщений (smart_truncate)"
+}

chutils-3.4.2/conductor/tracks/telegram_formatting_20260729/plan.md

@@ -0,0 +1,17 @@
+# Implementation Plan: Telegram Safe Formatting & Message Truncation (`telegram_formatting_20260729`)
+
+## Phase 1: Core Escaping Functions & Unit Tests
+- [ ] Task: Create `chutils.telegram.formatting` module with `escape_markdown` and `escape_html`
+- [ ] Task: Write comprehensive unit tests for `escape_markdown` (v1/v2) and `escape_html`
+- [ ] Task: Conductor - User Manual Verification 'Phase 1: Escaping Functions' (Protocol in workflow.md)
+
+## Phase 2: Smart Truncation & Message Splitting
+- [ ] Task: Implement `smart_truncate` with code block (```) and HTML tag closure
+- [ ] Task: Implement `split_message` helper for splitting logs/long reports
+- [ ] Task: Export functions in `src/chutils/telegram/__init__.py` and root `src/chutils/__init__.py`
+- [ ] Task: Unit tests for `smart_truncate` and `split_message`
+- [ ] Task: Conductor - User Manual Verification 'Phase 2: Smart Truncation & Splitting' (Protocol in workflow.md)
+
+## Phase 3: Documentation & Indexing
+- [ ] Task: Add examples in `docs/` and update `api_map.md` / `project_index.json`
+- [ ] Task: Conductor - User Manual Verification 'Phase 3: Documentation' (Protocol in workflow.md)

chutils-3.4.2/conductor/tracks/telegram_formatting_20260729/spec.md

@@ -0,0 +1,14 @@
+# Track Specification: Telegram Safe Formatting & Message Truncation (`telegram_formatting_20260729`)
+
+## Overview
+Реализация модуля `chutils.telegram.formatting` для безопасной работы с разметкой сообщений Telegram. Модуль гарантирует защиту от ошибок `BadRequest: Can't parse entities` за счет надежного экранирования `MarkdownV2` / `HTML` и предотвращает вылеты по превышению 4096 символов благодаря умному сплиттингу сообщений с сохранением парности тегов и кодовых блоков.
+
+## Functional Requirements
+- **Экранирование символов (`escape_markdown` / `escape_html`)**:
+  - `escape_markdown(text, version=2)`: Экранирование спецсимволов (`_`, `*`, `[`, `]`, `(`, `)`, `~`, `` ` ``, `>`, `#`, `+`, `-`, `=`, `|`, `{`, `}`, `.`, `!`). Поддержка v1 и v2.
+  - `escape_html(text)`: Экранирование `<`, `>`, `&`, `"`.
+- **Умное разбиение сообщений (`smart_truncate` & `split_message`)**:
+  - `smart_truncate(text, max_length=4096)`: Обрезка текста до `max_length` с автоматическим закрытием незавершенных кодовых блоков (```) или HTML-тегов.
+  - `split_message(text, max_length=4096)`: Разбиение длинного текста/логов на список валидных чанков не превышающих `max_length` символов.
+- **Типизация**:
+  - Строгие аннотации типов Python 3.10+.

chutils-3.4.2/conductor/tracks/telegram_keyboard_20260729/index.md

@@ -0,0 +1,5 @@
+# Track telegram_keyboard_20260729 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

chutils-3.4.2/conductor/tracks/telegram_keyboard_20260729/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "telegram_keyboard_20260729",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-07-29T20:20:00Z",
+  "updated_at": "2026-07-29T20:20:00Z",
+  "description": "chutils.telegram.keyboard: build_inline_keyboard генератор сетки и PaginatorKeyboard для пагинации списков"
+}

chutils-3.4.2/conductor/tracks/telegram_keyboard_20260729/plan.md

@@ -0,0 +1,18 @@
+# Implementation Plan: Telegram Dynamic & Paginated Keyboards (`telegram_keyboard_20260729`)
+
+## Phase 1: Core Inline Keyboard Generator
+- [ ] Task: Create `chutils.telegram.keyboard` module with `build_inline_keyboard` function
+- [ ] Task: Support grid alignment (`buttons_per_row`), custom URLs, and dict/tuple inputs
+- [ ] Task: Unit tests for `build_inline_keyboard` logic
+- [ ] Task: Conductor - User Manual Verification 'Phase 1: Core Inline Keyboard' (Protocol in workflow.md)
+
+## Phase 2: PaginatorKeyboard & Framework Integrations
+- [ ] Task: Implement `PaginatorKeyboard` class with page slicing, state labels, and navigation buttons
+- [ ] Task: Support `footer_buttons` and `aiogram` `InlineKeyboardMarkup` conversion
+- [ ] Task: Export symbols in `src/chutils/telegram/__init__.py` and root `src/chutils/__init__.py`
+- [ ] Task: Unit tests for `PaginatorKeyboard` pagination and navigation
+- [ ] Task: Conductor - User Manual Verification 'Phase 2: PaginatorKeyboard & Integration' (Protocol in workflow.md)
+
+## Phase 3: Documentation & Indexing
+- [ ] Task: Add examples in `docs/` and update `api_map.md` / `project_index.json`
+- [ ] Task: Conductor - User Manual Verification 'Phase 3: Documentation' (Protocol in workflow.md)

chutils-3.4.2/conductor/tracks/telegram_keyboard_20260729/spec.md

@@ -0,0 +1,15 @@
+# Track Specification: Telegram Dynamic & Paginated Keyboards (`telegram_keyboard_20260729`)
+
+## Overview
+Реализация модуля `chutils.telegram.keyboard` для конструирования динамических Inline-клавиатур и управления пагинацией списков. Подсистема исключает рутинное написание сетки кнопок, автоматизирует навигацию (`« Назад`, `1/5`, `Вперед »`) и поддерживает экспорт в формате чистых Python-словарей или готовых `InlineKeyboardMarkup` для `aiogram 3.x`.
+
+## Functional Requirements
+- **Генератор сетки `build_inline_keyboard`**:
+  - Принимает список элементов `(text, callback_data)` или словарей `{"text": ..., "callback_data": ..., "url": ...}`.
+  - Автоматическое разбиение на ряды с помощью параметра `buttons_per_row` (по умолчанию 2).
+  - Опция `as_aiogram` для приведения к объекту `InlineKeyboardMarkup` при наличии `aiogram`.
+- **Пагинатор `PaginatorKeyboard`**:
+  - Универсальный класс пагинации для списков любых объектов.
+  - Генерация строки состояния (например, `1/5`) и навигационных кнопок (`«`, `»`).
+  - Метод `get_page(page: int, per_page: int)` для сбора подмножества данных.
+  - Поддержка прикрепления дополнительных фиктивных или постоянных кнопок (`footer_buttons`, например "Закрыть").

chutils-3.4.2/conductor/tracks/telegram_logging_20260729/index.md

@@ -0,0 +1,5 @@
+# Track telegram_logging_20260729 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

chutils-3.4.2/conductor/tracks/telegram_logging_20260729/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "telegram_logging_20260729",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-07-29T00:09:00Z",
+  "updated_at": "2026-07-29T00:09:00Z",
+  "description": "TelegramLogFilter / TelegramMiddleware: Автоматическое логирование команд, нажатий inline-кнопок и авто-проброс контекста в chutils.logger"
+}

chutils-3.4.2/conductor/tracks/telegram_logging_20260729/plan.md

@@ -0,0 +1,17 @@
+# Implementation Plan: Telegram Update Logging & Context Tracing (`telegram_logging_20260729`)
+
+## Phase 1: Core Context Tracing Engine & Decorator
+- [ ] Task: Create `chutils.telegram.logging` module with context binding logic (`telegram_user_id`, `chat_id`, `update_id`)
+- [ ] Task: Implement `trace_telegram_update` sync/async context manager and decorator with `execution_time_ms` calculation and PII masking
+- [ ] Task: Unit tests for core `trace_telegram_update` and logger context binding
+- [ ] Task: Conductor - User Manual Verification 'Phase 1: Core Context Tracing Engine' (Protocol in workflow.md)
+
+## Phase 2: aiogram Middleware & Lazy Exports
+- [ ] Task: Implement `TelegramLoggingMiddleware` for `aiogram 3.x`
+- [ ] Task: Register lazy exports in `src/chutils/telegram/__init__.py` and root `src/chutils/__init__.py`
+- [ ] Task: Unit tests for `aiogram` logging middleware
+- [ ] Task: Conductor - User Manual Verification 'Phase 2: aiogram Middleware' (Protocol in workflow.md)
+
+## Phase 3: Documentation & Indexing
+- [ ] Task: Add examples in `docs/` and update `api_map.md` / `project_index.json`
+- [ ] Task: Conductor - User Manual Verification 'Phase 3: Documentation' (Protocol in workflow.md)

chutils-3.4.2/conductor/tracks/telegram_logging_20260729/spec.md

@@ -0,0 +1,16 @@
+# Track Specification: Telegram Update Logging & Context Tracing (`telegram_logging_20260729`)
+
+## Overview
+Добавление подсистемы прозрачного логирования и контекстного трейсинга Telegram-апдейтов в `chutils.telegram.logging`. Модуль автоматически обогащает все логи, вызывемые внутри хэндлеров, контекстными полями `telegram_user_id` и `chat_id`, измеряет время выполнения (`execution_time_ms`), маскирует PII-данные и предоставляет удобную мидлварь для `aiogram 3.x`.
+
+## Functional Requirements
+- **Авто-проброс контекста (`chutils.logger.bind_context`)**:
+  - При получении любого апдейта автоматически устанавливается локальный контекст потока/таски (`telegram_user_id`, `chat_id`, `update_id`).
+  - Гарантированный сброс контекста (cleanup) после завершения работы хэндлера.
+- **Метрики и структура логов**:
+  - Логирование успешных команд, нажатий inline-кнопок и необработанных исключений.
+  - Измерение точности выполнения в миллисекундах (`execution_time_ms`).
+  - Маскирование PII через `chutils.logger.masking`.
+- **Интеграции с фреймворками**:
+  - `TelegramLoggingMiddleware` для `aiogram 3.x` (Outer / Inner Middleware).
+  - Декоратор и асинхронный контекстный менеджер `trace_telegram_update` для `python-telegram-bot`, `telebot` и пользовательских скриптов.

chutils-3.4.2/conductor/tracks/telegram_media_20260729/index.md

@@ -0,0 +1,5 @@
+# Track telegram_media_20260729 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

chutils-3.4.2/conductor/tracks/telegram_media_20260729/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "telegram_media_20260729",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-07-29T20:23:00Z",
+  "updated_at": "2026-07-29T20:23:00Z",
+  "description": "chutils.telegram.media: download_user_file с автоматической проверкой resolve_safe_path и опцией отключения allow_unsafe_path"
+}

chutils-3.4.2/conductor/tracks/telegram_media_20260729/plan.md

@@ -0,0 +1,18 @@
+# Implementation Plan: Telegram Safe File Downloader (`telegram_media_20260729`)
+
+## Phase 1: Core File Download Logic & Path Safety
+- [ ] Task: Create `chutils.telegram.media` module with `download_user_file` function
+- [ ] Task: Integrate `chutils.fs.resolve_safe_path` and `safe_filename` with `allow_unsafe_path=False` toggle
+- [ ] Task: Implement file size validation (`max_size_bytes`) and HTTP/Bot API stream saving
+- [ ] Task: Unit tests for path traversal attacks, `allow_unsafe_path` override, and file size limits
+- [ ] Task: Conductor - User Manual Verification 'Phase 1: Core File Downloader' (Protocol in workflow.md)
+
+## Phase 2: Framework Integrations & Lazy Exports
+- [ ] Task: Support `aiogram 3.x` `Bot` instance and raw `bot_token` HTTP download fallback
+- [ ] Task: Export symbols in `src/chutils/telegram/__init__.py` and root `src/chutils/__init__.py`
+- [ ] Task: Unit tests for framework compatibility and download fallbacks
+- [ ] Task: Conductor - User Manual Verification 'Phase 2: Framework Support' (Protocol in workflow.md)
+
+## Phase 3: Documentation & Indexing
+- [ ] Task: Add examples in `docs/` and update `api_map.md` / `project_index.json`
+- [ ] Task: Conductor - User Manual Verification 'Phase 3: Documentation' (Protocol in workflow.md)

chutils-3.4.2/conductor/tracks/telegram_media_20260729/spec.md

@@ -0,0 +1,15 @@
+# Track Specification: Telegram Safe File Downloader (`telegram_media_20260729`)
+
+## Overview
+Реализация модуля `chutils.telegram.media` для безопасного выкачивания файлов пользователей из Telegram (`download_user_file`). Модуль решает проблему уязвимости Path Traversal при передаче имени файла пользователем через механизмы `chutils.fs.resolve_safe_path` и `safe_filename`, с опциональной возможностью отключения защиты разработчиком (`allow_unsafe_path=True`).
+
+## Functional Requirements
+- **Функция `download_user_file`**:
+  - Принимает `bot` (aiogram/python-telegram-bot или bot_token), `file_id`, `target_dir` и `custom_filename` (опционально).
+  - Интеграция с `chutils.fs.resolve_safe_path`: гарантирует, что итоговый файл сохраняется строго в пределах `target_dir`.
+  - Защита от Path Traversal: санитизация имени файла (удаление `../`, `..\`, замена через `safe_filename`).
+  - Опция отключения: параметр `allow_unsafe_path: bool = False`, позволяющий разработчику при необходимости отключить проверку с записью предупреждения в лог (`logger.warning`).
+  - Контроль размера файла: `max_size_bytes: int | None` с выбросом `ChutilsException` при превышении.
+- **Типизация и исключения**:
+  - Поддержка `async def` и `def` вызова.
+  - Понятные ошибки при недоступности файла или нарушении безопасности.

chutils-3.4.2/conductor/tracks/telegram_notifier_20260729/index.md

@@ -0,0 +1,5 @@
+# Track telegram_notifier_20260729 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

chutils-3.4.2/conductor/tracks/telegram_notifier_20260729/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "telegram_notifier_20260729",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-07-29T00:13:00Z",
+  "updated_at": "2026-07-29T00:13:00Z",
+  "description": "chutils.telegram.notifier: TelegramLogHandler для алертов об ошибках со стеком и HealthCheckAlertBridge для моста с chutils.diagnostics"
+}

chutils-3.4.2/conductor/tracks/telegram_notifier_20260729/plan.md

@@ -0,0 +1,17 @@
+# Implementation Plan: Telegram Admin Notifications & Diagnostics Alert Bridge (`telegram_notifier_20260729`)
+
+## Phase 1: TelegramLogHandler & Alert Throttling
+- [ ] Task: Create `chutils.telegram.notifier` module with `TelegramLogHandler` class for standard `logging`
+- [ ] Task: Implement rate-limiting / deduplication of log alerts to prevent spam during cascading failures
+- [ ] Task: Unit tests for `TelegramLogHandler` formatting, rate-limiting, and error handling
+- [ ] Task: Conductor - User Manual Verification 'Phase 1: TelegramLogHandler' (Protocol in workflow.md)
+
+## Phase 2: HealthCheckAlertBridge & Diagnostics Integration
+- [ ] Task: Implement `HealthCheckAlertBridge` connected to `chutils.diagnostics`
+- [ ] Task: Export symbols in `src/chutils/telegram/__init__.py` and root `src/chutils/__init__.py`
+- [ ] Task: Unit tests for `HealthCheckAlertBridge` notification triggers
+- [ ] Task: Conductor - User Manual Verification 'Phase 2: HealthCheckAlertBridge' (Protocol in workflow.md)
+
+## Phase 3: Documentation & Indexing
+- [ ] Task: Add examples in `docs/` and update `api_map.md` / `project_index.json`
+- [ ] Task: Conductor - User Manual Verification 'Phase 3: Documentation' (Protocol in workflow.md)

chutils-3.4.2/conductor/tracks/telegram_notifier_20260729/spec.md

@@ -0,0 +1,18 @@
+# Track Specification: Telegram Admin Notifications & Diagnostics Alert Bridge (`telegram_notifier_20260729`)
+
+## Overview
+Реализация модуля `chutils.telegram.notifier` для немедленного оповещения администраторов о критических сбоях и проблемах здоровья приложения в Telegram. Модуль содержит встроенный лог-хэндлер `TelegramLogHandler` с защитой от флуда и мост `HealthCheckAlertBridge` для отправки алертов при деградации проверок `chutils.diagnostics`.
+
+## Functional Requirements
+- **Лог-хэндлер `TelegramLogHandler`**:
+  - Перехват исключений уровня `ERROR` / `CRITICAL`.
+  - Форматирование сообщений с трейсбэками, именем модуля и меткой времени.
+  - Встроенный Rate-Limiter (дросселирование одинаковых или каскадных алертов, например, не более N сообщений в минуту).
+  - Автоматическое чтение `bot_token` и `chat_id` из секции `[Telegram]` конфигурации `chutils`.
+- **Мост алертов диагностики `HealthCheckAlertBridge`**:
+  - Подписка на результаты проверок `chutils.diagnostics`.
+  - Автоматическая отправка уведомления при переходах статусов здоровья в `DEGRADED` или `UNHEALTHY`.
+  - Информативные алерты с форматированием деталей сбоя.
+- **Асинхронность и изоляция**:
+  - Отправка алертов не блокирует основной поток приложения (неблокирующий I/O или фоновые таски).
+  - Ошибки отправки самого Telegram API не падают с крашем основного приложения.

chutils-3.4.2/conductor/tracks/telegram_ratelimit_20260729/index.md

@@ -0,0 +1,5 @@
+# Track telegram_ratelimit_20260729 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

chutils-3.4.2/conductor/tracks/telegram_ratelimit_20260729/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "telegram_ratelimit_20260729",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-07-29T00:06:00Z",
+  "updated_at": "2026-07-29T00:06:00Z",
+  "description": "@rate_limit(rate=3, per=60): Защита от спама/флуда пользователей с автоматической отправкой сообщения 'Пожалуйста, подождите X сек.'"
+}

chutils-3.4.2/conductor/tracks/telegram_ratelimit_20260729/plan.md

@@ -0,0 +1,19 @@
+# Implementation Plan: Telegram Bot Rate Limiting & Throttling (`telegram_ratelimit_20260729`)
+
+## Phase 1: Core Telegram Rate Limiter Engine & Decorator
+- [ ] Task: Create `chutils.telegram.rate_limit` module with `TelegramRateLimiter` class wrapping `chutils.decorators.rate_limit`
+- [ ] Task: Implement `wait_sec` calculation logic and template formatting (`{wait_sec}`)
+- [ ] Task: Implement `@tg_rate_limit` decorator for sync/async handlers with scope (`user_id`/`chat_id`), `warning_text` and `silent` options
+- [ ] Task: Unit tests for `TelegramRateLimiter` and `@tg_rate_limit` decorator
+- [ ] Task: Conductor - User Manual Verification 'Phase 1: Core Telegram Rate Limiter Engine' (Protocol in workflow.md)
+
+## Phase 2: aiogram Middleware & Redis Storage Backend
+- [ ] Task: Implement `TelegramThrottlingMiddleware` for `aiogram 3.x`
+- [ ] Task: Support Redis / `chutils.cache` storage adapter for distributed rate limiting
+- [ ] Task: Export symbols in `src/chutils/telegram/__init__.py` and root `src/chutils/__init__.py`
+- [ ] Task: Unit tests for `aiogram` throttling middleware and Redis storage logic
+- [ ] Task: Conductor - User Manual Verification 'Phase 2: aiogram Middleware & Storage' (Protocol in workflow.md)
+
+## Phase 3: Documentation & Indexing
+- [ ] Task: Add examples in `docs/` and update `api_map.md` / `project_index.json`
+- [ ] Task: Conductor - User Manual Verification 'Phase 3: Documentation' (Protocol in workflow.md)

chutils-3.4.2/conductor/tracks/telegram_ratelimit_20260729/spec.md

@@ -0,0 +1,21 @@
+# Track Specification: Telegram Bot Rate Limiting & Throttling (`telegram_ratelimit_20260729`)
+
+## Overview
+Добавление специализированных механизмов защиты от флуда/спама в Telegram-ботах: декоратор `@tg_rate_limit(rate=3, per=60)` и `TelegramThrottlingMiddleware` (для `aiogram 3.x`). Утилита опирается на проверенное ядро `chutils.decorators.rate_limit`, высчитывает точное время ожидания `wait_sec` и автоматически высылает пользователю информативное предупреждение.
+
+## Functional Requirements
+- **Декоратор `@tg_rate_limit` & `TelegramThrottlingMiddleware`**:
+  - Параметры: `rate` (количество вызовов), `per` (период в секундах), `strategy` (`token_bucket` / `leaky_bucket`).
+  - Шаблон предупреждения: `warning_text="⏱ Пожалуйста, подождите {wait_sec} сек. перед повторной отправкой."`.
+  - Тихий режим: `silent=True` для полного отбрасывания спам-запросов без вызова Telegram API и расхода лимитов бота.
+  - Ключи лимитирования (`scope`): по `user_id` (дефолт), по `chat_id` или комбинированный `user_and_chat`.
+  - Динамический рассчет `wait_sec`: точное количество секунд, оставшихся до возобновления лимита.
+- **Хранение состояний (Storage Backends)**:
+  - `In-Memory` (по умолчанию, с TTL-очисткой).
+  - Поддержка внешних бэкендов (Redis / `chutils.cache`) для распределенных Telegram-ботов.
+- **Совместимость с фреймворками**:
+  - `TelegramThrottlingMiddleware` для `aiogram 3.x`.
+  - Синхронный и асинхронный декоратор `@tg_rate_limit` для `python-telegram-bot`, `telebot` и асинхронных хэндлеров.
+
+## Out of Scope
+- Глобальное ограничение скорости ответа самого Telegram API (обработка HTTP 429 от Telegram сервера).

chutils-3.4.2/conductor/tracks/telegram_send_file_20260729/index.md

@@ -0,0 +1,5 @@
+# Track telegram_send_file_20260729 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

chutils-3.4.2/conductor/tracks/telegram_send_file_20260729/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "telegram_send_file_20260729",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-07-29T20:27:00Z",
+  "updated_at": "2026-07-29T20:27:00Z",
+  "description": "chutils.telegram.media: send_telegram_file для отправки локальных файлов/папок с авто-архивацией в ZIP и безопасным экранированием подписи"
+}

chutils-3.4.2/conductor/tracks/telegram_send_file_20260729/plan.md

@@ -0,0 +1,18 @@
+# Implementation Plan: Telegram File Upload Helper (`telegram_send_file_20260729`)
+
+## Phase 1: Core send_telegram_file Implementation
+- [ ] Task: Create `send_telegram_file` function in `chutils.telegram.media`
+- [ ] Task: Integrate `resolve_safe_path` check and directory auto-zipping (`zip_folder`)
+- [ ] Task: Implement safe caption formatting, 1024 char truncation, and 50MB file size limit check
+- [ ] Task: Unit tests for path safety, directory auto-zipping, and caption truncation
+- [ ] Task: Conductor - User Manual Verification 'Phase 1: Core File Upload Logic' (Protocol in workflow.md)
+
+## Phase 2: Framework Integrations & Lazy Exports
+- [ ] Task: Support `aiogram 3.x` `Bot` sendDocument call and raw HTTP upload fallback
+- [ ] Task: Export `send_telegram_file` in `src/chutils/telegram/__init__.py` and root `src/chutils/__init__.py`
+- [ ] Task: Unit tests for framework compatibility and fallback mechanisms
+- [ ] Task: Conductor - User Manual Verification 'Phase 2: Framework Integrations' (Protocol in workflow.md)
+
+## Phase 3: Documentation & Indexing
+- [ ] Task: Add examples in `docs/` and update `api_map.md` / `project_index.json`
+- [ ] Task: Conductor - User Manual Verification 'Phase 3: Documentation' (Protocol in workflow.md)

chutils-3.4.2/conductor/tracks/telegram_send_file_20260729/spec.md

@@ -0,0 +1,14 @@
+# Track Specification: Telegram File Upload Helper (`telegram_send_file_20260729`)
+
+## Overview
+Реализация функции `send_telegram_file` в подсистеме `chutils.telegram.media` для надежной и безопасной отправки локальных файлов и директорий из приложения в Telegram. Функция берет на себя защиту от Path Traversal, экранирование и обрезку подписей (`caption`), контроль лимитов размера Telegram API (50 МБ) и авто-упаковку папок в ZIP-архивы.
+
+## Functional Requirements
+- **Функция `send_telegram_file`**:
+  - Аргументы: `bot`, `chat_id: int | str`, `file_path: str | Path`, `caption: str | None = None`, `parse_mode: str | None = None`, `allow_unsafe_path: bool = False`.
+  - Проверка безопасности пути через `chutils.fs.resolve_safe_path()` (с возможностью отключения через `allow_unsafe_path=True`).
+  - Авто-упаковка: если `file_path` указывает на папку, функция автоматически создает временный ZIP-архив через `chutils.fs.zip_folder` и отправляет его как файл.
+  - Обработка подписи (`caption`): безопасное экранирование спецсимволов и обрезка текста под 1024 символа (`smart_truncate`) во избежание вылетов по `BadRequest`.
+  - Проверка размера: проверка превышения лимита ботов Telegram (50 МБ) перед вызовом API.
+- **Совместимость с фреймворками**:
+  - Поддержка экземпляров `Bot` (`aiogram 3.x`, `python-telegram-bot`) и отправка через прямой `HTTP POST` по `bot_token`.

chutils-3.4.2/conductor/tracks/telegram_whitelist_20260729/index.md

@@ -0,0 +1,5 @@
+# Track telegram_whitelist_20260729 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

chutils-3.4.2/conductor/tracks/telegram_whitelist_20260729/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "telegram_whitelist_20260729",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-07-29T00:07:00Z",
+  "updated_at": "2026-07-29T00:07:00Z",
+  "description": "SecretUserFilter: Разграничение прав по белым/черным спискам Telegram ID / хэндлов"
+}

chutils-3.4.2/conductor/tracks/telegram_whitelist_20260729/plan.md

@@ -0,0 +1,17 @@
+# Implementation Plan: Secret User & Access Whitelist/Blacklist Filter (`telegram_whitelist_20260729`)
+
+## Phase 1: Core Access List Engine & Decorator
+- [ ] Task: Create `chutils.telegram.whitelist` module with `AccessListManager` class supporting allow/block lists and file persistence
+- [ ] Task: Implement `@allowed_only` decorator with config fallback (`allowed_users`/`blocked_users`)
+- [ ] Task: Unit tests for `AccessListManager` and `@allowed_only` decorator
+- [ ] Task: Conductor - User Manual Verification 'Phase 1: Core Access List Engine' (Protocol in workflow.md)
+
+## Phase 2: aiogram Integration & Framework Support
+- [ ] Task: Implement `SecretUserFilter` for `aiogram 3.x`
+- [ ] Task: Export symbols in `src/chutils/telegram/__init__.py` and root `src/chutils/__init__.py`
+- [ ] Task: Unit tests for `aiogram` filter and framework compatibility
+- [ ] Task: Conductor - User Manual Verification 'Phase 2: aiogram Integration' (Protocol in workflow.md)
+
+## Phase 3: Documentation & Indexing
+- [ ] Task: Add examples in `docs/` and update `api_map.md` / `project_index.json`
+- [ ] Task: Conductor - User Manual Verification 'Phase 3: Documentation' (Protocol in workflow.md)

chutils-3.4.2/conductor/tracks/telegram_whitelist_20260729/spec.md

@@ -0,0 +1,19 @@
+# Track Specification: Secret User & Access Whitelist/Blacklist Filter (`telegram_whitelist_20260729`)
+
+## Overview
+Реализация специализированных фильтров белых и черных списков доступа для Telegram-ботов (`SecretUserFilter`, `@allowed_only`). Компонент позволяет ограничивать доступ к боту или конкретным фичам только определенной группе пользователей (по Telegram ID и @username), с поддержкой динамического пополнения/удаления записей и сохранения в файл/БД.
+
+## Functional Requirements
+- **Класс `SecretUserFilter` & Декоратор `@allowed_only`**:
+  - Фильтрация по `allowed_ids` (int) и `allowed_usernames` (str).
+  - Настройка черного списка: `blocked_ids` / `blocked_usernames`.
+  - Автоматический fallback на конфигурацию `chutils`: `get_config_value("Telegram", "allowed_users")` / `blocked_users`.
+- **Динамический менеджер списков (`AccessListManager`)**:
+  - Методы `allow_user(user_id_or_username)`, `block_user(user_id_or_username)`, `remove_user(...)`.
+  - Опциональное сохранение изменений в JSON-файл (`atomic_write`) или пользовательский провайдер.
+- **Интеграции с фреймворками**:
+  - `SecretUserFilter` для `aiogram 3.x` (реализация `BaseFilter`).
+  - `@allowed_only` для `python-telegram-bot`, `telebot` и кастомных асинхронных хэндлеров.
+
+## Out of Scope
+- Хранение сложных ролей и прав групп в СУБД (RBAC).