chutils 3.6.0__tar.gz → 3.7.0__tar.gz

{chutils-3.6.0 → chutils-3.7.0}/.github/workflows/ci.yml

@@ -1,46 +1,46 @@
-name: CI
-
-on:
-  push:
-    branches: [ main, master ]
-  pull_request:
-    branches: [ main, master ]
-
-jobs:
-  test-and-lint:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: [ '3.10', '3.11', '3.12', '3.13', '3.14', '3.15-dev' ]
-
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
-        with:
-          enable-cache: true
-          version: "latest"
-
-      - name: Install dependencies
-        run: |
-          uv sync --all-extras
-
-      - name: Run Tests
-        run: |
-          uv run pytest
-
-      - name: Run Type Checking (Mypy)
-        run: |
-          uv run mypy src
-
-      - name: Run AI-Readiness Audit
-        run: |
-          uv run python -m chutils dev ai-lint --soft-mode
-
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test-and-lint:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ '3.10', '3.11', '3.12', '3.13', '3.14', '3.15-dev' ]
+
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          version: "latest"
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras
+
+      - name: Run Tests
+        run: |
+          uv run pytest
+
+      - name: Run Type Checking (Mypy)
+        run: |
+          uv run mypy src
+
+      - name: Run AI-Readiness Audit
+        run: |
+          uv run python -m chutils dev ai-lint --soft-mode
+

