chutils 3.4.0__tar.gz → 3.4.2__tar.gz

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

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

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

@@ -1,9 +1,9 @@
 ---
-chutils_version: 3.3.2
-project_version: 3.3.2
-git_commit: 1056ddfc241c7c49c89d0e5ceb7c71b6a49fcb9e (dirty)
-generated_at: 2026-07-25T09:58:24.525089+00:00
-project_hash: c9fdfbcccbbcd7da26d504ea6a52c71ac54d3d6ac8ad3db65ab038e0112d8666
+chutils_version: 3.4.1
+project_version: 3.4.1
+git_commit: 35b0abb02583ebebbd7a918dd74a5056d6b40c5c (dirty)
+generated_at: 2026-07-30T21:04:30.356972+00:00
+project_hash: 73c182750cd7e4d409a97fe4e3797cb39064637a44fe36638c5c113466639683
 ---
 
 # Public API Map: chutils
@@ -88,7 +88,7 @@ project_hash: c9fdfbcccbbcd7da26d504ea6a52c71ac54d3d6ac8ad3db65ab038e0112d8666
 | `Scaffolder`                          | class    | `(self, module_name: 'str', output_dir: 'str \| None' = None, force: 'bool' = False) -> 'None'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Генератор слоев Чистой Архитектуры для нового модуля.                                                              |
 | `SecretError`                         | class    | `(self, message: str, hint: str \| None = None, **context: Any) -> None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Общая ошибка менеджера секретов.                                                                                   |
 | `SecretManager`                       | class    | `(self, service_name: 'str \| None' = None, prefix: 'str \| None' = None, auto_mask_logs: 'bool' = True, providers: 'list[SecretProvider] \| None' = None) -> 'None'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Универсальный менеджер для управления секретами через цепочку провайдеров.                                         |
-| `SecretMaskingFilter`                 | class    | `(self, name='')`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Фильтр для автоматического маскирования секретов в сообщениях логов.                                               |
+| `SecretMaskingFilter`                 | class    | `(self, name: 'str' = '', secrets: 'list[str] \| set[str] \| None' = None, patterns: 'list[str] \| set[str] \| None' = None) -> 'None'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Фильтр для автоматического маскирования секретов в сообщениях логов.                                               |
 | `SecretNotFoundError`                 | class    | `(self, message: str, hint: str \| None = None, **context: Any) -> None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Ошибка: секрет не найден.                                                                                          |
 | `SecretProviderError`                 | class    | `(self, message: str, hint: str \| None = None, **context: Any) -> None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Ошибка конкретного провайдера секретов (например, сбой keyring).                                                   |
 | `ServerSentEvent`                     | class    | `(self, id: 'str \| None' = None, event: 'str \| None' = None, data: 'str' = '', retry: 'int \| None' = None, raw: 'str' = '') -> None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Представляет собой отдельное событие Server-Sent Events (SSE).                                                     |

{chutils-3.4.0/conductor/archive/fallback_alias_20260707 → chutils-3.4.2/conductor/tracks/ai_context_opt_20260728}/index.md

@@ -1,4 +1,4 @@
-# Track fallback_alias_20260707 Context
+# Track ai_context_opt_20260728 Context
 
 - [Specification](./spec.md)
 - [Implementation Plan](./plan.md)

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

@@ -0,0 +1,8 @@
+{
+  "track_id": "ai_context_opt_20260728",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-07-28T21:09:22.614964",
+  "updated_at": "2026-07-28T21:09:22.614995",
+  "description": "Оптимизация AI-контекст генератора (.gitignore и инкрементальное обновление)"
+}

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

@@ -0,0 +1,17 @@
+# Implementation Plan - AI Context Generator Optimization (`ai_context_opt_20260728`)
+
+Оптимизация утилиты `chutils dev generate-context` с помощью `.gitignore` парсера и инкрементального AST-обновления.
+
+## Phase 1: Gitignore Parser (`src/chutils/dev/context/gitignore.py`)
+- [ ] Task: Добавить поддержку чтения и парсинга `.gitignore` файлов через `pathspec` или встроенный fnmatch-механизм в `src/chutils/dev/context/gitignore.py`.
+- [ ] Task: Интегрировать опцию `--gitignore` в команду CLI `generate-context` (`src/chutils/commands/dev.py`).
+
+## Phase 2: Incremental AST Indexer (`src/chutils/dev/context/incremental.py`)
+- [ ] Task: Реализовать получение списка измененных файлов через `git status` / `git diff` в `src/chutils/dev/context/incremental.py`.
+- [ ] Task: Реализовать логику частичной замены узлов AST для измененных файлов в `project_index.json` и `api_map.md`.
+- [ ] Task: Интегрировать флаги `--incremental` / `-i` в CLI утилиту `generate-context`.
+
+## Phase 3: Testing & Verification
+- [ ] Task: Написать unit-тесты для парсера `.gitignore` и инкрементальной генерации в `tests/unit/dev/test_context_generator.py`.
+- [ ] Task: Проверить работу команды через `uv run mypy src/chutils` и `uv run pytest tests/unit/dev/`.
+- [ ] Task: Обновить документацию в `docs/api.md` и перегенерировать `api_map.md`.

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

@@ -0,0 +1,23 @@
+# Specification: AI Context Generator Optimization (`ai_context_opt_20260728`)
+
+## 1. Overview
+Расширение возможностей утилиты `chutils dev generate-context` флагами `--gitignore` (учет игнорируемых Git файлов) и `--incremental` / `-i` (инкрементальное обновление семантических индексов AST на основе `git diff` / `git status`).
+
+## 2. Functional Requirements
+1. **Учет `.gitignore` (`--gitignore`)**:
+   - Чтение паттернов из файла `.gitignore` (а также корневых и вложенных `.gitignore` целевого проекта).
+   - Исключение подходящих под правила файлов и каталогов из сканирования наравне с `.chutilsignore`.
+2. **Инкрементальное обновление (`--incremental` / `-i`)**:
+   - Определение списка измененных или добавленных файлов с последнего Git-коммита (`git diff --name-only HEAD` / `git status`).
+   - Перепарсинг AST-дерева только для изменившихся файлов и частичное обновление структур `project_index.json` и `api_map.md` без полного перестроения индекса всей кодовой базы.
+3. **Безопасность и хэширование**:
+   - Автоматический пересчет хэша проекта после частичного обновления во избежание срабатывания `APIMapHashRule` в аудиторе.
+
+## 3. Non-Functional Requirements
+- Сокращение времени генерации контекста на крупных проектах (500+ файлов) в режиме `--incremental` более чем на 80%.
+- Полная совместимость со существующим CLI-интерфейсом `chutils dev generate-context`.
+
+## 4. Acceptance Criteria
+- [ ] Флаг `--gitignore` отсеивает `build/`, `.venv/` и файлы, указанные в `.gitignore`.
+- [ ] Флаг `--incremental` обновляет метаданные AST только для измененных файлов в `project_index.json` и `api_map.md`.
+- [ ] Тесты в `tests/unit/dev/test_context_generator.py` подтверждают правильность отбора файлов.

{chutils-3.4.0/conductor/archive/config_remote_push_20260702 → chutils-3.4.2/conductor/tracks/async_lifecycle_20260728}/index.md

@@ -1,4 +1,4 @@
-# Track config_remote_push_20260702 Context
+# Track async_lifecycle_20260728 Context
 
 - [Specification](./spec.md)
 - [Implementation Plan](./plan.md)

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

@@ -0,0 +1,8 @@
+{
+  "track_id": "async_lifecycle_20260728",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-07-28T21:02:11.640486",
+  "updated_at": "2026-07-28T21:02:11.640546",
+  "description": "Асинхронный контекстный менеджер lifecycle()"
+}

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

@@ -0,0 +1,16 @@
+# Implementation Plan - Async Lifecycle Context Manager (`async_lifecycle_20260728`)
+
+Реализация асинхронного контекстного менеджера `async_lifecycle` в `chutils.lifecycle`.
+
+## Phase 1: Lifecycle Context Implementation (`src/chutils/lifecycle.py`)
+- [ ] Task: Создать класс/функцию `AsyncLifecycleContext` и публичную функцию `lifecycle()` в `src/chutils/lifecycle.py`.
+- [ ] Task: Реализовать логику `__aenter__` (авто-подключение сигналов при `setup_signals=True`) и `__aexit__` (безопасный вызов `async_run_cleanup()`).
+- [ ] Task: Добавить поддержку опционального автоклининга подсистем (`db`, `tasks`, `logger`) при `auto_cleanup_subsystems=True`.
+
+## Phase 2: Unit Testing & Integration Verification
+- [ ] Task: Написать unit-тесты для `async with lifecycle()` с успешным завершением и сгенерированным исключением в `tests/unit/core/test_lifecycle.py`.
+- [ ] Task: Написать тесты перехвата сигналов ОС в контекстном менеджере.
+
+## Phase 3: Verification & Documentation
+- [ ] Task: Запустить `uv run mypy src/chutils` и `uv run pytest tests/unit/core/test_lifecycle.py`.
+- [ ] Task: Добавить примеры использования `async with lifecycle()` в `docs/api.md` и обновить `api_map.md`.

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

@@ -0,0 +1,26 @@
+# Specification: Async Lifecycle Context Manager (`async_lifecycle_20260728`)
+
+## 1. Overview
+Добавление контекстного менеджера `lifecycle()` / `async_lifecycle()` в модуль `chutils.lifecycle` для удобного и надежного управления ресурсами приложения с поддержкой `async with` (и синхронного `with`).
+
+## 2. Functional Requirements
+1. **Контекстный синтаксис**:
+   ```python
+   async with chutils.lifecycle(setup_signals=True, auto_cleanup_subsystems=True):
+       await app.run()
+   ```
+2. **Гибкие параметры управления**:
+   - `setup_signals: bool = True`: Автоматическое подключение перехвата сигналов `SIGINT`/`SIGTERM` при входе и сброс при выходе.
+   - `auto_cleanup_subsystems: bool = True`: Автоматический вызов функций очистки для связанных подсистем (`db`, `tasks`, `logger`).
+3. **Идемпотентность и поддержка Event Loop**:
+   - Безопасное выполнение в асинхронном контексте с ожиданием завершения всех коллбэков очистки в текущем петле событий (`asyncio.get_running_loop()`).
+   - Защита от повторного выполнения очистки, если она уже была запущена по сигналу ОС.
+
+## 3. Non-Functional Requirements
+- Совместимость с FastAPI Lifespan, Litestar, qasync (PyQt6) и asyncio CLI.
+- 100% строгая типизация (Zero-Any) и полная потокобезопасность.
+
+## 4. Acceptance Criteria
+- [ ] `async with lifecycle()` корректно выполняет зарегистрированные коллбэки при выходе из блока или при вызове `Ctrl+C`.
+- [ ] Параметры `setup_signals` и `auto_cleanup_subsystems` позволяют точно настраивать поведение контекста.
+- [ ] Добавлены модульные тесты в `tests/unit/core/test_lifecycle.py`.

{chutils-3.4.0/conductor/archive/qt_integration_20260521 → chutils-3.4.2/conductor/tracks/browser_profiles_20260728}/index.md

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

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

@@ -0,0 +1,8 @@
+{
+  "track_id": "browser_profiles_20260728",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-07-28T20:55:19.986167",
+  "updated_at": "2026-07-28T20:55:19.986187",
+  "description": "Поддержка родительских профилей браузеров (nodriver, playwright, selenium)"
+}

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

@@ -0,0 +1,23 @@
+# Implementation Plan - Browser Profiles Support (`browser_profiles_20260728`)
+
+Модуль управления, экспорта, импорта и переноса авторизованных сессий и профилей браузеров между `nodriver`, `playwright` и `selenium`.
+
+## Phase 1: Core Data Models & Serialization (`chutils.scraping.profiles.models`)
+- [ ] Task: Создать Pydantic-модели профилей `BrowserProfile`, `CookieData`, `StorageData`, `HeaderData` в `src/chutils/scraping/profiles/models.py`.
+- [ ] Task: Реализовать методы упаковывания/распаковывания `.chprofile` архивов с поддержкой Fernet-шифрования (`chutils.crypto`) в `src/chutils/scraping/profiles/storage.py`.
+- [ ] Task: Написать unit-тесты для сериализации, шифрования и распаковки `BrowserProfile` в `tests/unit/scraping/test_profile_storage.py`.
+
+## Phase 2: Engine Adapters (nodriver, playwright, selenium)
+- [ ] Task: Реализовать адаптер экспорта/импорта для `playwright` (Async & Sync Contexts) в `src/chutils/scraping/profiles/adapters/playwright.py`.
+- [ ] Task: Реализовать адаптер экспорта/импорта для `nodriver` через CDP в `src/chutils/scraping/profiles/adapters/nodriver.py`.
+- [ ] Task: Реализовать адаптер экспорта/импорта для `selenium`/`undetected_chromedriver` в `src/chutils/scraping/profiles/adapters/selenium.py`.
+- [ ] Task: Написать unit-тесты с моками для всех трех адаптеров движков в `tests/unit/scraping/test_profile_adapters.py`.
+
+## Phase 3: ProfileManager & Public API Integration
+- [ ] Task: Создать единый интерфейс `ProfileManager` в `src/chutils/scraping/profiles/manager.py` с методами `export_profile()`, `import_profile()`, `convert_profile()`.
+- [ ] Task: Экспортировать `BrowserProfile` и `ProfileManager` в `src/chutils/scraping/__init__.py` и `src/chutils/__init__.py` с поддержкой ленивой загрузки (PEP 562).
+- [ ] Task: Добавить интеграционные тесты конвертации профилей между движками в `tests/unit/scraping/test_profile_manager.py`.
+
+## Phase 4: Verification & Documentation
+- [ ] Task: Проверить проект через `uv run mypy src/chutils` и `uv run pytest`.
+- [ ] Task: Обновить документацию в `docs/scraping.md` и сгенерировать контекст через `uv run chutils dev generate-context --force -o api_map.md`.

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

@@ -0,0 +1,33 @@
+# Specification: Browser Profiles Export/Import (`chutils.scraping.profiles`)
+
+## 1. Overview
+Модуль `chutils.scraping.profiles` предназначен для экспорта, сохранения, конвертации и импорта авторизованных сессий и профилей браузеров между различными движками скрейпинга (`nodriver`, `playwright`, `selenium`/`undetected-chromedriver`).
+
+## 2. Functional Requirements
+1. **Поддержка сессионных данных**:
+   - Экспорт и импорт авторизационных Cookie (с привязкой к доменам, SameSite, Secure, Expiry).
+   - Экспорт и импорт `LocalStorage` и `SessionStorage` для каждого домена.
+   - Экспорт и импорт структурированных данных `IndexedDB`.
+   - Сохранение и автоматическое восстановление метаданных браузера и HTTP-заголовков (`User-Agent`, `Accept-Language`, `Sec-CH-UA`).
+2. **Универсальный формат хранения**:
+   - Портативный `.chprofile` файл (ZIP-архив с JSON-структурой сессии и бинарными дампами).
+   - Опциональная интеграция с `chutils.crypto` для парольного шифрования профилей (Fernet).
+3. **Бесшовный переход между движками**:
+   - Метод `ProfileManager.export_from_nodriver(tab)` для извлечения куков и хранилищ через CDP (Chrome DevTools Protocol).
+   - Метод `ProfileManager.import_to_nodriver(tab, profile)` для подгрузки сессии в активную вкладку `nodriver`.
+   - Метод `ProfileManager.export_from_playwright(page/context)` для извлечения `storage_state` и данных хранилищ `playwright`.
+   - Метод `ProfileManager.import_to_playwright(context/page, profile)` для установки куков и выполнения скриптов восстановления хранилищ.
+   - Базовая поддержка экспорта/импорта для `selenium` / `undetected-chromedriver`.
+4. **Безопасность и обработка ошибок**:
+   - При наличии несериализуемых данных в `IndexedDB` применяется Safe Fallback с журналированием предупреждения в лог без остановки работы.
+   - При отсутствии установленных библиотек (`playwright`, `nodriver`, `selenium`) выбрасываются понятные `OptionalDependencyError`.
+
+## 3. Non-Functional Requirements
+- 100% покрытие аннотациями типов без использования `Any` в бизнес-логике.
+- Потоко- и асинхронная безопасность (`asyncio.Lock` при операциях со Storage).
+- Модульные тесты на замену и конвертацию формата между `nodriver` и `playwright`.
+
+## 4. Acceptance Criteria
+- [ ] Профиль, экспортированный из `nodriver`, успешно восстанавливает авторизованную сессию и куки в `playwright` (и наоборот).
+- [ ] Экспортированный профиль корректно сохраняется в шифрованный `.chprofile` и распаковывается по паролю.
+- [ ] Ошибки несериализуемых значений Storage обрабатываются с вызовом `logger.warning()` без падения приложения.

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

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

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

@@ -0,0 +1,8 @@
+{
+  "track_id": "queue_monitoring_20260728",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-07-28T20:58:30.182743",
+  "updated_at": "2026-07-28T20:58:30.182776",
+  "description": "Мониторинг очередей задач и воркеров через Prometheus"
+}

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

@@ -0,0 +1,16 @@
+# Implementation Plan - Queue & Worker Prometheus Monitoring (`queue_monitoring_20260728`)
+
+Внедрение мониторинга очередей задач и пула воркеров через `chutils.metrics`.
+
+## Phase 1: Queue Metrics Collector (`src/chutils/scraping/concurrency/metrics.py`)
+- [ ] Task: Создать модуль `src/chutils/scraping/concurrency/metrics.py` с объявлением метрик `QueueMetricsCollector`.
+- [ ] Task: Добавить поддержку параметра `enable_metrics: bool = True` в `BaseTaskQueue`, `InMemoryTaskQueue`, `PersistentTaskQueue` и `RedisTaskQueue`.
+- [ ] Task: Написать unit-тесты сбора метрик очередей в `tests/unit/scraping/test_queue_metrics.py`.
+
+## Phase 2: WorkerPool Integration
+- [ ] Task: Интегрировать измерение длительности выполнения задач `@timer` и подсчет статусов обработки в `WorkerPool` (`src/chutils/scraping/concurrency/worker.py`).
+- [ ] Task: Написать unit-тесты для `WorkerPool` с проверкой метрик в `tests/unit/scraping/test_worker_metrics.py`.
+
+## Phase 3: Verification & Documentation
+- [ ] Task: Запустить `uv run mypy src/chutils` и `uv run pytest tests/unit/scraping/`.
+- [ ] Task: Обновить документацию `docs/scraping.md` и перегенерировать `api_map.md`.

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

@@ -0,0 +1,26 @@
+# Specification: Queue & Worker Prometheus Monitoring (`queue_monitoring_20260728`)
+
+## 1. Overview
+Интеграция подсистемы метрик `chutils.metrics` в очереди задач (`InMemoryTaskQueue`, `PersistentTaskQueue`, `RedisTaskQueue`) и пул воркеров `WorkerPool` для мониторинга в реальном времени с экспортом в формате Prometheus.
+
+## 2. Functional Requirements
+1. **Экспортируемые метрики**:
+   - `chutils_queue_pending_size` (Gauge): размер очереди ожидания с метками `queue_name` и `queue_type`.
+   - `chutils_task_execution_duration_seconds` (Histogram/Timer): время обработки задач с метками `queue_name`, `status`.
+   - `chutils_tasks_processed_total` (Counter): общее количество завершенных задач с метками `status` (`completed`, `failed`, `retried`).
+   - `chutils_worker_pool_active_workers` (Gauge): число активных воркеров в пуле.
+2. **Интеграция с очередями**:
+   - Автоматический трекинг размера при вызовах `push()`, `pop()`, `complete()`, `fail()`, `clear()`.
+   - Возможность включения/отключения экспорта метрик через опциональный параметр `enable_metrics=True` в конструкторе очередей и `WorkerPool`.
+3. **Совместимость с `chutils.metrics`**:
+   - Использование абстракции `chutils.metrics` с поддержкой No-Op fallback (если `prometheus_client` не установлен или метрики отключены).
+
+## 3. Non-Functional Requirements
+- Нулевые накладные расходы при выключенном флаге метрик.
+- Потоко- и асинхронная безопасность.
+- Полное отсутствие `Any` в аннотациях типов.
+
+## 4. Acceptance Criteria
+- [ ] Очереди `InMemoryTaskQueue`, `PersistentTaskQueue` и `RedisTaskQueue` обновляют Gauge размера очереди при выполнении операций.
+- [ ] `WorkerPool` записывает длительность выполнения и число обработанных задач при работе с очередями.
+- [ ] Тесты подтверждают корректный сбор метрик и работы без библиотеки `prometheus_client`.

{chutils-3.4.0/conductor/archive/dev_watch_20260702 → chutils-3.4.2/conductor/tracks/stream_crypto_20260728}/index.md

@@ -1,4 +1,4 @@
-# Track dev_watch_20260702 Context
+# Track stream_crypto_20260728 Context
 
 - [Specification](./spec.md)
 - [Implementation Plan](./plan.md)

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

@@ -0,0 +1,8 @@
+{
+  "track_id": "stream_crypto_20260728",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-07-28T21:06:58.057037",
+  "updated_at": "2026-07-28T21:06:58.057058",
+  "description": "Потоковое AES-GCM шифрование файлов гигантского объема"
+}

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

@@ -0,0 +1,16 @@
+# Implementation Plan - Streaming Encryption for Large Files (`stream_crypto_20260728`)
+
+Реализация чанкового (потокового) шифрования файлов больших размеров в `chutils.crypto`.
+
+## Phase 1: Streaming Cipher Engine (`src/chutils/crypto/stream.py`)
+- [ ] Task: Реализовать класс `StreamCipher` в `src/chutils/crypto/stream.py` для обработки файлов блоками AES-GCM с уникальными Nonce.
+- [ ] Task: Обновить `encrypt_file` и `decrypt_file` в `src/chutils/crypto/core.py` с поддержкой `stream=True` и `chunk_size`.
+- [ ] Task: Добавить обработку `OptionalDependencyError` при отсутствии библиотеки `cryptography`.
+
+## Phase 2: Testing & Memory Benchmark
+- [ ] Task: Написать unit-тесты для потокового шифрования и расшифровки файлов в `tests/unit/test_crypto_stream.py`.
+- [ ] Task: Добавить тесты обнаружения подмененных/поврежденных чанков (AES-GCM integrity failure).
+
+## Phase 3: Verification & Documentation
+- [ ] Task: Запустить `uv run mypy src/chutils` и `uv run pytest tests/unit/test_crypto*.py`.
+- [ ] Task: Обновить примеры использования шифрования больших файлов в `docs/api.md` и обновить `api_map.md`.

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

@@ -0,0 +1,22 @@
+# Specification: Streaming Encryption for Large Files (`stream_crypto_20260728`)
+
+## 1. Overview
+Добавление поддержки потокового чанкового шифрования и расшифрования файлов произвольного объема (включая десятки гигабайт) в модуле `chutils.crypto` с жестко ограниченным потреблением оперативной памяти (O(1) Memory).
+
+## 2. Functional Requirements
+1. **Потоковая обработка**:
+   - Реализовать считывание, шифрование и запись файлов фиксированными блоками (по умолчанию `chunk_size = 64 МБ`).
+   - Расширить сигнатуру существующих функций `encrypt_file` и `decrypt_file` параметрами `stream: bool = True` и `chunk_size: int = 64 * 1024 * 1024`.
+2. **Криптографическая стойкость**:
+   - Использование симметричного шифрования AES-GCM (через `cryptography.hazmat.primitives.ciphers.aead.AESGCM`) с независимыми IV (Nonce) для каждого чанка и генерацией уникального заголовка (Header) со счетчиком чанков.
+3. **Безопасность и проверка целостности**:
+   - Валидация тега аутентификации для каждого блока при расшифровке. Если один из блоков поврежден или подменен, выбросить `InvalidSignature` / `DecryptionError` с точным указанием индекса сбойного чанка.
+
+## 3. Non-Functional Requirements
+- Потребление RAM при шифровании многогигабайтных файлов не должно превышать `chunk_size * 2`.
+- Graceful Fallback с прозрачным выводом требований к установке `chutils[crypto]` при отсутствии пакета `cryptography`.
+
+## 4. Acceptance Criteria
+- [ ] `encrypt_file(..., stream=True)` шифрует файл 1+ ГБ с потреблением RAM менее 150 МБ.
+- [ ] `decrypt_file` успешно восстанавливает исходный файл, проверяя целостность каждого чанка.
+- [ ] Модульные тесты подтверждают обнаружение поврежденных чанков во время расшифровки.

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)