chutils 3.4.0__tar.gz → 3.4.1__tar.gz

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

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

{chutils-3.4.0 → chutils-3.4.1}/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: 824417aa80b19bbfbb6cbb86151e5139be92b981 (dirty)
+generated_at: 2026-07-28T19:53:16.120390+00:00
+project_hash: 1001ffd89333fcf5c07c42b89dfebc67f38e7574da9f7166e3845fa464c5bc81
 ---
 
 # 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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/conductor/tracks.md

@@ -0,0 +1,37 @@
+# Project Tracks
+
+This file tracks all major tracks for the project. Each track has its own detailed plan in its respective folder.
+
+---
+
+- [ ] **Track: Поддержка родительских профилей браузеров (nodriver, playwright, selenium)** [3.5.0]
+*Link: [./tracks/browser_profiles_20260728/](./tracks/browser_profiles_20260728/)*
+
+---
+
+- [ ] **Track: Мониторинг очередей задач и воркеров через Prometheus** [3.5.0]
+*Link: [./tracks/queue_monitoring_20260728/](./tracks/queue_monitoring_20260728/)*
+
+---
+
+- [ ] **Track: Асинхронный контекстный менеджер lifecycle()** [3.5.0]
+*Link: [./tracks/async_lifecycle_20260728/](./tracks/async_lifecycle_20260728/)*
+
+---
+
+- [ ] **Track: Потоковое шифрование гигантских файлов (AES-GCM)** [3.5.0]
+*Link: [./tracks/stream_crypto_20260728/](./tracks/stream_crypto_20260728/)*
+
+---
+
+- [ ] **Track: Оптимизация генератора AI-контекста (.gitignore и инкремент)** [3.5.0]
+*Link: [./tracks/ai_context_opt_20260728/](./tracks/ai_context_opt_20260728/)*
+
+
+
+
+
+
+
+
+

{chutils-3.4.0 → chutils-3.4.1}/docs/dependencies.md

@@ -52,7 +52,12 @@ pip install "chutils[full]"
 | `qt-pyside`  | `PySide6 >=6.6`                                                                        | `chutils.qt` — `QtLogHandler`, `run_async_task`, `BaseMainWindow`, `BaseDialog` (PySide6 бэкенд)                                                                                                                                                                                                                                                             | `OptionalDependencyError` при вызове                                                                                                  |
 | `otel`       | `opentelemetry-api`, `opentelemetry-sdk`, `opentelemetry-exporter-otlp` (все `>=1.41`) | `chutils.tracing` — `setup_tracing()`, `@traced`, `get_tracer()`                                                                                                                                                                                                                                                                                             | ⚡ Декоратор `@traced` становится no-op (просто возвращает оригинальную функцию). `get_tracer()` возвращает `None`.                    |
 | `testing`    | `pytest >=9.0`                                                                         | `chutils.testing` — фикстуры для тестов (`temp_config`, `mock_secret_manager` и др.)                                                                                                                                                                                                                                                                         | `ImportError` при попытке импорта                                                                                                     |
-| `full`       | Все вышеперечисленные                                                                  | Вся функциональность                                                                                                                                                                                                                                                                                                                                         | —                                                                                                                                     |
+| `full`       | Практически все пакеты (кроме взаимоисключающих `qt` / `qt-pyside`)                    | Вся базовая и расширенная функциональность библиотеки (без дублирования альтернативных GUI-бэкендов)                                                                                                                                                                                                                                                         | —                                                                                                                                     |
+
+> [!NOTE]
+> Группа `chutils[full]` намеренно **не включает** GUI биндинги (`PyQt6` / `PySide6`) и распределенный бэкенд `redis`,
+> так как пользователь выбирает конкретную графическую библиотеку или инфра-хранилище под свой стек. Для добавления Qt
+> установите `chutils[full,qt]` или `chutils[full,qt-pyside]`.
 
 ---