{chutils-3.6.0 → chutils-3.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: chutils
-Version: 3.6.0
+Version: 3.7.0
 Summary: Набор простых и удобных утилит для Python, который избавляет от рутины при работе с конфигурацией и логированием в новых проектах.
 Author-email: Chu4hel <sergeiivanov636@gmail.com>
 License-Expression: MIT
@@ -11,6 +11,8 @@ Requires-Dist: python-dotenv>=1.2.2
 Requires-Dist: pyyaml>=6.0.3
 Provides-Extra: aws
 Requires-Dist: boto3>=1.34.0; extra == 'aws'
+Provides-Extra: camoufox
+Requires-Dist: camoufox>=0.4.0; extra == 'camoufox'
 Provides-Extra: captcha
 Requires-Dist: httpx>=0.27.0; extra == 'captcha'
 Provides-Extra: crypto
@@ -71,6 +73,8 @@ Provides-Extra: testing
 Requires-Dist: pytest>=9.0.3; extra == 'testing'
 Provides-Extra: text
 Requires-Dist: rapidfuzz>=3.9.0; extra == 'text'
+Provides-Extra: tls
+Requires-Dist: curl-cffi>=0.7.0; extra == 'tls'
 Provides-Extra: vk
 Requires-Dist: pydantic<3.0.0,>=2.13.4; extra == 'vk'
 Provides-Extra: vkma

{chutils-3.6.0 → chutils-3.7.0}/ai-lint.toml

@@ -128,8 +128,10 @@
 # ---------------------------------------------------------------------------
 
 "src/chutils/scraping/**/*.py" = ["docs/scraping.md"]
+"new:src/chutils/scraping/nodriver.py" = ["docs/scraping.md"]
 "src/chutils/scraping/captcha/**/*.py" = ["docs/captcha.md"]
 
+
 # ---------------------------------------------------------------------------
 # Модуль аудита
 # ---------------------------------------------------------------------------

{chutils-3.6.0 → chutils-3.7.0}/api_map.md

@@ -1,9 +1,9 @@
 ---
-chutils_version: 3.6.0
-project_version: 3.6.0
-git_commit: a622ebf7170639f85d8e299bf4763768c2e87719
-generated_at: 2026-09-07T19:30:12.995418+00:00
-project_hash: fb14b689767aaa8d9826e388bf1bc7b7627bbc60d975d32d8e73cbab59a05758
+chutils_version: 3.7.0
+project_version: 3.7.0
+git_commit: 5cb29a30832f6b1d6e3af1c4572da491e9a76968 (dirty)
+generated_at: 2026-09-15T14:49:04.299233+00:00
+project_hash: 58ba4b8fbabcd20573314c01c78c3ef9decdf6006d6aac4c12d7be9c84989f7a
 ---
 
 # Public API Map: chutils
@@ -104,6 +104,8 @@ project_hash: fb14b689767aaa8d9826e388bf1bc7b7627bbc60d975d32d8e73cbab59a05758
 | `SseConfigClient`                     | class    | `(self, url: 'str', on_event: 'Callable[[SseEvent], None] \| None' = None, on_reload: 'Callable[[], None] \| None' = None, headers: 'dict[str, str] \| None' = None, timeout: 'float' = 30.0, reconnect_delay: 'float' = 1.0, max_reconnect_delay: 'float' = 60.0) -> 'None'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Клиент для постоянного подключения к SSE-серверу обновлений конфигурации.                                          |
 | `SseEvent`                            | class    | `(self, event: 'str' = 'message', data: 'str' = '', event_id: 'str \| None' = None, retry: 'int \| None' = None) -> 'None'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Представляет отдельное событие Server-Sent Events (SSE).                                                           |
 | `StoreManager`                        | class    | `(self, backend: 'BaseStoreBackend \| None' = None, serializer: 'str \| Any' = 'json', prefix: 'str' = '') -> 'None'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Центральный менеджер Key-Value хранилища.                                                                          |
+| `TLSAsyncClient`                      | class    | `(self, impersonate: 'str' = 'chrome120', proxy: 'ProxyConfig \| str \| None' = None, proxy_pool: 'ProxyPool \| None' = None, fallback_to_standard: 'bool' = False, timeout: 'float' = 30.0, **kwargs: 'Any') -> 'None'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Асинхронный HTTP-клиент с поддержкой TLS/HTTP2 Client Impersonation (curl-cffi).                                   |
+| `TLSSession`                          | class    | `(self, impersonate: 'str' = 'chrome120', proxy: 'ProxyConfig \| str \| None' = None, proxy_pool: 'ProxyPool \| None' = None, fallback_to_standard: 'bool' = False, timeout: 'float' = 30.0, **kwargs: 'Any') -> 'None'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Синхронный HTTP-клиент с поддержкой TLS/HTTP2 Client Impersonation (curl-cffi).                                    |
 | `TelegramLogHandler`                  | class    | `(self, bot_token: 'str \| None' = None, chat_id: 'int \| str \| None' = None, level: 'int' = 40, rate_limit_per_min: 'int' = 10) -> 'None'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Handler стандартного модуля logging для отправки критических логов в Telegram.                                     |
 | `TelegramLoggingMiddleware`           | class    | `(self, logger_instance: 'Any' = None) -> 'None'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Middleware контекстного логирования и измерений времени выполнения для aiogram 3.x.                                |
 | `TelegramRateLimiter`                 | class    | `(self, rate: 'int' = 1, per: 'float' = 1.0) -> 'None'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Движок ограничений вызовов (Rate Limiter) для Telegram-ботов.                                                      |
@@ -120,17 +122,17 @@ project_hash: fb14b689767aaa8d9826e388bf1bc7b7627bbc60d975d32d8e73cbab59a05758
 | `aget_config`                         | function | `(model: 'type[T] \| None' = None) -> 'JSONDict \| T'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Асинхронная версия get_config.                                                                                     |
 | `aget_config_value`                   | function | `(section: 'str', key: 'str', fallback: 'Any' = None, config: 'JSONDict \| None' = None, required: 'bool' = False) -> 'Any'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Асинхронно получает произвольное значение из конфигурации.                                                         |
 | `allowed_only`                        | function | `(manager: 'AccessListManager \| None' = None, allowed_ids: 'list[int] \| None' = None, allowed_usernames: 'list[str] \| None' = None, blocked_ids: 'list[int] \| None' = None, blocked_usernames: 'list[str] \| None' = None, refusal_text: 'str \| None' = '⛔ У вас нет доступа к этой функции', silent: 'bool' = False, raise_on_denied: 'bool' = False) -> 'Callable[[F], F]'`                                                                                                                                                                                                                                                                                                                                                                                              | Декоратор ограничения доступа по белым и черным спискам.                                                           |
-| `apply_antidetect_nodriver`           | function | `(tab: Any, *, webgl_vendor: str = 'Google Inc. (NVIDIA)', webgl_renderer: str = 'ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 Direct3D11 vs_5_0 ps_5_0, D3D11)', hardware_concurrency: int = 8, device_memory: int = 8) -> None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Применяет JS-инъекции анти-детекта к вкладке (Tab) nodriver.                                                       |
-| `apply_antidetect_playwright`         | function | `(context: Any, *, webgl_vendor: str = 'Google Inc. (NVIDIA)', webgl_renderer: str = 'ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 Direct3D11 vs_5_0 ps_5_0, D3D11)', hardware_concurrency: int = 8, device_memory: int = 8) -> None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Применяет JS-инъекции анти-детекта к контексту Playwright.                                                         |
-| `apply_antidetect_selenium`           | function | `(driver: Any, *, webgl_vendor: str = 'Google Inc. (NVIDIA)', webgl_renderer: str = 'ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 Direct3D11 vs_5_0 ps_5_0, D3D11)', hardware_concurrency: int = 8, device_memory: int = 8) -> None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Применяет JS-инъекции анти-детекта к сессии Selenium.                                                              |
+| `apply_antidetect_nodriver`           | function | `(tab: 'Any', *, config: 'AntidetectConfig \| None' = None, webgl_vendor: 'str' = 'Google Inc. (NVIDIA)', webgl_renderer: 'str' = 'ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 Direct3D11 vs_5_0 ps_5_0, D3D11)', hardware_concurrency: 'int' = 8, device_memory: 'int' = 8, stealth_minimal: 'bool' = True, session_seed: 'str \| int' = 1337, client_hints: 'dict[str, Any] \| None' = None) -> 'None'`                                                                                                                                                                                                                                                                                                                                                                            | Применяет JS-инъекции анти-детекта к вкладке (Tab) nodriver.                                                       |
+| `apply_antidetect_playwright`         | function | `(context: 'Any', *, config: 'AntidetectConfig \| None' = None, webgl_vendor: 'str' = 'Google Inc. (NVIDIA)', webgl_renderer: 'str' = 'ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 Direct3D11 vs_5_0 ps_5_0, D3D11)', hardware_concurrency: 'int' = 8, device_memory: 'int' = 8, stealth_minimal: 'bool' = False, session_seed: 'str \| int' = 1337, client_hints: 'dict[str, Any] \| None' = None) -> 'None'`                                                                                                                                                                                                                                                                                                                                                                       | Применяет JS-инъекции анти-детекта к контексту Playwright.                                                         |
+| `apply_antidetect_selenium`           | function | `(driver: 'Any', *, config: 'AntidetectConfig \| None' = None, webgl_vendor: 'str' = 'Google Inc. (NVIDIA)', webgl_renderer: 'str' = 'ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 Direct3D11 vs_5_0 ps_5_0, D3D11)', hardware_concurrency: 'int' = 8, device_memory: 'int' = 8, stealth_minimal: 'bool' = False, session_seed: 'str \| int' = 1337, client_hints: 'dict[str, Any] \| None' = None) -> 'None'`                                                                                                                                                                                                                                                                                                                                                                        | Применяет JS-инъекции анти-детекта к сессии Selenium.                                                              |
 | `are_paths_initialized`               | function | `() -> bool`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Проверяет, были ли инициализированы пути к проекту и файлам конфигурации.                                          |
 | `asave_config_value`                  | function | `(section: 'str', key: 'str', value: 'Any', cfg_file: 'str \| None' = None, save_to_local: 'bool' = False, notify: 'bool' = True) -> 'bool'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Асинхронно сохраняет одно значение в конфигурационном файле.                                                       |
-| `async_click`                         | function | `(page: Any, selector: str \| None = None, x: int \| None = None, y: int \| None = None, start: tuple[int, int] \| None = None, algorithm: str = 'windmouse', button: str = 'left') -> None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Имитирует реалистичный клик мышью (с плавным наведением, микропаузами и удержанием кнопки).                        |
+| `async_click`                         | function | `(page: Any, selector: str \| None = None, x: int \| None = None, y: int \| None = None, start: tuple[int, int] \| None = None, algorithm: str = 'windmouse', button: str = 'left', hold_time: tuple[float, float] = (0.05, 0.12)) -> None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Имитирует реалистичный клик мышью (с плавным наведением, микропаузами и удержанием кнопки).                        |
 | `async_human_sleep`                   | function | `(min_seconds: float, max_seconds: float) -> None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Асинхронно задерживает выполнение на случайное время, имитируя поведение человека.                                 |
 | `async_lifecycle`                     | function | `(setup_signals: 'bool' = True, auto_cleanup_subsystems: 'bool' = True) -> 'AsyncLifecycleContext'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Возвращает контекстный менеджер для управления жизненным циклом ресурсов.                                          |
 | `async_move_mouse`                    | function | `(page: Any, x: int, y: int, start: tuple[int, int] \| None = None, steps: int = 30, delay_between_steps: float = 0.01, algorithm: str = 'bezier') -> None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Имитирует плавное перемещение мыши Playwright или nodriver.                                                        |
 | `async_scroll_to`                     | function | `(page: Any, x: int, y: int, selector: str \| None = None, steps: int = 10, delay_between_steps: float = 0.01) -> None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Имитирует плавный скроллинг Playwright или nodriver.                                                               |
-| `async_type_text`                     | function | `(page: Any, selector: str, text: str, error_rate: float = 0.05, speed_wpm: float = 40.0) -> None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Имитирует ввод текста с опечатками Playwright или nodriver.                                                        |
+| `async_type_text`                     | function | `(page: Any, selector: str, text: str, error_rate: float = 0.05, speed_wpm: float = 40.0, key_hold_time: tuple[float, float] = (0.04, 0.09)) -> None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Имитирует ввод текста с опечатками Playwright или nodriver.                                                        |
 | `audit`                               | module   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | chutils.audit — Неизменяемый журнал событий аудита.                                                                |
 | `audit_context`                       | function | `(action: 'str', actor: 'str', *, target: 'str \| None' = None, backend: 'object') -> 'Generator[_AuditContextState, None, None]'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Контекстный менеджер для регистрации события аудита в блоке кода.                                                  |
 | `audit_event`                         | function | `(action: 'str', actor: '_ActorOrCallable' = 'system', *, target: '_TargetOrCallable' = None, backend: 'object') -> 'Callable'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Декоратор для автоматической регистрации события аудита при вызове функции.                                        |
@@ -143,10 +145,12 @@ project_hash: fb14b689767aaa8d9826e388bf1bc7b7627bbc60d975d32d8e73cbab59a05758
 | `cleanup_paths`                       | function | `(*paths: 'str \| Path', retries: 'int' = 3, delay: 'float' = 0.1, on_locked: "Literal['raise', 'rename_orphan', 'warn']" = 'warn', orphan_collision: "Literal['raise', 'overwrite', 'unique']" = 'raise') -> 'None'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Пакетное удаление нескольких путей.                                                                                |
 | `clear_context`                       | function | `() -> 'None'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Полностью очищает текущий контекст.                                                                                |
 | `cli_command`                         | function | `(func: ~F) -> ~F`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Декоратор для превращения функции в CLI-команду.                                                                   |
-| `click`                               | function | `(driver: Any, selector: str \| None = None, x: int \| None = None, y: int \| None = None, start: tuple[int, int] \| None = None, algorithm: str = 'windmouse') -> None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Имитирует реалистичный клик мышью Selenium.                                                                        |
+| `click`                               | function | `(driver: Any, selector: str \| None = None, x: int \| None = None, y: int \| None = None, start: tuple[int, int] \| None = None, algorithm: str = 'windmouse', hold_time: tuple[float, float] = (0.05, 0.12)) -> None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Имитирует реалистичный клик мышью Selenium.                                                                        |
 | `config`                              | module   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Модуль для работы с конфигурацией.                                                                                 |
 | `container`                           | constant |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Легковесный IoC/DI контейнер.                                                                                      |
 | `context`                             | module   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                    |
+| `create_curl_async_session`           | function | `(impersonate: 'str', proxy: 'str \| None' = None, **kwargs: 'Any') -> 'Any'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Создает асинхронную сессию curl_cffi с заданным профилем impersonate.                                              |
+| `create_curl_session`                 | function | `(impersonate: 'str', proxy: 'str \| None' = None, **kwargs: 'Any') -> 'Any'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Создает синхронную сессию curl_cffi с заданным профилем impersonate.                                               |
 | `create_http_span`                    | function | `(method: 'str', url: 'str', tracer_name: 'str' = 'chutils.http') -> 'object \| None'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Создаёт OTEL-спан для исходящего HTTP-запроса.                                                                     |
 | `crypto`                              | module   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Модуль для портативного детерминированного шифрования данных.                                                      |
 | `dashboard`                           | module   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Интерактивный TUI-дашборд для CLI-команд проекта.                                                                  |
@@ -166,6 +170,7 @@ project_hash: fb14b689767aaa8d9826e388bf1bc7b7627bbc60d975d32d8e73cbab59a05758
 | `events`                              | module   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Модуль шины событий (In-Memory Event Bus).                                                                         |
 | `exceptions`                          | module   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                    |
 | `export_schema`                       | function | `(model: type[pydantic.main.BaseModel] \| str, output_path: str \| pathlib.Path \| None = None, indent: int = 4) -> str`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Генерирует JSON Schema для Pydantic модели и опционально сохраняет в файл.                                         |
+| `extract_clearance_cookies`           | function | `(target: 'Any') -> 'Any'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Извлекает cookies (включая cf_clearance) и User-Agent из сессии браузера.                                          |
 | `few_shot`                            | module   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                    |
 | `fs`                                  | module   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Модуль для надежных операций с файловой системой.                                                                  |
 | `generate_env_template`               | function | `(model_class: 'type[BaseModel]', prefix: 'str' = 'CH') -> 'str'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Генерирует .env шаблон (плоский формат).                                                                           |
@@ -175,7 +180,8 @@ project_hash: fb14b689767aaa8d9826e388bf1bc7b7627bbc60d975d32d8e73cbab59a05758
 | `generate_yaml_template`              | function | `(model_class: 'type[BaseModel]', indent: 'int' = 0) -> 'str'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Генерирует YAML шаблон на основе Pydantic модели с комментариями.                                                  |
 | `get_all_config_paths`                | function | `(cfg_file: str \| None = None) -> tuple[str \| None, str \| None, str \| None]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Возвращает пути к основному, специфичному для окружения и локальному файлам конфигурации.                          |
 | `get_base_dir`                        | function | `() -> str \| None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Возвращает абсолютный путь к корневой директории проекта.                                                          |
-| `get_browser_launch_args`             | function | `() -> list[str]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Возвращает набор аргументов запуска браузера для скрытия автоматизации.                                            |
+| `get_browser_launch_args`             | function | `() -> 'list[str]'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Возвращает расширенный набор аргументов запуска браузера для скрытия автоматизации.                                |
+| `get_client_hints`                    | function | `(user_agent: 'str \| None' = None) -> 'dict[str, Any]'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Генерирует словарь согласованных Client Hints (navigator.userAgentData) на основе User-Agent.                      |
 | `get_config`                          | function | `(model: 'type[T] \| None' = None, remote_url: 'str \| None' = None, remote_auth: 'tuple[str, str] \| None' = None, polling_interval: 'int \| None' = None, sse_url: 'str \| None' = None, sse_headers: 'dict[str, str] \| None' = None) -> 'JSONDict \| T'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Загружает и объединяет конфигурацию из всех доступных источников.                                                  |
 | `get_config_boolean`                  | function | `(section: 'str', key: 'str', fallback: 'bool' = False, config: 'JSONDict \| None' = None, required: 'bool' = False) -> 'bool'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Получает булево значение из конфигурации.                                                                          |
 | `get_config_file_path`                | function | `() -> str \| None`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Возвращает путь к основному файлу конфигурации, который используется в данный момент.                              |
@@ -199,6 +205,7 @@ project_hash: fb14b689767aaa8d9826e388bf1bc7b7627bbc60d975d32d8e73cbab59a05758
 | `is_otel_enabled`                     | function | `() -> 'bool'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Проверяет, доступен ли OpenTelemetry и не отключен ли он.                                                          |
 | `is_rich_enabled`                     | function | `() -> 'bool'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Централизованная проверка: доступен ли Rich и разрешен ли он настройками.                                          |
 | `is_significant_difference`           | function | `(text1: str, text2: str, threshold: float = 0.9) -> bool`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Проверяет, является ли разница между двумя текстами значительной.                                                  |
+| `launch_camoufox`                     | function | `(headless: 'bool' = True, os: 'str' = 'windows', **kwargs: 'Any') -> 'Any'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Создает и возвращает контекстный менеджер / сессию браузера AsyncCamoufox.                                         |
 | `lifecycle`                           | module   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Управление жизненным циклом приложения.                                                                            |
 | `load_ai_lint_config`                 | function | `(cli_args: 'JSONDict \| None' = None) -> 'JSONDict'`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Загружает и объединяет конфигурацию для ai-lint из всех источников.                                                |
 | `log_function_details`                | function | `(func: collections.abc.Callable[~P, ~R]) -> collections.abc.Callable[~P, ~R]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Декоратор для логирования деталей вызова функции.                                                                  |

{chutils-3.6.0 → chutils-3.7.0}/benchmarks/cold_start.py

@@ -35,13 +35,13 @@ loaded_chutils = [m for m in sys.modules if m.startswith('chutils.')]
 print(json.dumps({{"duration": end - start, "modules": loaded_chutils}}))
 """
     result = subprocess.run(
-        [sys.executable, "-c", script], capture_output=True, text=True
+        [sys.executable, "-c", script], capture_output=True, text=True, check=False
     )
     if result.returncode != 0:
         print(f"Error: {result.stderr}")
         try:
             return json.loads(result.stdout)
-        except:
+        except Exception:
             return None
     return json.loads(result.stdout)
 

chutils-3.7.0/conductor/archive/advanced_antidetect_e2e_20260910/index.md

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

chutils-3.7.0/conductor/archive/advanced_antidetect_e2e_20260910/index.md.metadata.json

@@ -0,0 +1,4 @@
+{
+  "summary":  "Индексный файл index.md для трека advanced_antidetect_e2e_20260910",
+  "updatedAt":  "2026-09-10T12:54:36.199351700Z"
+}

chutils-3.7.0/conductor/archive/advanced_antidetect_e2e_20260910/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "advanced_antidetect_e2e_20260910",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-09-10T15:53:30+03:00",
+  "updated_at": "2026-09-10T15:53:30+03:00",
+  "description": "Улучшение антидетекта (Web Workers, stack traces, cookie bridge) и E2E тесты"
+}

chutils-3.7.0/conductor/archive/advanced_antidetect_e2e_20260910/plan.md

@@ -0,0 +1,29 @@
+# Implementation Plan: Продвинутый антидетект и E2E тесты
+
+## Phase 1: Усиление JS-антидетекта (Web Workers & V8 Stacks)
+- [x] Task: Написать unit-тесты для перехвата Worker и маскировки стектрейсов
+    - [x] Написать тесты на генерацию JS-кода с перехватом `Worker` и `SharedWorker`
+    - [x] Написать тесты на генерацию чистого `Error.prototype.stack` в геттерах
+- [x] Task: Модернизация src/chutils/scraping/humanize/antidetect.py
+    - [x] Добавить в JS-скрипт перехват `window.Worker` и `window.SharedWorker` с инъекцией преамбулы
+    - [x] Улучшить хелпер `makeNative` для маскировки стектрейсов вызовов V8
+- [x] Task: Conductor - User Manual Verification 'Phase 1: Worker & Stack Protection' (Protocol in workflow.md)
+
+## Phase 2: Мост Cookie/Headers (Браузер -> TLSAsyncClient)
+- [x] Task: Написать unit-тесты для extract_clearance_cookies
+    - [x] Написать тесты для извлечения кук и User-Agent из Playwright, Selenium и Nodriver моков
+- [x] Task: Реализация extract_clearance_cookies и интеграция с TLSAsyncClient
+    - [x] Реализовать `extract_clearance_cookies` в `src/chutils/scraping/humanize/antidetect.py`
+    - [x] Добавить фабричный метод `from_browser_session` в `TLSAsyncClient` / `TLSSession`
+- [x] Task: Conductor - User Manual Verification 'Phase 2: Cookie Bridge' (Protocol in workflow.md)
+
+## Phase 3: E2E Тесты и финальная верификация
+- [x] Task: Реализация E2E тестов в tests/e2e/test_antidetect_e2e.py
+    - [x] Реализовать E2E проверку TLS/JA4 профилей через peet.ws
+    - [x] Реализовать проверку чистоты окружения Worker и navigator
+    - [x] Реализовать сквозной тест передачи сессии из браузера в TLSAsyncClient
+- [x] Task: Экспорт, документация и проверки качества
+    - [x] Добавить экспорт новых утилит в `src/chutils/__init__.py` и `src/chutils/scraping/__init__.py`
+    - [x] Обновить документацию `docs/scraping.md` и `docs/http.md`
+    - [x] Прогнать `pytest`, `mypy --strict`, `ruff check`, `ruff format --check`, `chutils dev lock --force`, `chutils dev ai-lint`
+- [x] Task: Conductor - User Manual Verification 'Phase 3: E2E Testing & Verification' (Protocol in workflow.md)

chutils-3.7.0/conductor/archive/advanced_antidetect_e2e_20260910/plan.md.metadata.json

@@ -0,0 +1,4 @@
+{
+  "summary":  "План реализации plan.md трека advanced_antidetect_e2e_20260910",
+  "updatedAt":  "2026-09-10T12:54:30.892555600Z"
+}

chutils-3.7.0/conductor/archive/advanced_antidetect_e2e_20260910/spec.md

@@ -0,0 +1,25 @@
+# Specification: Продвинутый антидетект (Web Workers, V8 Stacks, Cookie Bridge) и E2E тесты
+
+## 1. Overview
+Трек направлен на закрытие ключевых векторов обнаружения автоматизации (утечки через изолированные Web Workers/SharedWorkers, следы в Error.prototype.stack) и создание сквозного моста передачи сессионных cookie/заголовков из браузеров (Playwright/Camoufox/Nodriver) в высокоскоростные TLS-клиенты (TLSSession/TLSAsyncClient), а также покрытие функционала E2E-тестами.
+
+## 2. Functional Requirements
+- **Web Workers & SharedWorkers Protection**:
+  - Внедрение перехвата `window.Worker` и `window.SharedWorker` в `antidetect.py`.
+  - Автоматическая инъекция защитного преамбул-скрипта (очистка `navigator.webdriver`, подмена `navigator.userAgentData`, маскировка `toString`) при создании Worker через URL или Blob.
+- **V8 Stack Traces Cloaking**:
+  - Улучшение `makeNative` для предотвращения утечек имен патч-функций и неверных строк стека при искусственном вызове ошибок внутри геттеров.
+- **Cookie/Header Bridge (`extract_clearance_cookies`)**:
+  - Функция `extract_clearance_cookies(target: Any) -> dict[str, Any]` с извлечением кук (`cf_clearance`, `__cf_bm` и др.), заголовков и User-Agent из Playwright `BrowserContext`/`Page`, Selenium WebDriver и Nodriver Tab.
+  - Метод интеграции или фабрика создания `TLSAsyncClient.from_browser_session(session_or_page)`.
+- **E2E Testing Suite**:
+  - Создание `tests/e2e/test_antidetect_e2e.py` (с маркером `@pytest.mark.e2e`):
+    - Тест валидации JA3/JA4 и HTTP/2 на реальном сервисе `https://tls.peet.ws/api/all`.
+    - Тест изоляции Web Workers и прототипов в браузере.
+    - Сквозной тест передачи сессии из браузера в `TLSAsyncClient`.
+
+## 3. Acceptance Criteria
+1. Web Workers не выдают `navigator.webdriver === true`.
+2. Стектрейсы ошибок в пропатченных свойствах не содержат артефактов стороннего JS кода.
+3. Функция `extract_clearance_cookies` успешно работает со всеми поддерживаемыми драйверами с graceful fallback.
+4. Все E2E и unit-тесты проходят, mypy strict, ruff и ai-lint без ошибок и предупреждений.

chutils-3.7.0/conductor/archive/advanced_antidetect_e2e_20260910/spec.md.metadata.json

@@ -0,0 +1,4 @@
+{
+  "summary":  "Спецификация трека advanced_antidetect_e2e_20260910",
+  "updatedAt":  "2026-09-10T12:54:27.348681300Z"
+}

chutils-3.7.0/conductor/archive/nodriver_antidetect_20260910/index.md

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

chutils-3.7.0/conductor/archive/nodriver_antidetect_20260910/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "nodriver_antidetect_20260910",
+  "type": "feature",
+  "status": "completed",
+  "created_at": "2026-09-10T02:42:00Z",
+  "updated_at": "2026-09-10T02:42:00Z",
+  "description": "Улучшение антидетекта и скрытия автоматизации nodriver (маскировка JS, нативные дескрипторы, микропаузы, Permissions API)"
+}

chutils-3.7.0/conductor/archive/nodriver_antidetect_20260910/plan.md

@@ -0,0 +1,41 @@
+# Implementation Plan: nodriver Anti-Detect & Stealth Enhancement
+
+## Phase 1: JavaScript Anti-Tampering & Permissions Synchronization
+- [x] Task: TDD - Тесты для улучшенной JS-инъекции (защита toString, WebGL2, Permissions API)
+    - [x] Написать unit-тесты для проверки `Function.prototype.toString` (`[native code]`)
+    - [x] Написать unit-тесты для одновременного патчинга WebGL1 и WebGL2
+    - [x] Написать unit-тесты эмуляции Permissions API и Notification
+- [x] Task: Реализация улучшений JS-маскировки в `antidetect.py`
+    - [x] Реализовать функцию `makeNative` для маскировки строкового представления функций
+    - [x] Добавить обработку `WebGL2RenderingContext`
+    - [x] Добавить синхронизацию `navigator.permissions.query` и `Notification.permission`
+    - [x] Привести в соответствие дескрипторы свойств `navigator`
+- [x] Task: Conductor - User Manual Verification 'Phase 1: JavaScript Anti-Tampering & Permissions Synchronization' (Protocol in workflow.md)
+
+## Phase 2: nodriver Stealth Minimal Mode & Browser Flags
+- [x] Task: TDD - Тесты для режима stealth_minimal и флагов запуска браузера
+    - [x] Добавить тесты для `apply_antidetect_nodriver` с параметром `stealth_minimal=True`
+    - [x] Протестировать обновленный список флагов запуска `get_browser_launch_args`
+- [x] Task: Реализация `stealth_minimal` и обновление аргументов запуска
+    - [x] Добавить аргумент `stealth_minimal` в функцию `apply_antidetect_nodriver`
+    - [x] Исключить модификацию Canvas и WebGL при `stealth_minimal=True`
+    - [x] Обновить флаги в `get_browser_launch_args` (современный headless, подавление детекта автоматизации)
+- [x] Task: Conductor - User Manual Verification 'Phase 2: nodriver Stealth Minimal Mode & Browser Flags' (Protocol in workflow.md)
+
+## Phase 3: Humanized Hold Time in CDP Input Actions
+- [x] Task: TDD - Тесты для микропауз удержания кнопок мыши и клавиш
+    - [x] Написать тесты для проверки пауз между mousePressed и mouseReleased в `async_click`
+    - [x] Написать тесты для проверки задержек удержания keyDown/keyUp в `async_type_text`
+- [x] Task: Реализация микропауз удержания в `actions.py`
+    - [x] Добавить параметры `hold_time_min` и `hold_time_max` в `async_click` для CDP
+    - [x] Добавить эмуляцию задержки нажатия клавиш в `async_type_text` для nodriver
+- [x] Task: Conductor - User Manual Verification 'Phase 3: Humanized Hold Time in CDP Input Actions' (Protocol in workflow.md)
+
+## Phase 4: Documentation, AI Context Sync & Final Integration
+- [x] Task: Обновление документации
+    - [x] Обновить `docs/scraping.md` с описанием новых параметров и возможностей антидетекта
+    - [x] Проверить соответствие Google docstrings в затронутых файлах
+- [x] Task: Синхронизация AI-контекста и линтинг
+    - [x] Сгенерировать контекст через `uv run chutils dev generate-context`
+    - [x] Запустить `uv run chutils dev ai-lint` и `uv run pytest` для валидации всего набора тестов
+- [x] Task: Conductor - User Manual Verification 'Phase 4: Documentation, AI Context Sync & Final Integration' (Protocol in workflow.md)

chutils-3.7.0/conductor/archive/nodriver_antidetect_20260910/spec.md

@@ -0,0 +1,31 @@
+# Specification: nodriver Anti-Detect & Stealth Enhancement (`chutils.scraping.humanize`)
+
+## 1. Overview
+Улучшение механизмов маскировки автоматизации и антидетекта для `nodriver` (а также `playwright` и `selenium`) в модуле `chutils.scraping.humanize`. Цель: устранение прямых признаков вмешательства (Tampering) в окружение JavaScript, поддержка WebGL2, нативная маскировка `Function.prototype.toString`, согласование дескрипторов свойств, реализация режима `stealth_minimal` и добавление физиологических микропауз удержания (Hold Time) для CDP-ввода.
+
+## 2. Functional Requirements
+1. **Качественная маскировка JavaScript (Anti-Tampering)**:
+   - Защита `Function.prototype.toString`: все подмененные встроенные функции должны возвращать `"function [name]() { [native code] }"`, а вызов `.toString()` на них самих — корректную нативную строку.
+   - Корректная эмуляция дескрипторов: `Object.getOwnPropertyDescriptor` на `navigator` и прототипах должен возвращать стандартные атрибуты без явных следов переопределения (`enumerable`, `configurable`, `writable`).
+   - Патчинг WebGL2: одновременная и согласованная подмена параметров вендора и рендерера в `WebGLRenderingContext` и `WebGL2RenderingContext`.
+   - Синхронизация Permissions API: приведение к консистентному состоянию `Notification.permission` и `navigator.permissions.query({name: 'notifications'})`.
+2. **Режим `stealth_minimal` для nodriver**:
+   - Параметр `stealth_minimal: bool = False` в `apply_antidetect_nodriver()`.
+   - При активном флаге не вносить синтетический шум в Canvas (`getImageData`) и не переопределять WebGL-параметры, если используется полноценный установленный Google Chrome, чтобы не нарушать естественный отпечаток железа.
+3. **Физиологические микропаузы (Hold Time)**:
+   - Добавить настраиваемый диапазон задержки удержания (Hold Time) для событий клика мыши (`mousePressed` -> `mouseReleased`) в `async_click` (по умолчанию 50–120 мс).
+   - Добавить задержку удержания между нажатием и отпусканием клавиш (`keyDown` -> `keyUp`) в `async_type_text` (по умолчанию 40–90 мс) при работе через CDP.
+4. **Оптимизация флагов запуска**:
+   - Обновить `get_browser_launch_args()` для добавления флагов исключения предупреждений автоматизации и поддержки современного режима headless.
+
+## 3. Non-Functional Requirements
+- Строгая типизация Python 3.10+ (без устаревших `typing.Optional`, `typing.List` и без `Any` в сигнатурах публичного API).
+- Обратная совместимость с существующими сигнатурами функций `apply_antidetect_*` и `async_click`/`async_type_text`.
+- Высокое покрытие модульными тестами (>90%).
+
+## 4. Acceptance Criteria
+- [ ] Вызовы `.toString()` на подмененных функциях в JS-инъекциях возвращают `[native code]`.
+- [ ] Параметры WebGL вендора и рендерера корректно подменяются как для WebGL 1, так и для WebGL 2.
+- [ ] `apply_antidetect_nodriver(..., stealth_minimal=True)` не внедряет искажения Canvas и WebGL.
+- [ ] Ввод текста и клики через CDP в `nodriver` содержат микропаузы удержания клавиш и кнопок мыши.
+- [ ] Все существующие и новые unit-тесты успешно проходят через `uv run pytest`.

chutils-3.7.0/conductor/archive/nodriver_launch_turnstile_fix_20260910/index.md

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

chutils-3.7.0/conductor/archive/nodriver_launch_turnstile_fix_20260910/metadata.json

@@ -0,0 +1,9 @@
+{
+  "track_id": "nodriver_launch_turnstile_fix_20260910",
+  "type": "feature",
+  "status": "completed",
+  "created_at": "2026-09-10T18:51:00Z",
+  "updated_at": "2026-09-10T19:04:00Z",
+
+  "description": "Исправление координат Turnstile, поддержка Shadow DOM и фабрика launch_nodriver с AntidetectConfig"
+}