Справочник API

В этом разделе находится документация, автоматически сгенерированная из исходного кода chutils. Все детали реализации, приоритеты настроек, форматы переменных окружения (включая разделитель вложенности __, AliasChoices и автоматический парсинг JSON-списков) и примеры перенесены непосредственно в докстринги модулей и функций.

Пакет chutils

chutils

Пакет chutils - набор переиспользуемых утилит для Python.

Основная цель - упростить рутинные задачи, такие как работа с конфигурацией, логированием и управлением секретами, с минимальными усилиями со стороны разработчика.

Ключевые особенности: - Автоматическое обнаружение корня проекта и файла конфигурации. - Поддержка форматов config.yml, config.yaml и config.ini (YAML в приоритете). - Удобные функции для доступа к настройкам, включая разрешение путей. - Асинхронные версии основных функций для неблокирующей работы. - Готовый к работе логгер с выводом в консоль и ротируемые файлы. - Безопасное хранение секретов через системное хранилище (keyring).

Основное использование:

Вам не нужно ничего инициализировать. Просто импортируйте и используйте:

from chutils import get_config_value, setup_logger, SecretManager

logger = setup_logger()
secrets = SecretManager("my_app")
db_host = get_config_value("Database", "host", "localhost")
logger.info(f"Подключение к базе данных на {db_host}")

Ручная инициализация (для нестандартных случаев):

Если автоматика не сработала, вы можете указать путь к корню проекта вручную:

import chutils
chutils.init(base_dir="/path/to/your/project")

__dir__()

Возвращает список всех доступных атрибутов для поддержки автодополнения и интроспекции.

__getattr__(name)

Реализация ленивой загрузки согласно PEP 562. Вызывается при обращении к атрибутам модуля, которые не определены явно.

init(base_dir)

Ручная инициализация пакета с указанием базовой директории проекта.

Эту функцию нужно вызывать только в том случае, если автоматическое определение корня проекта не сработало. Вызывать следует один раз в самом начале работы основного скрипта вашего приложения.

Parameters:

Name	Type	Description	Default
base_dir	str	Абсолютный путь к корневой директории проекта.	required

Raises:

Type	Description
ChutilsException	Если указанная директория не существует.

options: members: [init]

Модуль config

chutils.config

Модуль для работы с конфигурацией.

Обеспечивает автоматический поиск файла config.yml, config.yaml или config.ini в корне проекта и предоставляет удобные функции для чтения и сохранения настроек. Поддерживает кастомные уровни логирования при условии, что модуль logger загружен.

Переопределение конфигурации

Библиотека поддерживает многоуровневое переопределение настроек: 1. Переменные окружения (CH_[SECTION]_[KEY]): Имеют наивысший приоритет. 2. Локальный файл (config.local.yml): Переопределяет значения основного файла. 3. Основной файл (config.yml): Базовые настройки проекта.

Локальные файлы конфигурации (например, config.local.yml или config.local.ini) должны находиться в той же директории, что и основной файл. Это позволяет удобно управлять чувствительными или специфичными для разработчика настройками, не коммитя их в репозиторий.

T = TypeVar('T', bound='BaseModel') module-attribute

Тип для Pydantic моделей.

BaseConfigProvider

Bases: ABC

Абстрактный базовый класс для кастомного динамического провайдера конфигурации.

Реализуйте этот класс, чтобы интегрировать любой внешний источник настроек (БД, Redis, Consul, удалённый API и т.д.) в систему конфигурации chutils.

Провайдеры опрашиваются перед чтением локальных файлов конфигурации: если провайдер вернул значение (не None), оно используется без обращения к файлам.

Приоритет между несколькими провайдерами определяется параметром priority при регистрации: меньшее число → больший приоритет (аналогично DNS TTL).

Example

Минимальная реализация синхронного провайдера::

class EnvVaultProvider(BaseConfigProvider):
    def get_value(self, section: str, key: str) -> Any | None:
        return vault_client.get(f"{section}/{key}")

    async def aget_value(self, section: str, key: str) -> Any | None:
        return await async_vault_client.get(f"{section}/{key}")

aget_value(section, key) abstractmethod async

Асинхронно получает значение из провайдера.

Parameters:

Name	Type	Description	Default
section	str	Имя секции конфигурации.	required
key	str	Имя ключа внутри секции.	required

Returns:

Type	Description
Any | None	Значение из источника или None, если ключ не найден.

get_value(section, key) abstractmethod

Синхронно получает значение из провайдера.

Parameters:

Name	Type	Description	Default
section	str	Имя секции конфигурации.	required
key	str	Имя ключа внутри секции.	required

Returns:

Type	Description
Any | None	Значение из источника или None, если ключ не найден.

DictConfigProvider

Bases: BaseConfigProvider

Провайдер конфигурации на основе словаря в памяти.

Предназначен для использования в тестах (моки настроек) и для быстрого прототипирования. Полностью потокобезопасен при чтении, так как словарь не изменяется после инициализации.

Example

Использование в тестах с pytest::

import pytest
from chutils.config import register_provider, reset_providers
from chutils.config.custom_providers import DictConfigProvider

@pytest.fixture(autouse=True)
def mock_config():
    provider = DictConfigProvider({
        "database": {"host": "test-host", "port": "5432"},
        "app": {"debug": "true"},
    })
    register_provider(provider, priority=0)
    yield
    reset_providers()

Attributes:

Name	Type	Description
_data	dict[str, dict[str, Any]]	Вложенный словарь вида {section: {key: value}}.

__init__(data)

Инициализирует провайдер с заданным словарём.

Parameters:

Name	Type	Description	Default
data	dict[str, dict[str, Any]]	Вложенный словарь вида {section: {key: value}}. Ключи секций и ключей сравниваются без учёта регистра.	required

aget_value(section, key) async

Асинхронно возвращает значение из словаря.

Реализация не блокирует event loop, поскольку работает только с данными в памяти.

Parameters:

Name	Type	Description	Default
section	str	Имя секции (без учёта регистра).	required
key	str	Имя ключа (без учёта регистра).	required

Returns:

Type	Description
Any | None	Значение или None, если секция или ключ не найдены.

get_value(section, key)

Синхронно возвращает значение из словаря.

Parameters:

Name	Type	Description	Default
section	str	Имя секции (без учёта регистра).	required
key	str	Имя ключа (без учёта регистра).	required

Returns:

Type	Description
Any | None	Значение или None, если секция или ключ не найдены.

__getattr__(name)

Обеспечивает ленивую загрузку экспортируемых функций генератора и схемы.

aget_config(model=None) async

Асинхронная версия get_config.

Parameters:

Name	Type	Description	Default
model	type[T] | None	Опциональный класс Pydantic модели для валидации.	None

Returns:

Type	Description
JSONDict | T	Словарь конфигурации или экземпляр Pydantic модели.

aget_config_value(section, key, fallback=None, config=None, required=False) async

Асинхронно получает произвольное значение из конфигурации.

Сначала опрашивает зарегистрированные кастомные провайдеры через их асинхронный интерфейс aget_value. Если ни один из них не вернул значение, выполняет синхронный поиск в уже загруженном кэше конфигурации (через run_in_executor, чтобы не блокировать event loop).

Parameters:

Name	Type	Description	Default
section	str	Имя секции.	required
key	str	Имя ключа.	required
fallback	Any	Значение по умолчанию, если ключ не найден.	None
config	JSONDict | None	Опциональный, предварительно загруженный словарь конфигурации.	None
required	bool	Если True, выбросит ConfigKeyNotFoundError при отсутствии ключа.	False

Returns:

Type	Description
Any	Значение из конфигурации или fallback.

are_paths_initialized()

Проверяет, были ли инициализированы пути к проекту и файлам конфигурации.

Returns:

Type	Description
bool	True, если пути определены.

asave_config_value(section, key, value, cfg_file=None, save_to_local=False, notify=True) async

Асинхронно сохраняет одно значение в конфигурационном файле. Работает как асинхронная обертка вокруг синхронной save_config_value().

Parameters:

Name	Type	Description	Default
section	str	Имя секции.	required
key	str	Имя ключа в секции.	required
value	Any	Новое значение для ключа.	required
cfg_file	str | None	Опциональный путь к файлу для сохранения. Если указан, имеет приоритет над save_to_local.	None
save_to_local	bool	Если True, и существует локальный файл конфигурации (например, config.local.yml), значение будет сохранено в него. По умолчанию False.	False
notify	bool	Если True (по умолчанию), Hot-Reload watcher уведомит о смене конфигурации. Если False, уведомление будет подавлено.	True

Returns:

Name	Type	Description
True	bool	Если значение было успешно обновлено и сохранено.
False	bool	Если файл не найден, или произошла ошибка.

export_schema(model, output_path=None, indent=4)

Генерирует JSON Schema для Pydantic модели и опционально сохраняет в файл.

Parameters:

Name	Type	Description	Default
model	type[BaseModel] | str	Класс модели или строковый путь к нему ('module:Class').	required
output_path	str | Path | None	Путь к файлу для сохранения схемы.	None
indent	int	Отступ в результирующем JSON.	4

Returns:

Type	Description
str	Строка с JSON Schema.

generate_env_template(model_class, prefix='CH')

Генерирует .env шаблон (плоский формат).

Parameters:

Name	Type	Description	Default
model_class	type[BaseModel]	Класс Pydantic модели.	required
prefix	str	Префикс для имен переменных окружения.	'CH'

Returns:

Type	Description
str	Строковое представление сгенерированного .env-шаблона.

generate_json_schema(model_class)

Генерирует JSON схему на основе Pydantic модели.

Parameters:

Name	Type	Description	Default
model_class	type[BaseModel]	Класс Pydantic модели.	required

Returns:

Type	Description
str	JSON-строка схемы.

generate_yaml_template(model_class, indent=0)

Генерирует YAML шаблон на основе Pydantic модели с комментариями.

Parameters:

Name	Type	Description	Default
model_class	type[BaseModel]	Класс Pydantic модели.	required
indent	int	Начальный отступ в пробелах (уровень вложенности).	0

Returns:

Type	Description
str	Строковое представление сгенерированного YAML-шаблона.

get_all_config_paths(cfg_file=None)

Возвращает пути к основному, специфичному для окружения и локальному файлам конфигурации.

Parameters:

Name	Type	Description	Default
cfg_file	str | None	Опциональный путь к основному файлу.	None

Returns:

Type	Description
tuple[str | None, str | None, str | None]	Кортеж (путь_к_основному, путь_к_окружению, путь_к_локальному).

get_base_dir()

Возвращает абсолютный путь к корневой директории проекта.

Если пути еще не инициализированы, запускает автоматический поиск.

Returns:

Type	Description
str | None	Путь к корню проекта или None, если корень не найден.

get_config(model=None, remote_url=None, remote_auth=None, polling_interval=None, sse_url=None, sse_headers=None)

Загружает и объединяет конфигурацию из всех доступных источников.

Результат кэшируется. Повторные вызовы возвращают кэшированный объект, если он не был сброшен (например, при сохранении нового значения).

Порядок применения конфигураций (от меньшего приоритета к большему): 1. Основной файл (config.yml) 2. Файл окружения (config.{CH_ENV}.yml) 3. Локальный файл (config.local.yml) 4. Удаленный источник (если указан remote_url) 5. Переменные окружения (CH_SECTION_KEY)

Parameters:

Name	Type	Description	Default
model	type[T] | None	Опциональный класс Pydantic модели для валидации.	None
remote_url	str | None	URL для загрузки удаленной конфигурации.	None
remote_auth	tuple[str, str] | None	Кортеж (login, password) для Basic Auth.	None
polling_interval	int | None	Интервал опроса удаленного источника в секундах. Если не указан, опрос не запускается.	None
sse_url	str | None	URL для подключения к SSE-серверу событий об обновлениях.	None
sse_headers	dict[str, str] | None	HTTP-заголовки для подключений к SSE-серверу.	None

Returns:

Type	Description
JSONDict | T	Словарь со всей конфигурацией проекта или экземпляр Pydantic модели.
JSONDict | T	Если файлы не найдены, возвращается пустой словарь (или ошибка валидации модели).

Raises:

Type	Description
ConfigLoadError	Если произошла ошибка при чтении файлов конфигурации.
ConfigParseError	Если файлы конфигурации содержат синтаксические ошибки.
OptionalDependencyError	Если передана model, но пакет pydantic не установлен.

get_config_boolean(section, key, fallback=False, config=None, required=False)

Получает булево значение из конфигурации.

Распознает 'true', '1', 't', 'y', 'yes' как True и 'false', '0', 'f', 'n', 'no' как False (без учета регистра).

Parameters:

Name	Type	Description	Default
section	str	Имя секции.	required
key	str	Имя ключа.	required
fallback	bool	Значение по умолчанию, если ключ не найден или не может быть распознан как булево.	False
config	JSONDict | None	Опциональный, предварительно загруженный словарь конфигурации.	None
required	bool	Если True, выбросит ConfigKeyNotFoundError при отсутствии ключа.	False

Returns:

Type	Description
bool	True или False.

get_config_file_path()

Возвращает путь к основному файлу конфигурации, который используется в данный момент.

Returns:

Type	Description
str | None	Путь к файлу или None, если файл не найден.

get_config_float(section, key, fallback=0.0, config=None, required=False)

Получает дробное значение из конфигурации.

Parameters:

Name	Type	Description	Default
section	str	Имя секции.	required
key	str	Имя ключа.	required
fallback	float	Значение по умолчанию, если ключ не найден или не может быть преобразован в float.	0.0
config	JSONDict | None	Опциональный, предварительно загруженный словарь конфигурации.	None
required	bool	Если True, выбросит ConfigKeyNotFoundError при отсутствии ключа.	False

Returns:

Type	Description
float	Float или fallback.

get_config_int(section, key, fallback=0, config=None, required=False)

Получает целочисленное значение из конфигурации.

Parameters:

Name	Type	Description	Default
section	str	Имя секции.	required
key	str	Имя ключа.	required
fallback	int	Значение по умолчанию, если ключ не найден или не может быть преобразован в int.	0
config	JSONDict | None	Опциональный, предварительно загруженный словарь конфигурации.	None
required	bool	Если True, выбросит ConfigKeyNotFoundError при отсутствии ключа.	False

Returns:

Type	Description
int	Целое число из конфигурации или fallback.

get_config_list(section, key, fallback=None, config=None, required=False)

Получает значение как список из конфигурации.

Parameters:

Name	Type	Description	Default
section	str	Имя секции.	required
key	str	Имя ключа.	required
fallback	list[Any] | None	Значение по умолчанию, если ключ не найден.	None
config	JSONDict | None	Опциональный, предварительно загруженный словарь конфигурации.	None
required	bool	Если True, выбросит ConfigKeyNotFoundError при отсутствии ключа.	False

Returns:

Type	Description
list[Any]	Список из конфигурации или fallback. Если fallback не указан,
list[Any]	возвращается пустой список.

get_config_path(section, key, fallback=None, config=None, resolve_from_root=True, required=False)

Получает путь из конфигурации. Функция автоматически добавляет _BASE_DIR к относительным путям, если resolve_from_root установлено в True. Args: section: Имя секции. key: Имя ключа. fallback: Значение по умолчанию, если ключ не найден. config: Опциональный, предварительно загруженный словарь конфигурации. resolve_from_root: Если True, относительные пути будут разрешаться относительно _BASE_DIR. Если False, пути возвращаются как есть, без добавления _BASE_DIR. required: Если True, выбросит ConfigKeyNotFoundError при отсутствии ключа. Returns: Путь из конфигурации или fallback.

get_config_paths(cfg_file=None)

Возвращает пути к основному и локальному файлам конфигурации.

Legacy API для обратной совместимости. Возвращает кортеж из 2 элементов. Для получения всех путей (включая env) используйте get_all_config_paths().

Parameters:

Name	Type	Description	Default
cfg_file	str | None	Опциональный путь к основному файлу.	None

Returns:

Type	Description
tuple[str | None, str | None]	Кортеж (путь_к_основному, путь_к_локальному).

get_config_section(section_name, fallback=None, config=None, model=None, required=False)

get_config_section(
    section_name: str,
    fallback: JSONDict | None = None,
    config: JSONDict | None = None,
    model: None = None,
    required: bool = False,
) -> JSONDict

get_config_section(
    section_name: str,
    fallback: JSONDict | None = None,
    config: JSONDict | None = None,
    model: type[T] = ...,
    required: bool = False,
) -> T

Получает всю секцию конфигурации как словарь или Pydantic модель.

Parameters:

Name	Type	Description	Default
section_name	str	Имя секции.	required
fallback	JSONDict | None	Значение по умолчанию, если секция не найдена.	None
config	JSONDict | None	Опциональный, предварительно загруженный словарь конфигурации.	None
model	type[T] | None	Опциональный класс Pydantic модели для валидации секции.	None
required	bool	Если True, выбросит ConfigKeyNotFoundError при отсутствии секции.	False

Returns:

Type	Description
JSONDict | T	Словарь с содержимым секции или экземпляр Pydantic модели.
JSONDict | T	Если fallback не указан и секция не найдена, возвращается пустой словарь.

Raises:

Type	Description
ConfigLoadError	Если произошла ошибка при чтении файлов конфигурации.
ConfigParseError	Если файлы конфигурации содержат синтаксические ошибки.
OptionalDependencyError	Если передана model, но пакет pydantic не установлен.
ConfigKeyNotFoundError	Если секция не найдена и required=True.

get_config_value(section, key, fallback=None, config=None, required=False)

Получает произвольное значение из конфигурации.

Если значение не найдено или оно пустое, возвращает fallback. Поддерживает универсальное переопределение через переменные окружения по шаблону CH_[SECTION]_[KEY], если не установлено CH_DISABLE_ENV_OVERRIDE=true.

Порядок приоритетов (от высшего к низшему):

1. Зарегистрированные кастомные провайдеры (по их приоритету).
2. Переменные окружения CH_[SECTION]_[KEY].
3. Локальный файл конфигурации (config.local.yml).
4. Файл окружения (config.{CH_ENV}.yml).
5. Основной файл конфигурации (config.yml).

Parameters:

Name	Type	Description	Default
section	str	Имя секции.	required
key	str	Имя ключа.	required
fallback	Any	Значение по умолчанию, если ключ не найден или его значение пустое.	None
config	JSONDict | None	Опциональный, предварительно загруженный словарь конфигурации.	None
required	bool	Если True, выбросит ConfigKeyNotFoundError при отсутствии ключа или пустом значении.	False

Returns:

Type	Description
Any	Значение из конфигурации или fallback.

import_model_class(model_path)

Импортирует класс Pydantic модели по строковому пути.

Parameters:

Name	Type	Description	Default
model_path	str	Путь к модели в формате 'module.path:ClassName'.	required

Returns:

Type	Description
type[BaseModel]	Класс модели (BaseModel).

Raises:

Type	Description
ConfigParseError	Если формат пути некорректен или класс не найден.
OptionalDependencyError	Если Pydantic не установлен.

is_config_loaded()

Проверяет, была ли конфигурация уже загружена в память.

Returns:

Type	Description
bool	True, если кэш конфигурации заполнен.

load_ai_lint_config(cli_args=None)

Загружает и объединяет конфигурацию для ai-lint из всех источников.

Приоритет источников (от наивысшего к низшему): 1. CLI флаги (cli_args) 2. Переменные окружения (CH_DEV_AILINT_...) 3. Локальные yml файлы (секция Dev.AI-Lint) 4. pyproject.toml (секция [tool.chutils.ai-lint]) 5. Значения по умолчанию

Parameters:

Name	Type	Description	Default
cli_args	JSONDict | None	Аргументы командной строки.	None

Returns:

Type	Description
JSONDict	Объединенный словарь конфигурации ai-lint.

on_config_change(callback)

Регистрирует функцию обратного вызова, которая будет вызвана при изменении конфигурации.

Parameters:

Name	Type	Description	Default
callback	Callable[[], None]	Функция без аргументов.	required

parse_chutils_ignore(base_dir)

Парсит файл .chutilsignore и возвращает список шаблонов для игнорирования.

Parameters:

Name	Type	Description	Default
base_dir	str	Корневая директория, содержащая .chutilsignore.	required

Returns:

Type	Description
list[str]	Список шаблонов для игнорирования.

register_provider(provider, priority=100)

Регистрирует кастомный провайдер конфигурации.

Провайдеры опрашиваются перед чтением локальных файлов конфигурации. Если провайдер возвращает значение (не None), оно используется как итоговое.

Приоритет: меньшее число → выше приоритет (опрашивается первым).

Parameters:

Name	Type	Description	Default
provider	BaseConfigProvider	Экземпляр класса, реализующего :class:BaseConfigProvider.	required
priority	int	Числовой приоритет провайдера. По умолчанию: 100.	100

Example

::

from chutils.config import register_provider
from chutils.config.custom_providers import DictConfigProvider

provider = DictConfigProvider({"db": {"host": "prod-db"}})
register_provider(provider, priority=10)

reset_providers()

Очищает реестр всех зарегистрированных кастомных провайдеров.

Используется в тестах для сброса состояния между тест-кейсами, а также при необходимости переконфигурирования провайдеров в рантайме.

Example

::

from chutils.config import reset_providers

def teardown():
    reset_providers()

save_config_value(section, key, value, cfg_file=None, save_to_local=False, notify=True)

Сохраняет или обновляет одно значение в файле конфигурации.

Warning

Важно: При сохранении в .yml комментарии и форматирование будут утеряны. При сохранении в .ini - сохраняются.

Parameters:

Name	Type	Description	Default
section	str	Имя секции.	required
key	str	Имя ключа в секции.	required
value	Any	Новое значение для ключа.	required
cfg_file	str | None	Опциональный путь к файлу для сохранения. Если указан, имеет приоритет над save_to_local.	None
save_to_local	bool	Если True, и существует локальный файл конфигурации (например, config.local.yml), значение будет сохранено в него. По умолчанию False.	False
notify	bool	Если True (по умолчанию), Hot-Reload watcher уведомит о смене конфигурации. Если False, уведомление будет подавлено.	True

Returns:

Name	Type	Description
True	bool	Если значение было успешно обновлено и сохранено.
False	bool	Если файл не найден, или произошла ошибка.

start_config_watcher()

Запускает фоновый процесс отслеживания изменений в файлах конфигурации.

Требует установленного пакета watchdog.

Returns:

Type	Description
bool	True, если watcher успешно запущен.

Raises:

Type	Description
OptionalDependencyError	Если пакет watchdog не установлен.

start_webhook_server(host='0.0.0.0', port=8080, path='/webhook/config-reload', secret_token=None, hmac_secret=None)

Запускает встроенный Webhook-сервер для мгновенного обновления конфигурации.

Parameters:

Name	Type	Description	Default
host	str	Хост прослушивания (по умолчанию 0.0.0.0).	'0.0.0.0'
port	int	Порт прослушивания (0 — случайный порт).	8080
path	str	Путь эндпоинта (по умолчанию /webhook/config-reload).	'/webhook/config-reload'
secret_token	str | None	Опциональный токен авторизации.	None
hmac_secret	str | None	Опциональный секретный ключ HMAC-SHA256.	None

Returns:

Type	Description
Any	Экземпляр WebhookConfigServer.

stop_config_watcher()

Останавливает процесс отслеживания изменений конфигурации.

stop_webhook_server()

Останавливает запущенный встроенный Webhook-сервер.

trigger_reload()

Вызывает принудительную перезагрузку конфигурации и оповещает колбэки.

validate_required_keys(section, keys, config=None)

Проверяет наличие списка обязательных ключей в указанной секции конфигурации или словаре. Служит для групповой валидации за один проход. Выбрасывает ConfigValidationGroupError, если один или несколько ключей отсутствуют или пусты.

Parameters:

Name	Type	Description	Default
section	str | dict[str, Any]	Имя секции (str) или непосредственно словарь с данными (dict).	required
keys	list[str] | str	Список ключей (list[str]) или одиночный ключ (str).	required
config	JSONDict | None	Опциональный, предварительно загруженный словарь конфигурации.	None

Raises:

Type	Description
ConfigValidationGroupError	Если один или несколько ключей отсутствуют.

options: members:

• get_config
• aget_config
• get_config_value
• aget_config_value
• HttpConfigProvider
• get_config_int
• get_config_float
• get_config_boolean
• get_config_list
• get_config_section
• get_config_path
• save_config_value
• asave_config_value
• start_config_watcher
• stop_config_watcher
• on_config_change
• get_base_dir
• get_config_file_path
• is_config_loaded
• are_paths_initialized
• get_config_paths
• generate_yaml_template
• generate_env_template
• generate_json_schema
• export_schema
• import_model_class
• register_provider
• reset_providers
• BaseConfigProvider
• DictConfigProvider
• trigger_reload
• start_webhook_server
• stop_webhook_server
• SseConfigClient
• WebhookConfigServer
• verify_webhook_request
• create_fastapi_webhook_route
• create_flask_webhook_route

Модуль config.custom_providers (Custom Config Providers API)

chutils.config.custom_providers

API для кастомных динамических провайдеров конфигурации.

Позволяет регистрировать внешние источники настроек (БД, Key-Value хранилища, удалённые API) и интегрировать их в единый интерфейс chutils.config.

Пример использования::

from chutils.config import register_provider
from chutils.config.custom_providers import DictConfigProvider

provider = DictConfigProvider({"database": {"host": "localhost"}})
register_provider(provider, priority=10)

logger = logging.getLogger(__name__) module-attribute

Локальный логгер модуля.

BaseConfigProvider

Bases: ABC

Абстрактный базовый класс для кастомного динамического провайдера конфигурации.

Реализуйте этот класс, чтобы интегрировать любой внешний источник настроек (БД, Redis, Consul, удалённый API и т.д.) в систему конфигурации chutils.

Провайдеры опрашиваются перед чтением локальных файлов конфигурации: если провайдер вернул значение (не None), оно используется без обращения к файлам.

Приоритет между несколькими провайдерами определяется параметром priority при регистрации: меньшее число → больший приоритет (аналогично DNS TTL).

Example

Минимальная реализация синхронного провайдера::

class EnvVaultProvider(BaseConfigProvider):
    def get_value(self, section: str, key: str) -> Any | None:
        return vault_client.get(f"{section}/{key}")

    async def aget_value(self, section: str, key: str) -> Any | None:
        return await async_vault_client.get(f"{section}/{key}")

aget_value(section, key) abstractmethod async

Асинхронно получает значение из провайдера.

Parameters:

Name	Type	Description	Default
section	str	Имя секции конфигурации.	required
key	str	Имя ключа внутри секции.	required

Returns:

Type	Description
Any | None	Значение из источника или None, если ключ не найден.

get_value(section, key) abstractmethod

Синхронно получает значение из провайдера.

Parameters:

Name	Type	Description	Default
section	str	Имя секции конфигурации.	required
key	str	Имя ключа внутри секции.	required

Returns:

Type	Description
Any | None	Значение из источника или None, если ключ не найден.

DictConfigProvider

Bases: BaseConfigProvider

Провайдер конфигурации на основе словаря в памяти.

Предназначен для использования в тестах (моки настроек) и для быстрого прототипирования. Полностью потокобезопасен при чтении, так как словарь не изменяется после инициализации.

Example

Использование в тестах с pytest::

import pytest
from chutils.config import register_provider, reset_providers
from chutils.config.custom_providers import DictConfigProvider

@pytest.fixture(autouse=True)
def mock_config():
    provider = DictConfigProvider({
        "database": {"host": "test-host", "port": "5432"},
        "app": {"debug": "true"},
    })
    register_provider(provider, priority=0)
    yield
    reset_providers()

Attributes:

Name	Type	Description
_data	dict[str, dict[str, Any]]	Вложенный словарь вида {section: {key: value}}.

__init__(data)

Инициализирует провайдер с заданным словарём.

Parameters:

Name	Type	Description	Default
data	dict[str, dict[str, Any]]	Вложенный словарь вида {section: {key: value}}. Ключи секций и ключей сравниваются без учёта регистра.	required

aget_value(section, key) async

Асинхронно возвращает значение из словаря.

Реализация не блокирует event loop, поскольку работает только с данными в памяти.

Parameters:

Name	Type	Description	Default
section	str	Имя секции (без учёта регистра).	required
key	str	Имя ключа (без учёта регистра).	required

Returns:

Type	Description
Any | None	Значение или None, если секция или ключ не найдены.

get_value(section, key)

Синхронно возвращает значение из словаря.

Parameters:

Name	Type	Description	Default
section	str	Имя секции (без учёта регистра).	required
key	str	Имя ключа (без учёта регистра).	required

Returns:

Type	Description
Any | None	Значение или None, если секция или ключ не найдены.

get_registry()

Возвращает глобальный реестр кастомных провайдеров.

Returns:

Type	Description
_CustomProviderRegistry	Глобальный экземпляр :class:_CustomProviderRegistry.

options: members:

• BaseConfigProvider
• DictConfigProvider

Модуль logger

chutils.logger

Модуль для настройки логирования.

Этот пакет разделен на модули для соблюдения SRP: - core: Основной класс логгера и setup_logger. - masking: Фильтрация секретов. - formatters: Форматирование (Text, JSON). - handlers: Обработчики файлов (ротация, сжатие).

options: members:

• setup_logger
• setup_logger_from_config
• ChutilsLogger
• DEVDEBUG_LEVEL_NUM
• MEDIUMDEBUG_LEVEL_NUM
• FlappingFilter
• add_global_handler
• remove_global_handler
• get_global_handlers
• clear_global_handlers
• InterceptHandler
• capture_standard_logging
• intercept_all
• restore_standard_logging

Модуль context

chutils.context

ContextFilter

Bases: Filter

Фильтр, обогащающий LogRecord данными из контекста.

Добавляет: - Индивидуальные ключи контекста как атрибуты (для %(key)s). - record.context: Строка вида "[key1=val1 key2=val2 ]" или "" если пусто. - record.context_dict: Оригинальный словарь контекста (для JSON-логирования).

filter(record)

Обогащает запись лога контекстными данными.

Parameters:

Name	Type	Description	Default
record	LogRecord	Запись лога, которую необходимо отфильтровать/обогатить.	required

Returns:

Type	Description
bool	Всегда возвращает True для продолжения обработки записи.

bind_context(**kwargs)

Привязывает значения к текущему контексту.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Ключи и значения для привязки к контексту.	{}

Returns:

Type	Description
Token[dict[str, Any] | None]	Токен для последующей очистки контекста через unbind_context.

clear_context()

Полностью очищает текущий контекст.

get_context()

Возвращает копию текущего контекста.

Returns:

Type	Description
dict[str, Any]	Словарь с текущими контекстными переменными.

unbind_context(token)

Восстанавливает контекст до состояния, предшествующего bind_context.

Parameters:

Name	Type	Description	Default
token	Token[dict[str, Any] | None]	Токен, возвращенный соответствующим вызовом bind_context.	required

options: members:

• bind_context
• unbind_context
• clear_context
• ContextFilter

Модуль lifecycle (Управление жизненным циклом)

chutils.lifecycle

Управление жизненным циклом приложения.

Обеспечивает механизмы регистрации функций очистки (cleanup callbacks), которые будут выполнены при завершении работы приложения.

CleanupCallback = Callable[[], Any] | Callable[[], Awaitable[Any]] module-attribute

Тип для функций очистки.

AsyncLifecycleContext

Контекстный менеджер для управления жизненным циклом ресурсов приложения.

Поддерживает протоколы async with и with.

__aenter__() async

Вход в асинхронный контекстный менеджер.

__aexit__(exc_type, exc_val, exc_tb) async

Выход из асинхронного контекстного менеджера.

__enter__()

Вход в синхронный контекстный менеджер.

__exit__(exc_type, exc_val, exc_tb)

Выход из синхронного контекстного менеджера.

__init__(setup_signals=True, auto_cleanup_subsystems=True, manager=None)

Инициализирует контекстный менеджер жизненного цикла.

Parameters:

Name	Type	Description	Default
setup_signals	bool	Автоматически перехватывать сигналы завершения ОС (SIGINT, SIGTERM).	True
auto_cleanup_subsystems	bool	Автоматически очищать подсистемы chutils (db, tasks, logger).	True
manager	LifecycleManager | None	Опциональный менеджер жизненного цикла (по умолчанию глобальный).	None

LifecycleManager

Менеджер жизненного цикла, управляющий реестром функций очистки.

__init__()

Инициализирует LifecycleManager.

get_cleanup_callbacks()

Возвращает список зарегистрированных функций в порядке LIFO.

Returns:

Type	Description
list[CleanupCallback]	Список функций очистки в порядке LIFO.

register_cleanup(func)

Регистрирует функцию для выполнения при завершении работы.

Функции выполняются в порядке LIFO (Last-In-First-Out). Поддерживаются как синхронные, так и асинхронные функции.

Parameters:

Name	Type	Description	Default
func	CleanupCallback	Функция или корутина для регистрации.	required

Returns:

Type	Description
CleanupCallback	Та же функция (позволяет использовать как декоратор).

restore_signals()

Восстанавливает исходные обработчики сигналов ОС.

setup_graceful_shutdown(signals=None)

Настраивает перехват сигналов завершения работы.

Parameters:

Name	Type	Description	Default
signals	list[int] | None	Опциональный список сигналов для отслеживания.	None

unregister_cleanup(func)

Удаляет функцию из реестра функций очистки.

Parameters:

Name	Type	Description	Default
func	CleanupCallback	Функция или корутина для удаления.	required

Returns:

Type	Description
bool	True, если функция была найдена и удалена, иначе False.

async_run_cleanup() async

Асинхронно выполняет все зарегистрированные функции очистки LIFO.

lifecycle(setup_signals=True, auto_cleanup_subsystems=True)

Возвращает контекстный менеджер для управления жизненным циклом ресурсов.

Parameters:

Name	Type	Description	Default
setup_signals	bool	Перехватывать сигналы ОС (SIGINT, SIGTERM).	True
auto_cleanup_subsystems	bool	Очищать подсистемы chutils при выходе.	True

Returns:

Type	Description
AsyncLifecycleContext	Экземпляр AsyncLifecycleContext, поддерживающий async with и with.

Example

async with chutils.lifecycle(setup_signals=True):
    await app.run()

register_cleanup(func)

Регистрирует функцию очистки в менеджере.

Эта функция является публичным API для добавления колбэков, которые будут вызваны при завершении работы приложения.

Parameters:

Name	Type	Description	Default
func	CleanupCallback	Функция-колбэк, которую нужно зарегистрировать. Должна соответствовать типу CleanupCallback.	required

Returns:

Type	Description
CleanupCallback	Зарегистрированная функция (возвращает тот же объект для
CleanupCallback	использования в качестве декоратора).

Example

Использование в качестве декоратора: @register_cleanup async def close_db(): await db.close()

Использование как обычной функции: def cleanup_logs(): print("Cleaning up logs...") register_cleanup(cleanup_logs)

run_cleanup()

Выполняет все зарегистрированные функции очистки LIFO (безопасно для вызова из синхронного кода и активных Event Loop).

setup_graceful_shutdown()

Публичный API для настройки Graceful Shutdown.

Рекомендуется вызывать в самом начале работы приложения.

unregister_cleanup(func)

Удаляет функцию из реестра функций очистки.

Parameters:

Name	Type	Description	Default
func	CleanupCallback	Функция или корутина для удаления.	required

Returns:

Type	Description
bool	True, если функция была найдена и удалена, иначе False.

options: members:

• register_cleanup
• setup_graceful_shutdown
• run_cleanup
• async_run_cleanup
• lifecycle
• async_lifecycle
• AsyncLifecycleContext

Модуль cli_booster (Быстрое создание CLI)

chutils.cli_booster

Модуль для быстрого создания консольных команд (CLI Booster).

Предоставляет декоратор @cli_command, который превращает обычную функцию в полноценную CLI-утилиту с автоматическим парсингом аргументов.

F = TypeVar('F', bound=Callable[..., Any]) module-attribute

Тип для декорируемой функции.

cli_command(func)

Декоратор для превращения функции в CLI-команду.

Интроспектирует сигнатуру функции и создает парсер аргументов argparse. Поддерживает аннотации типов, значения по умолчанию, асинхронные функции и автоматический парсинг докстрингов (Google-style) для генерации справки.

Parameters:

Name	Type	Description	Default
func	F	Декорируемая функция.	required

Returns:

Type	Description
F	Обертка функции, поддерживающая CLI-интерфейс.

Example

@cli_command def my_script(name: str, count: int = 1): """ Пример скрипта.

Args:
    name (str): Имя пользователя.
    count (int): Количество повторений.
"""
for _ in range(count):
    print(f"Hello, {name}!")

options: members:

• cli_command

Модуль time (Работа со временем)

chutils.time

Модуль для работы со временем и датами. Обеспечивает UTC-first подход, корректную обработку часовых поясов и парсинг.

humanize_timedelta(dt, locale='ru', custom_locales=None)

Превращает дату, timedelta или количество секунд в человекочитаемую строку относительно текущего времени.

Parameters:

Name	Type	Description	Default
dt	datetime | timedelta | float	Дата (datetime), интервал (timedelta) или количество секунд (int/float).	required
locale	str	Код локали ('ru' или 'en').	'ru'
custom_locales	dict[str, Any] | None	Дополнительные локали или переопределения.	None

Returns:

Type	Description
str	Строка вида "5 минут назад", "вчера" и т.д.

parse_datetime(value)

Парсит дату и время из различных форматов и приводит к UTC aware объекту.

Поддерживаемые форматы: - ISO 8601 строки (например, "2023-01-01T12:00:00"). - UNIX timestamps в секундах (int/float). - UNIX timestamps в миллисекундах (длинные числа).

Если установлена библиотека python-dateutil (chutils[date]), поддерживается более широкий спектр форматов.

Parameters:

Name	Type	Description	Default
value	str | float	Строка с датой или числовое представление (timestamp).	required

Returns:

Type	Description
datetime	Объект datetime в зоне UTC.

Raises:

Type	Description
ValueError	Если формат не распознан.

utc_now()

Возвращает текущее время в формате UTC с информацией о часовом поясе.

Returns:

Type	Description
datetime	Объект datetime, представляющий текущее время в UTC.

options: members:

• utc_now
• parse_datetime
• humanize_timedelta

Модуль tracing (Распределенное трассирование)

chutils.tracing

IS_OTEL_AVAILABLE = OTEL_AVAILABLE module-attribute

Флаг доступности OpenTelemetry, используемый для обратной совместимости.

get_current_trace_context()

Возвращает текущие trace_id и span_id, если трассировка активна.

Returns:

Type	Description
dict[str, str] | None	Словарь с trace_id и span_id или None.

get_tracer(name='chutils')

Возвращает экземпляр трейсера, если OpenTelemetry доступен.

Parameters:

Name	Type	Description	Default
name	str	Имя трейсера.	'chutils'

Returns:

Type	Description
Any	Экземпляр Tracer или None, если OTel не установлен.

setup_tracing(service_name, exporter_type='console', otlp_endpoint=None, otlp_protocol='grpc')

Настраивает OpenTelemetry SDK для сбора трасс.

Parameters:

Name	Type	Description	Default
service_name	str	Имя сервиса для отображения в трассах.	required
exporter_type	str	Тип экспортера: 'console' или 'otlp'.	'console'
otlp_endpoint	str | None	URL эндпоинта для OTLP (например, http://localhost:4317).	None
otlp_protocol	str	Протокол для OTLP: 'grpc' или 'http/protobuf'.	'grpc'

Returns:

Type	Description
bool	True, если настройка выполнена успешно, False если OTel недоступен.

trace(name=None, attributes=None, capture_kwargs=False)

Декоратор для автоматического создания спана при вызове функции. Поддерживает как синхронные, так и асинхронные функции.

Если OpenTelemetry не установлен, декоратор просто возвращает оригинальную функцию без накладных расходов.

Parameters:

Name	Type	Description	Default
name	str | Callable[P, R] | None	Имя спана. По умолчанию используется имя функции. Может использоваться как позиционный аргумент при @trace("имя").	None
attributes	dict[str, Any] | None	Дополнительные атрибуты для спана.	None
capture_kwargs	bool	Если True, аргументы функции будут добавлены как атрибуты спана с префиксом 'arg.'.	False

Returns:

Type	Description
Any	Декоратор для создания спана или саму декорируемую функцию.

Example

@trace()
def my_func(x):
    return x + 1

@trace("custom_name", capture_kwargs=True)
async def my_async_func(y):
    return y * 2

options: members:

• trace
• setup_tracing
• IS_OTEL_AVAILABLE

Модуль features (Фича-флаги)

chutils.features

Модуль для управления фича-флагами (Feature Flags).

Позволяет переключать функциональность на лету через конфигурационные файлы. Поддерживает булевы флаги, фильтры по окружению и процентное раскатывание.

get_features()

Загружает и кэширует фича-флаги.

Приоритет источников: 1. Файл features.yml (или features.yaml) в корне проекта. 2. Секция feature_flags или FeatureFlags в основном config.yml.

Returns:

Type	Description
dict[str, Any]	Словарь с конфигурацией фича-флагов.

is_feature_enabled(feature_name, context=None)

Проверяет, включена ли указанная фича.

Parameters:

Name	Type	Description	Default
feature_name	str	Уникальное имя фичи.	required
context	dict[str, Any] | None	Опциональный контекст для вычисления (например, {'user_id': 123}).	None

Returns:

Type	Description
bool	True, если фича включена. False во всех остальных случаях (включая отсутствие фичи).

require_feature(feature_name, fallback=None)

Декоратор для ограничения доступа к функции на основе фича-флага.

Если фича включена, вызывается оригинальная функция. Если выключена: - И задан fallback, вызывается он. - И fallback не задан, возвращается None.

Контекст для вычисления флага может быть передан через именованный аргумент context.

Parameters:

Name	Type	Description	Default
feature_name	str	Имя фичи.	required
fallback	Callable[..., Any] | None	Опциональная функция для вызова при выключенной фиче.	None

Returns:

Type	Description
Callable[..., Any]	Декоратор.

options: members:

• is_feature_enabled
• require_feature

Модуль cache (Умное кэширование)

chutils.cache

BaseCacheBackend

Bases: ABC, Generic[T]

Базовый абстрактный класс для всех бэкендов кэширования.

Определяет единый интерфейс для синхронных и асинхронных операций.

aclear() async

Асинхронная очистка кэша.

adelete(key) async

Асинхронное удаление значения из кэша.

Parameters:

Name	Type	Description	Default
key	str	Ключ кэша.	required

aexists(key) async

Асинхронная проверка наличия ключа в кэше.

Parameters:

Name	Type	Description	Default
key	str	Ключ кэша.	required

Returns:

Type	Description
bool	True, если ключ существует и не просрочен, иначе False.

aget(key) async

Асинхронное получение значения из кэша.

Parameters:

Name	Type	Description	Default
key	str	Ключ кэша.	required

Returns:

Type	Description
T | None	Значение или None, если ключ не найден или просрочен.

ainvalidate_tag(tag) async

Асинхронное удаление всех ключей, связанных с указанным тегом.

Parameters:

Name	Type	Description	Default
tag	str	Тег для инвалидации.	required

aset(key, value, ttl=None, tags=None) async

Асинхронное сохранение значения в кэше.

Parameters:

Name	Type	Description	Default
key	str	Ключ кэша.	required
value	T	Значение для сохранения.	required
ttl	int | None	Время жизни в секундах.	None
tags	list[str] | None	Список тегов для связывания с ключом.	None

clear() abstractmethod

Очистить весь кэш.

delete(key) abstractmethod

Удалить ключ из кэша.

Parameters:

Name	Type	Description	Default
key	str	Ключ кэша.	required

exists(key) abstractmethod

Проверить наличие ключа в кэше.

Parameters:

Name	Type	Description	Default
key	str	Ключ кэша.	required

Returns:

Name	Type	Description
bool	bool	True, если ключ существует и не просрочен.

get(key) abstractmethod

Получить значение из кэша.

Parameters:

Name	Type	Description	Default
key	str	Ключ кэша.	required

Returns:

Type	Description
T | None	Значение или None, если ключ не найден или просрочен.

invalidate_tag(tag) abstractmethod

Удалить все ключи, связанные с указанным тегом.

Parameters:

Name	Type	Description	Default
tag	str	Тег для инвалидации.	required

set(key, value, ttl=None, tags=None) abstractmethod

Сохранить значение в кэше.

Parameters:

Name	Type	Description	Default
key	str	Ключ кэша.	required
value	T	Значение для сохранения.	required
ttl	Optional[int]	Время жизни в секундах. Если None, используется вечное хранение.	None
tags	Optional[list[str]]	Список тегов для связывания с ключом.	None

InMemoryCacheBackend

Bases: BaseCacheBackend[T]

Реализация кэша в оперативной памяти на базе словаря.

Поддерживает TTL, потокобезопасность и ленивую очистку просроченных записей.

__init__()

Инициализирует бэкенд кэширования в памяти.

aclear() async

Асинхронная очистка кэша.

adelete(key) async

Асинхронно удаляет запись из кэша по ключу.

Parameters:

Name	Type	Description	Default
key	str	Ключ для удаления.	required

aexists(key) async

Асинхронно проверяет существование ключа в кэше.

Parameters:

Name	Type	Description	Default
key	str	Ключ для проверки.	required

Returns:

Type	Description
bool	True, если ключ существует и не просрочен, иначе False.

aget(key) async

Асинхронно получает значение по ключу.

Parameters:

Name	Type	Description	Default
key	str	Ключ кэша.	required

Returns:

Type	Description
T | None	Значение из кэша или None, если оно отсутствует или просрочено.

ainvalidate_tag(tag) async

Асинхронно удаляет все ключи, связанные с указанным тегом.

Parameters:

Name	Type	Description	Default
tag	str	Тег для инвалидации.	required

aset(key, value, ttl=None, tags=None) async

Асинхронно сохраняет значение с TTL и тегами.

Parameters:

Name	Type	Description	Default
key	str	Ключ кэша.	required
value	T	Сохраняемое значение.	required
ttl	int | None	Время жизни записи в секундах.	None
tags	list[str] | None	Список тегов для связывания с ключом.	None

clear()

Полная очистка.

delete(key)

Удаляет запись из кэша по ключу.

Parameters:

Name	Type	Description	Default
key	str	Ключ для удаления.	required

exists(key)

Проверить наличие ключа в кэше.

Parameters:

Name	Type	Description	Default
key	str	Ключ кэша.	required

Returns:

Name	Type	Description
bool	bool	True, если ключ существует и не просрочен.

get(key)

Получает значение по ключу. Если значение просрочено - удаляет его.

Parameters:

Name	Type	Description	Default
key	str	Ключ кэша.	required

Returns:

Type	Description
T | None	Значение из кэша или None, если оно отсутствует или просрочено.

invalidate_tag(tag)

Удаляет все ключи, связанные с указанным тегом.

Parameters:

Name	Type	Description	Default
tag	str	Тег для инвалидации.	required

set(key, value, ttl=None, tags=None)

Сохраняет значение с заданным TTL и тегами.

Parameters:

Name	Type	Description	Default
key	str	Ключ кэша.	required
value	T	Сохраняемое значение.	required
ttl	int | None	Время жизни записи в секундах.	None
tags	list[str] | None	Список тегов для связывания с ключом.	None

cache_with_ttl(ttl=60, key_prefix='', sliding=True, backend=None, tags=None)

Декоратор для кэширования результатов выполнения функций с поддержкой TTL.

Декорированная функция получает дополнительные методы управления кэшем: * invalidate(*args, **kwargs) / ainvalidate(*args, **kwargs) — удаляет запись из кэша для указанных аргументов. * invalidate_all() / ainvalidate_all() — полностью очищает все записи этой функции. * invalidate_tag(tag) / ainvalidate_tag(tag) — сбрасывает все записи кэша, помеченные данным тегом.

Parameters:

Name	Type	Description	Default
ttl	int	Время жизни закэшированного значения в секундах. По умолчанию 60.	60
key_prefix	str	Префикс для ключа кэша.	''
sliding	bool	Если True, TTL продлевается при каждом успешном чтении из кэша.	True
backend	InMemoryCacheBackend[Any] | None	Инстанс бэкенда для хранения (по умолчанию InMemoryCacheBackend).	None
tags	list[str] | Callable[..., list[str] | str] | None	Статические теги (list[str]) или вызываемый объект (callable), принимающий те же аргументы, что и декорируемая функция, и генерирующий тег или список тегов.	None

Returns:

Name	Type	Description
Callable	Callable[..., Any]	Обернутая функция со встроенными методами инвалидации.

options: members:

• cache_with_ttl
• BaseCacheBackend
• InMemoryCacheBackend

Модуль secret_manager

chutils.secret_manager

DotEnvProvider

Bases: SecretProvider

Провайдер для работы с .env файлами. Обеспечивает загрузку переменных окружения из файла при первом обращении.

__init__(dotenv_path=None)

Инициализирует провайдер.

Parameters:

Name	Type	Description	Default
dotenv_path	str | None	Явный путь к .env файлу. Если не указан, ищется в корне проекта.	None

delete(key, service_name)

DotEnvProvider не поддерживает удаление.

Parameters:

Name	Type	Description	Default
key	str	Имя секрета.	required
service_name	str	Имя сервиса.	required

Returns:

Type	Description
bool	Всегда False, так как удаление не поддерживается.

get(key, service_name)

Получает значение из загруженных .env данных.

Parameters:

Name	Type	Description	Default
key	str	Имя запрашиваемого секрета.	required
service_name	str	Имя сервиса/приложения.	required

Returns:

Type	Description
str | None	Значение секрета или None, если он не найден.

set(key, value, service_name)

DotEnvProvider не поддерживает сохранение (доступен только для чтения).

Parameters:

Name	Type	Description	Default
key	str	Имя секрета.	required
value	str	Значение секрета.	required
service_name	str	Имя сервиса.	required

Returns:

Type	Description
bool	Всегда False, так как запись не поддерживается.

EnvProvider

Bases: SecretProvider

Провайдер для работы с переменными окружения ОС (os.environ).

delete(key, service_name)

EnvProvider не поддерживает удаление.

Parameters:

Name	Type	Description	Default
key	str	Имя секрета.	required
service_name	str	Имя сервиса.	required

Returns:

Type	Description
bool	Всегда False, так как удаление не поддерживается.

get(key, service_name)

Получает значение из переменных окружения ОС.

Parameters:

Name	Type	Description	Default
key	str	Имя запрашиваемого секрета.	required
service_name	str	Имя сервиса/приложения.	required

Returns:

Type	Description
str | None	Значение секрета или None, если он не найден.

set(key, value, service_name)

EnvProvider не поддерживает сохранение.

Parameters:

Name	Type	Description	Default
key	str	Имя секрета.	required
value	str	Значение секрета.	required
service_name	str	Имя сервиса.	required

Returns:

Type	Description
bool	Всегда False, так как запись не поддерживается.

KeyringProvider

Bases: SecretProvider

Провайдер для работы с системным хранилищем (keyring). Использует возможности ОС (Windows Credential Locker, macOS Keychain, KWallet/Secret Service).

__init__(disable_keyring=False)

Инициализирует провайдер.

Parameters:

Name	Type	Description	Default
disable_keyring	bool	Если True, все операции с keyring будут отключены.	False

delete(key, service_name)

Удаляет пароль из системного хранилища.

Parameters:

Name	Type	Description	Default
key	str	Имя удаляемого секрета.	required
service_name	str	Имя сервиса/приложения.	required

Returns:

Type	Description
bool	True, если удаление успешно, иначе False.

get(key, service_name)

Получает пароль из системного хранилища.

Parameters:

Name	Type	Description	Default
key	str	Имя запрашиваемого секрета.	required
service_name	str	Имя сервиса/приложения.	required

Returns:

Type	Description
str | None	Значение секрета или None, если он не найден.

set(key, value, service_name)

Сохраняет пароль в системное хранилище.

Parameters:

Name	Type	Description	Default
key	str	Имя секрета.	required
value	str	Сохраняемое значение секрета.	required
service_name	str	Имя сервиса/приложения.	required

Returns:

Type	Description
bool	True, если сохранение успешно, иначе False.

SecretManager

Универсальный менеджер для управления секретами через цепочку провайдеров.

Позволяет получать, сохранять и удалять секреты, используя различные стратегии (Keyring, .env, переменные окружения и т.д.).

__init__(service_name=None, prefix=None, auto_mask_logs=True, providers=None)

Инициализирует менеджер секретов.

Parameters:

Name	Type	Description	Default
service_name	str | None	Уникальное имя сервиса. Если не указано, определяется автоматически.	None
prefix	str | None	Префикс для имени сервиса (по умолчанию "Chutils_").	None
auto_mask_logs	bool	Если True, полученные секреты будут маскироваться в логах.	True
providers	list[SecretProvider] | None	Список провайдеров. Если None, создается стандартная цепочка.	None

Raises:

Type	Description
SecretError	Если не удалось автоматически определить service_name.

add_provider(provider, index=None)

Добавляет новый провайдер в цепочку.

Parameters:

Name	Type	Description	Default
provider	SecretProvider	Экземпляр провайдера.	required
index	int | None	Позиция в списке. Если None, добавляется в конец.	None

adelete_secret(key) async

Асинхронно удаляет секрет.

Parameters:

Name	Type	Description	Default
key	str	Имя удаляемого секрета.	required

Returns:

Type	Description
bool	True при успехе, иначе False.

aget_secret(key, fallback=None, required=False) async

Асинхронно получает секрет.

Parameters:

Name	Type	Description	Default
key	str	Имя секрета.	required
fallback	str | None	Значение по умолчанию.	None
required	bool	Флаг обязательности.	False

Returns:

Type	Description
str | None	Значение секрета или fallback.

asave_secret(key, value) async

Асинхронно сохраняет секрет.

Parameters:

Name	Type	Description	Default
key	str	Имя секрета.	required
value	str	Значение секрета.	required

Returns:

Type	Description
bool	True при успехе, иначе False.

delete_secret(key)

Удаляет секрет во всех провайдерах, поддерживающих удаление.

Parameters:

Name	Type	Description	Default
key	str	Имя удаляемого секрета.	required

Returns:

Type	Description
bool	True, если секрет был успешно удален хотя бы из одного провайдера, иначе False.

get_secret(key, fallback=None, required=False)

Получает секрет, опрашивая провайдеры по порядку.

Parameters:

Name	Type	Description	Default
key	str	Имя запрашиваемого секрета.	required
fallback	str | None	Значение по умолчанию, если секрет не найден.	None
required	bool	Флаг обязательности. Если True, выбрасывает исключение SecretNotFoundError при отсутствии.	False

Returns:

Type	Description
str | None	Значение секрета или fallback.

save_secret(key, value)

Сохраняет секрет в первом провайдере, поддерживающем запись.

Parameters:

Name	Type	Description	Default
key	str	Имя секрета.	required
value	str	Значение секрета.	required

Returns:

Type	Description
bool	True, если сохранение успешно, иначе False.

update_secret(key, value)

Обновляет секрет (псевдоним для save_secret).

Parameters:

Name	Type	Description	Default
key	str	Имя секрета.	required
value	str	Новое значение секрета.	required

Returns:

Type	Description
bool	True, если обновление успешно, иначе False.

SecretProvider

Bases: ABC

Абстрактный базовый класс для провайдеров секретов. Определяет интерфейс стратегии для различных механизмов хранения.

delete(key, service_name) abstractmethod

Удалить секрет.

Parameters:

Name	Type	Description	Default
key	str	Имя секрета.	required
service_name	str	Имя сервиса.	required

Returns:

Type	Description
bool	True, если удаление прошло успешно, иначе False.

get(key, service_name) abstractmethod

Получить значение секрета по ключу.

Parameters:

Name	Type	Description	Default
key	str	Имя секрета.	required
service_name	str	Имя сервиса (используется для изоляции в хранилищах типа keyring).	required

Returns:

Type	Description
str | None	Значение секрета или None, если секрет не найден.

set(key, value, service_name) abstractmethod

Сохранить значение секрета.

Parameters:

Name	Type	Description	Default
key	str	Имя секрета.	required
value	str	Значение секрета.	required
service_name	str	Имя сервиса.	required

Returns:

Type	Description
bool	True, если сохранение прошло успешно, иначе False.

Модуль config.diagnostics (Отладка конфигурации)

chutils.config.diagnostics

Логика формирования диагностических отчетов по конфигурации.

SECRET_KEYWORDS = {'password', 'secret', 'api_key', 'token', 'auth', 'key', 'pwd', 'credential'} module-attribute

Список ключевых слов, значения которых должны маскироваться по умолчанию.

format_trace(trace_data, format_type='tree', show_secrets=False)

Форматирует данные трассировки в выбранный формат.

Parameters:

Name	Type	Description	Default
trace_data	dict[str, dict[str, list[dict[str, Any]]]]	Данные трассировки конфигурации.	required
format_type	str	Тип форматирования ('tree', 'table', 'json').	'tree'
show_secrets	bool	Флаг принудительного показа секретов без маскирования.	False

Returns:

Type	Description
str	Отформатированная строка с диагностическим отчетом.

mask_value(key, value, show_secrets=False)

Маскирует значение, если ключ похож на секрет.

Parameters:

Name	Type	Description	Default
key	str	Имя ключа.	required
value	Any	Значение ключа.	required
show_secrets	bool	Флаг принудительного показа секретов без маскирования.	False

Returns:

Type	Description
str	Строковое представление значения (возможно маскированное).

handler: python

Модуль fs

chutils.fs

Модуль для надежных операций с файловой системой. Обеспечивает атомарную запись, безопасное создание директорий и работу с временными файлами.

atomic_write(file_path, data, mode='w', encoding='utf-8', **kwargs)

Атомарная запись данных в файл.

Данные сначала записываются во временный файл в той же директории, после чего выполняется атомарная замена целевого файла (os.replace). Это гарантирует, что файл не будет поврежден при сбое во время записи.

Поддерживает автоматическую сериализацию для JSON и YAML на основе расширения файла.

Parameters:

Name	Type	Description	Default
file_path	str | Path	Путь к целевому файлу.	required
data	Any	Данные для записи. Может быть строкой, байтами, словарем или списком.	required
mode	str	Режим открытия файла ('w' или 'wb').	'w'
encoding	str	Кодировка (только для текстового режима).	'utf-8'
**kwargs	Any	Дополнительные аргументы для json.dump или yaml.dump.	{}

Raises:

Type	Description
OptionalDependencyError	Если выполняется запись в YAML, но пакет pyyaml не установлен.
OSError	При ошибках ввода-вывода.

cleanup_paths(*paths, retries=3, delay=0.1, on_locked='warn', orphan_collision='raise')

Пакетное удаление нескольких путей.

Вызывает remove_path для каждого пути. Если on_locked == "warn" или "rename_orphan", ошибки для отдельных путей не прерывают обход остальных. При "raise" выполнение прерывается на первой же ошибке после исчерпания попыток.

Parameters:

Name	Type	Description	Default
paths	str | Path	Пути к удаляемым объектам.	()
retries	int	Количество повторных попыток.	3
delay	float	Задержка между попытками в секундах.	0.1
on_locked	Literal['raise', 'rename_orphan', 'warn']	Поведение при блокировке.	'warn'
orphan_collision	Literal['raise', 'overwrite', 'unique']	Поведение при коллизиях orphan-файлов.	'raise'

Raises:

Type	Description
OSError	Если удаление не удалось и on_locked == "raise".

ensure_dir(path)

Гарантирует существование директории. Создает все родительские директории, если они не существуют.

Parameters:

Name	Type	Description	Default
path	str | Path	Путь к директории (строка или pathlib.Path).	required

Returns:

Type	Description
Path	Объект pathlib.Path.

get_temp_file(suffix='')

Контекстный менеджер для работы с временным файлом. Файл автоматически удаляется при выходе из блока with.

Parameters:

Name	Type	Description	Default
suffix	str	Суффикс (расширение) временного файла.	''

Yields:

Type	Description
Path	Объект pathlib.Path к временному файлу.

remove_path(path, *, retries=3, delay=0.1, on_locked='warn', orphan_collision='raise')

Безопасно удаляет файл или директорию по указанному пути.

При возникновении ошибок доступа осуществляет повторные попытки с задержкой. В случае окончательной блокировки обрабатывает ошибку в соответствии с параметром on_locked.

Parameters:

Name	Type	Description	Default
path	str | Path	Путь к удаляемому объекту.	required
retries	int	Количество повторных попыток.	3
delay	float	Задержка между попытками в секундах.	0.1
on_locked	Literal['raise', 'rename_orphan', 'warn']	Поведение при блокировке ("raise", "rename_orphan", "warn").	'warn'
orphan_collision	Literal['raise', 'overwrite', 'unique']	Поведение при коллизиях orphan-файлов ("raise", "overwrite", "unique").	'raise'

Returns:

Type	Description
bool	True, если объект успешно удален или переименован,
bool	False, если удаление не удалось и on_locked == "warn".

Raises:

Type	Description
OSError	Если удаление не удалось и on_locked == "raise".
FileExistsError	Если orphan-файл существует и orphan_collision == "raise".

resolve_safe_path(path, base_dir=None)

Безопасно разрешает путь относительно базовой директории. Проверяет попытки выхода за пределы базовой директории (Path Traversal).

Parameters:

Name	Type	Description	Default
path	str | Path	Путь для разрешения.	required
base_dir	str | Path | None	Базовая директория. Если не указана, используется корень проекта из конфига.	None

Returns:

Type	Description
Path	Разрешенный абсолютный путь (pathlib.Path).

Raises:

Type	Description
PathTraversalError	Если обнаружена попытка выхода за пределы base_dir.

safe_filename(name, replacement='_', strip_chars=' _.-', max_length=255, transliterate=False)

Очищает строку, делая её безопасной для использования в качестве имени файла.

Оставляет только буквы, цифры, дефисы, точки и подчеркивания. Ограничивает длину и поддерживает транслитерацию кириллицы.

Parameters:

Name	Type	Description	Default
name	str	Исходное имя.	required
replacement	str	Символ замены недопустимых символов.	'_'
strip_chars	str	Символы, удаляемые с краев строки.	' _.-'
max_length	int	Максимальная длина результирующей строки.	255
transliterate	bool	Флаг транслитерации кириллицы в латиницу.	False

Returns:

Type	Description
str	Безопасное имя файла.

Raises:

Type	Description
ValueError	Если имя пустое или после очистки получается пустая строка.

zip_folder(folder_path, output_path, compression=zipfile.ZIP_DEFLATED, exclude=None)

Архивирует содержимое папки в ZIP-архив с сохранением структуры.

Parameters:

Name	Type	Description	Default
folder_path	str | Path	Путь к архивируемой папке.	required
output_path	str | Path	Путь к создаваемому ZIP-файлу.	required
compression	int	Метод сжатия (по умолчанию ZIP_DEFLATED).	ZIP_DEFLATED
exclude	list[str] | None	Список glob-шаблонов для исключения файлов/папок.	None

Returns:

Type	Description
Path	Путь к созданному ZIP-архиву.

Raises:

Type	Description
FileNotFoundError	Если папка folder_path не существует.
ValueError	Если folder_path не является директорией.

options: members:

• ensure_dir
• atomic_write
• get_temp_file

Модуль crypto (Шифрование данных и файлов)

chutils.crypto

Модуль для портативного детерминированного шифрования данных.

Предоставляет функции для шифрования строк и файлов с использованием детерминированного ключа, сгенерированного на основе seed-пароля (алгоритм Fernet).

decrypt_file(file_path, seed, output_path=None, raise_on_error=False, stream=None, progress_callback=None)

Дешифрует содержимое файла и сохраняет результат.

Parameters:

Name	Type	Description	Default
file_path	str | Path	Путь к зашифрованному файлу.	required
seed	str	Строка-пароль для генерации ключа.	required
output_path	str | Path | None	Путь для сохранения результата. Если не указан, файл перезаписывается.	None
raise_on_error	bool	Если True, выбрасывает ValueError при ошибке дешифрования (неверный ключ или поврежденный файл).	False
stream	bool | None	Если True или None, автоопределяет и расшифровывает потоковый файл.	None
progress_callback	Callable[[int, int], None] | None	Необязательная функция обратной связи (callback(processed, total)) для отслеживания прогресса (например, для прогресс-бара).	None

Returns:

Type	Description
bool	True, если дешифрование прошло успешно, иначе False.

Raises:

Type	Description
OptionalDependencyError	Если библиотека cryptography не установлена.
ValueError	Если raise_on_error равен True и произошла ошибка дешифрования.

decrypt_portable(encrypted_data, seed, raise_on_error=False)

Дешифрует строку с использованием детерминированного ключа, полученного из seed.

Parameters:

Name	Type	Description	Default
encrypted_data	str	Зашифрованная строка в формате Base64.	required
seed	str	Строка-пароль для генерации ключа.	required
raise_on_error	bool	Если True, выбрасывает ValueError при ошибке дешифрования (неверный ключ или поврежденный токен).	False

Returns:

Type	Description
str | None	Расшифрованная строка или None, если дешифрование завершилось ошибкой.

Raises:

Type	Description
OptionalDependencyError	Если библиотека cryptography не установлена.
ValueError	Если raise_on_error равен True и произошла ошибка дешифрования.

encrypt_file(file_path, seed, output_path=None, stream=False, chunk_size=DEFAULT_CHUNK_SIZE, progress_callback=None)

Шифрует содержимое файла и сохраняет результат.

Parameters:

Name	Type	Description	Default
file_path	str | Path	Путь к исходному файлу.	required
seed	str	Строка-пароль для генерации ключа.	required
output_path	str | Path | None	Путь для сохранения результата. Если не указан, исходный файл перезаписывается.	None
stream	bool	Если True, использовать потоковое чанковое шифрование (AES-GCM) с фиксированным потреблением памяти (для гигантских файлов).	False
chunk_size	int	Размер чанка в байтах при потоковом шифровании (по умолчанию 64 МБ).	DEFAULT_CHUNK_SIZE
progress_callback	Callable[[int, int], None] | None	Необязательная функция обратной связи (callback(processed, total)) для отслеживания прогресса (например, для прогресс-бара).	None

Returns:

Type	Description
Path	Путь к зашифрованному файлу.

Raises:

Type	Description
OptionalDependencyError	Если библиотека cryptography не установлена.

encrypt_portable(data, seed)

Шифрует строку с использованием детерминированного ключа, полученного из seed.

Parameters:

Name	Type	Description	Default
data	str	Исходная строка для шифрования.	required
seed	str	Строка-пароль для генерации ключа.	required

Returns:

Type	Description
str	Зашифрованная строка в формате Base64.

Raises:

Type	Description
OptionalDependencyError	Если библиотека cryptography не установлена.

options: members:

• encrypt_portable
• decrypt_portable
• encrypt_file
• decrypt_file

Модуль telegram (Интеграция и контроль доступа Telegram-ботов)

chutils.telegram

AccessListManager

Менеджер белых и черных списков пользователей Telegram.

__init__(storage_path=None, allowed_ids=None, allowed_usernames=None, blocked_ids=None, blocked_usernames=None)

Инициализирует AccessListManager.

Parameters:

Name	Type	Description	Default
storage_path	str | Path | None	Опциональный путь к JSON-файлу для автосохранения списков.	None
allowed_ids	list[int] | None	Начальный белый список Telegram ID.	None
allowed_usernames	list[str] | None	Начальный белый список юзернеймов.	None
blocked_ids	list[int] | None	Начальный черный список Telegram ID.	None
blocked_usernames	list[str] | None	Начальный черный список юзернеймов.	None

allow_user(user_id_or_username)

Добавляет пользователя в белый список и убирает из черного.

Parameters:

Name	Type	Description	Default
user_id_or_username	int | str	ID пользователя Telegram или его юзернейм.	required

block_user(user_id_or_username)

Добавляет пользователя в черный список и убирает из белого.

Parameters:

Name	Type	Description	Default
user_id_or_username	int | str	ID пользователя Telegram или его юзернейм.	required

is_user_allowed(user_id=None, username=None)

Проверяет разрешения для пользователя.

Parameters:

Name	Type	Description	Default
user_id	int | None	Telegram ID пользователя.	None
username	str | None	Username пользователя.	None

Returns:

Type	Description
bool	True, если пользователь имеет доступ, иначе False.

load()

Загружает списки из JSON-файла.

remove_user(user_id_or_username)

Удаляет пользователя из белого и черного списков.

Parameters:

Name	Type	Description	Default
user_id_or_username	int | str	ID пользователя Telegram или его юзернейм.	required

save()

Атомарно сохраняет списки в JSON-файл.

AdminFilter

Bases: BaseFilter

Фильтр проверки прав администратора для aiogram 3.x.

Пример использования

@router.message(AdminFilter(admin_ids=[12345678])) async def admin_cmd(message: Message): await message.answer("Привет, админ!")

__call__(event, **kwargs) async

Проверяет, отправлено ли событие (Message/CallbackQuery) администратором.

Parameters:

Name	Type	Description	Default
event	Any	Объект Telegram Update / Message / CallbackQuery из aiogram.	required
**kwargs	Any	Дополнительные контекстные данные.	{}

Returns:

Type	Description
bool	True, если пользователь является администратором.

HealthCheckAlertBridge

Мост отправки Telegram-уведомлений при изменении статусов здоровья chutils.diagnostics.

on_health_check(service_name, status, details=None)

Обрабатывает событие проверки здоровья и отправляет алерт при проблемах.

Parameters:

Name	Type	Description	Default
service_name	str	Имя сервиса/компонента.	required
status	str	Статус (HEALTHY, DEGRADED, UNHEALTHY).	required
details	dict[str, Any] | None	Подробности ошибки или метрики.	None

Returns:

Type	Description
bool	True, если алерт был отправлен, иначе False.

PaginatorKeyboard

Управляющий класс пагинации динамических Inline-клавиатур.

total_pages property

Возвращает общее количество страниц.

__init__(items, per_page=5, callback_prefix='page')

Инициализирует PaginatorKeyboard.

Parameters:

Name	Type	Description	Default
items	Sequence[Any]	Полный список элементов.	required
per_page	int	Количество элементов на странице (по умолчанию 5).	5
callback_prefix	str	Префикс callback_data для навигации.	'page'

build_keyboard(page=1, item_button_factory=None, footer_buttons=None, buttons_per_row=1, as_aiogram=False)

Строит готовую клавиатуру со срезом элементов и пагинационной панелью.

Parameters:

Name	Type	Description	Default
page	int	Номер запрашиваемой страницы.	1
item_button_factory	Any	Опциональная функция приведения элемента к ButtonSpec.	None
footer_buttons	Sequence[ButtonSpec] | None	Дополнительные кнопки под панелью пагинации.	None
buttons_per_row	int	Ряды элементов страницы.	1
as_aiogram	bool	Возвращать ли aiogram InlineKeyboardMarkup.	False

Returns:

Type	Description
Any	Готовая клавиатура.

get_page_items(page=1)

Возвращает срез элементов для указанной страницы (1-indexed).

Parameters:

Name	Type	Description	Default
page	int	Номер страницы (1..total_pages).	1

Returns:

Type	Description
list[Any]	Список элементов текущей страницы.

SecretUserFilter

Bases: BaseFilter

Фильтр белых и черных списков пользователей для aiogram 3.x.

__call__(event, **kwargs) async

Проверяет разрешения пользователя на основе списков.

Parameters:

Name	Type	Description	Default
event	Any	Входящее событие Telegram (Message, CallbackQuery).	required
**kwargs	Any	Контекстные данные.	{}

Returns:

Type	Description
bool	True, если доступ разрешен.

TelegramLogHandler

Bases: Handler

Handler стандартного модуля logging для отправки критических логов в Telegram.

add_flapping_filter(patterns, threshold=3, failure_timeout=60.0)

Добавляет фильтр подавления кратковременных транзиентных ошибок (флаппинга).

Сообщения об ошибках, совпадающие с patterns, будут отсекаться до тех пор, пока количество последовательных сбоев не достигнет threshold или время сбоя не превысит failure_timeout.

Parameters:

Name	Type	Description	Default
patterns	str | Pattern[str] | Sequence[str | Pattern[str]]	Шаблоны ошибок (подстрока, регулярное выражение или список таковых).	required
threshold	int	Порог последовательных ошибок до отправки алерта в Telegram.	3
failure_timeout	float	Таймаут сбоя в секундах до отправки алерта.	60.0

Returns:

Type	Description
TelegramLogHandler	Текущий экземпляр обработчика.

emit(record)

Отправляет отформатированную запись лога в Telegram.

Parameters:

Name	Type	Description	Default
record	LogRecord	Запись лога logging.LogRecord.	required

TelegramLoggingMiddleware

Bases: BaseMiddleware

Middleware контекстного логирования и измерений времени выполнения для aiogram 3.x.

__call__(handler, event, data) async

Обрабатывает события и логирует контекст в цепочке Middleware.

Parameters:

Name	Type	Description	Default
handler	Callable[[Any, dict[str, Any]], Any]	Следующий хэндлер в цепочке.	required
event	Any	Входящее событие Telegram.	required
data	dict[str, Any]	Контекстные данные события.	required

Returns:

Type	Description
Any	Результат выполнения хэндлера.

TelegramRateLimiter

Движок ограничений вызовов (Rate Limiter) для Telegram-ботов.

__init__(rate=1, per=1.0)

Инициализирует TelegramRateLimiter.

Parameters:

Name	Type	Description	Default
rate	int	Максимальное количество допустимых вызовов.	1
per	float	Период времени в секундах.	1.0

check_rate_limit(key)

Проверяет превышение лимита вызовов для ключа.

Parameters:

Name	Type	Description	Default
key	str	Уникальный идентификатор сущности (user_id / chat_id).	required

Returns:

Type	Description
tuple[bool, float]	Кортеж (is_limited, wait_sec), где is_limited - флаг превышения, wait_sec - секунд до разблокировки.

TelegramThrottlingMiddleware

Bases: BaseMiddleware

Middleware отслеживания и предотвращения спама (Throttling) для aiogram 3.x.

__call__(handler, event, data) async

Обрабатывает входящее событие в цепочке Middleware.

Parameters:

Name	Type	Description	Default
handler	Callable[[Any, dict[str, Any]], Any]	Следующий хэндлер в цепочке.	required
event	Any	Входящее событие Telegram.	required
data	dict[str, Any]	Контекстные данные события.	required

Returns:

Type	Description
Any	Результат выполнения хэндлера.

trace_telegram_update

Контекстный менеджер и декоратор трейсинга и логирования Telegram-апдейтов.

__call__(func)

Оборачивает функцию декоратором трейсинга.

Parameters:

Name	Type	Description	Default
func	F	Целевая функция.	required

Returns:

Type	Description
F	Обернутая функция.

__init__(event=None, logger_instance=None)

Инициализирует trace_telegram_update.

Parameters:

Name	Type	Description	Default
event	Any	Входящее событие/апдейт Telegram.	None
logger_instance	Any	Опциональный кастомный логгер.	None

admin_only(admin_ids=None, admin_usernames=None, is_admin_func=None, refusal_text='⛔ Доступ запрещен: требуется статус администратора', silent=False, raise_on_denied=False)

Декоратор для ограничения доступа к синхронным и асинхронным хэндлерам Telegram-ботов.

Parameters:

Name	Type	Description	Default
admin_ids	list[int] | None	Разрешенные Telegram ID.	None
admin_usernames	list[str] | None	Разрешенные юзернеймы.	None
is_admin_func	Callable[[int | None, str | None], bool] | None	Кастомный предикат проверки.	None
refusal_text	str | None	Текст сообщения при отказе в доступе.	'⛔ Доступ запрещен: требуется статус администратора'
silent	bool	Если True, тихо игнорировать неавторизованные запросы.	False
raise_on_denied	bool	Если True, выбрасывать TelegramAccessDeniedError.	False

Returns:

Type	Description
Callable[[F], F]	Обернутый хэндлер.

allowed_only(manager=None, allowed_ids=None, allowed_usernames=None, blocked_ids=None, blocked_usernames=None, refusal_text='⛔ У вас нет доступа к этой функции', silent=False, raise_on_denied=False)

Декоратор ограничения доступа по белым и черным спискам.

Parameters:

Name	Type	Description	Default
manager	AccessListManager | None	Готовый экземпляр AccessListManager.	None
allowed_ids	list[int] | None	Белый список Telegram ID.	None
allowed_usernames	list[str] | None	Белый список юзернеймов.	None
blocked_ids	list[int] | None	Черный список Telegram ID.	None
blocked_usernames	list[str] | None	Черный список юзернеймов.	None
refusal_text	str | None	Сообщение об отказе.	'⛔ У вас нет доступа к этой функции'
silent	bool	Если True, отбрасывать запросы без вывода ответа.	False
raise_on_denied	bool	Если True, выбрасывать TelegramAccessDeniedError.	False

Returns:

Type	Description
Callable[[F], F]	Обернутая функция.

build_inline_keyboard(buttons, buttons_per_row=2, as_aiogram=False)

Создает сетку Inline-клавиатуры Telegram из списка кнопок.

Parameters:

Name	Type	Description	Default
buttons	Sequence[ButtonSpec]	Список спецификаций кнопок (кортежи или словари).	required
buttons_per_row	int	Количество кнопок в одном ряду (по умолчанию 2).	2
as_aiogram	bool	Если True, возвращает aiogram InlineKeyboardMarkup (при наличии aiogram).	False

Returns:

Type	Description
Any	Словарь вида {'inline_keyboard': [...]} или aiogram InlineKeyboardMarkup.

download_user_file(bot, file_id, target_dir, custom_filename=None, allow_unsafe_path=False, max_size_bytes=None) async

Безопасно выкачивает файл из Telegram по file_id в указанную директорию target_dir.

Parameters:

Name	Type	Description	Default
bot	Any	Экземпляр бота (aiogram.Bot или аналогичный с методом get_file/download_file) или bot_token (str).	required
file_id	str	Уникальный идентификатор файла в Telegram API.	required
target_dir	str | Path	Целевая папка для сохранения.	required
custom_filename	str | None	Желаемое имя файла. Если не указано, используется имя из Telegram или file_id.	None
allow_unsafe_path	bool	Если True, отключает строгую проверку Path Traversal (записывается предупреждение).	False
max_size_bytes	int | None	Максимальный допустимый размер файла в байтах.	None

Returns:

Type	Description
Path	Абсолютный путь (Path) к сохраненному файлу.

Raises:

Type	Description
PathTraversalError	При попытке выхода за границы target_dir (когда allow_unsafe_path=False).
ChutilsException	При превышении max_size_bytes или ошибке загрузки.

escape_html(text)

Экранирует специальные символы в тексте для парс-режима HTML в Telegram.

Parameters:

Name	Type	Description	Default
text	str	Исходный текст.	required

Returns:

Type	Description
str	Экранированный HTML текст.

escape_markdown(text, version=2)

Экранирует специальные символы в тексте для парс-режима Markdown в Telegram.

Parameters:

Name	Type	Description	Default
text	str	Исходный текст.	required
version	int	Версия синтаксиса Markdown (1 или 2, по умолчанию: 2).	2

Returns:

Type	Description
str	Экранированный текст.

is_admin(user_id=None, username=None, admin_ids=None, admin_usernames=None, is_admin_func=None)

Проверяет, является ли пользователь администратором.

Если явные списки admin_ids / admin_usernames не заданы, считывает их из конфигурации chutils (секция 'Telegram', ключи 'admin_ids' / 'admin_usernames').

Parameters:

Name	Type	Description	Default
user_id	int | None	Telegram ID пользователя.	None
username	str | None	Telegram username пользователя.	None
admin_ids	list[int] | None	Список разрешенных Telegram ID администраторов.	None
admin_usernames	list[str] | None	Список разрешенных username администраторов.	None
is_admin_func	Callable[[int | None, str | None], bool] | None	Кастомный предикат проверки.	None

Returns:

Type	Description
bool	True, если пользователь является администратором, иначе False.

send_alert(title, message, bot_token=None, chat_id=None, level='ERROR')

Отправляет кастомное алерты-уведомление администраторам в Telegram.

Parameters:

Name	Type	Description	Default
title	str	Заголовок алерта.	required
message	str	Текст сообщения.	required
bot_token	str | None	Опциональный токен бота.	None
chat_id	int | str | None	Опциональный ID чата администратора.	None
level	str	Уровень алерта (INFO, WARNING, ERROR, CRITICAL).	'ERROR'

Returns:

Type	Description
bool	True при успешной отправке, иначе False.

send_telegram_file(bot, chat_id, file_path, caption=None, parse_mode=None, allow_unsafe_path=False, base_dir=None) async

Безопасно отправляет файл или папку (с авто-упаковкой в ZIP) в Telegram.

Parameters:

Name	Type	Description	Default
bot	Any	Экземпляр бота (aiogram.Bot) или raw bot_token (str).	required
chat_id	int | str	Идентификатор чата или получателя.	required
file_path	str | Path	Путь к отправляемому файлу или директории.	required
caption	str | None	Опциональная подпись к файлу (автоматически обрезается под 1024 символа).	None
parse_mode	str | None	Режим разметки подписи ('HTML', 'MarkdownV2', etc.).	None
allow_unsafe_path	bool	Если True, отключает проверку Path Traversal.	False
base_dir	str | Path | None	Базовая директория для проверки выхода за границы.	None

Returns:

Type	Description
Any	Объект отправленного сообщения Telegram API.

Raises:

Type	Description
PathTraversalError	Если файл находится за пределами base_dir.
ChutilsException	При превышении лимита 50 МБ или ошибках отправки.

smart_truncate(text, max_length=4096, suffix='...')

Безопасно обрезает текст до max_length с закрытием кодовых блоков (```).

Parameters:

Name	Type	Description	Default
text	str	Исходный текст сообщения.	required
max_length	int	Максимальная допустимая длина (по умолчанию 4096).	4096
suffix	str	Суффикс для обрезанного сообщения.	'...'

Returns:

Type	Description
str	Обрезанный валидный текст.

split_message(text, max_length=4096, mode='line')

Разбивает длинный текст на список валидных сообщений не превышающих max_length.

Parameters:

Name	Type	Description	Default
text	str	Исходный длинный текст.	required
max_length	int	Максимальный размер одного сообщения (по умолчанию: 4096).	4096
mode	Literal['paragraph', 'line', 'word', 'char']	Стратегия разбиения: - 'paragraph': сплит по абзацам (\n\n) - 'line': сплит по строкам (\n, по умолчанию) - 'word': сплит по словам (пробелам) - 'char': жесткий сплит посимвольно	'line'

Returns:

Type	Description
list[str]	Список чанков текста.

tg_rate_limit(rate=1, per=1.0, scope='user_id', warning_text='⏱ Пожалуйста, подождите {wait_sec} сек. перед повторной отправкой.', silent=False, raise_on_limit=False)

Декоратор ограничения частоты запросов для Telegram-ботов.

Parameters:

Name	Type	Description	Default
rate	int	Количество разрешенных запросов.	1
per	float	Временное окно в секундах.	1.0
scope	str	Область ограничения: 'user_id', 'chat_id' или 'user_and_chat'.	'user_id'
warning_text	str | None	Шаблон предупреждения. Поддерживает форматирование {wait_sec}.	'⏱ Пожалуйста, подождите {wait_sec} сек. перед повторной отправкой.'
silent	bool	Если True, отбрасывать запросы без вывода предупреждения.	False
raise_on_limit	bool	Если True, выбрасывать RateLimitExceededError при флуде.	False

Returns:

Type	Description
Callable[[F], F]	Обернутая функция-хэндлер.

options: members:

• is_admin
• admin_only
• AdminFilter
• SecretUserFilter
• TelegramRateLimiter
• tg_rate_limit
• TelegramThrottlingMiddleware
• TelegramLoggingMiddleware
• AccessListManager
• allowed_only
• trace_telegram_update
• escape_markdown
• escape_html
• smart_truncate
• split_message
• TelegramLogHandler
• HealthCheckAlertBridge
• send_alert
• build_inline_keyboard
• PaginatorKeyboard

Декораторы

chutils.decorators

Модуль с полезными декораторами для автоматизации задач.

Включает инструменты для логирования производительности и деталей вызовов функций.

CircuitBreakerState

Машина состояний для паттерна Circuit Breaker (Предохранитель).

__init__(failure_threshold, recovery_timeout, exceptions, name)

Инициализирует состояние предохранителя (Circuit Breaker).

Parameters:

Name	Type	Description	Default
failure_threshold	int	Порог неудачных попыток для открытия цепи.	required
recovery_timeout	float	Таймаут восстановления в секундах.	required
exceptions	tuple[type[Exception], ...]	Исключения, расцениваемые как ошибки.	required
name	str	Имя предохранителя (обычно имя декорируемой функции).	required

can_execute()

Проверяет возможность выполнения операции в текущем состоянии цепи.

Returns:

Type	Description
bool	True, если выполнение разрешено, иначе False.

record_failure(exc)

Записывает неудачную попытку выполнения.

Parameters:

Name	Type	Description	Default
exc	Exception	Возникшее исключение.	required

record_success()

Записывает успешное выполнение и сбрасывает состояние сбоев в CLOSED.

LeakyBucket

Алгоритм дырявого ведра (Leaky Bucket).

__init__(capacity, period)

Инициализирует дырявое ведро.

Parameters:

Name	Type	Description	Default
capacity	int	Максимальная вместимость ведра (максимальный уровень воды).	required
period	float	Временной интервал в секундах, за который ведро полностью опустошается.	required

acquire(wait=False)

Запрашивает добавление единицы воды в ведро.

Parameters:

Name	Type	Description	Default
wait	bool	Флаг необходимости блокирующего ожидания до тех пор, пока уровень воды не спадет.	False

Returns:

Type	Description
float | None	Время ожидания в секундах, если необходимо подождать, 0.0 если вода добавлена сразу,
float | None	или None, если ведро переполнено и wait=False.

TokenBucket

Алгоритм маркерной корзины (Token Bucket).

__init__(capacity, period)

Инициализирует маркерную корзину.

Parameters:

Name	Type	Description	Default
capacity	int	Максимальная вместимость корзины (количество токенов).	required
period	float	Временной интервал в секундах, за который корзина полностью пополняется.	required

acquire(wait=False)

Запрашивает получение токена из корзины.

Parameters:

Name	Type	Description	Default
wait	bool	Флаг необходимости блокирующего ожидания, если токенов нет.	False

Returns:

Type	Description
float | None	Время ожидания в секундах, если необходимо подождать, 0.0 если токен получен сразу,
float | None	или None, если токенов нет и wait=False.

bulkhead(max_concurrent, max_waiting=0, timeout=None, fallback=_NO_FALLBACK, key=None)

Декоратор для изоляции ресурсов (Bulkhead).

Ограничивает максимальное количество параллельных запросов и размер очереди ожидания. Поддерживает таймауты и fallback.

Parameters:

Name	Type	Description	Default
max_concurrent	int	Максимальное количество параллельно выполняющихся запросов.	required
max_waiting	int	Максимальное количество запросов в очереди ожидания.	0
timeout	float | None	Таймаут ожидания свободного слота в секундах.	None
fallback	Any	Значение или callable для возврата при отклонении.	_NO_FALLBACK
key	Callable[..., Any] | None	Опциональная функция вычисления динамического ключа группировки.	None

Returns:

Type	Description
Callable[[Callable[P, R]], Callable[P, R]]	Декорированная функция.

circuit_breaker(failure_threshold=5, recovery_timeout=60.0, exceptions=(Exception,))

Декоратор Circuit Breaker (Предохранитель) для защиты от каскадных сбоев.

Parameters:

Name	Type	Description	Default
failure_threshold	int	Количество последовательных ошибок для открытия цепи.	5
recovery_timeout	float	Время в секундах, в течение которого цепь остается открытой.	60.0
exceptions	tuple[type[Exception], ...]	Кортеж исключений, которые считаются ошибками.	(Exception,)

Returns:

Type	Description
Callable[[Callable[P, R]], Callable[P, R]]	Декоратор, оборачивающий функцию механизмом автоматического отключения при сбоях.

clear_limiters()

Очищает реестр ограничителей (для тестов).

get_limiter(key, max_calls, period, strategy='token_bucket')

Возвращает или создает ограничитель частоты по ключу.

Parameters:

Name	Type	Description	Default
key	str	Уникальный ключ для идентификации ограничителя.	required
max_calls	int	Максимальное число вызовов за период.	required
period	float	Временной интервал в секундах.	required
strategy	str	Стратегия ограничения частоты ("token_bucket" или "leaky_bucket").	'token_bucket'

Returns:

Type	Description
TokenBucket | LeakyBucket	Экземпляр ограничителя частоты (TokenBucket или LeakyBucket).

log_function_details(func)

Декоратор для логирования деталей вызова функции.

Записывает аргументы, время выполнения и возвращаемое значение на уровне DEVDEBUG.

Parameters:

Name	Type	Description	Default
func	Callable[P, R]	Декорируемая функция.	required

Returns:

Type	Description
Callable[P, R]	Обертка функции с логированием.

Example

@log_function_details
def add(a, b):
    return a + b

add(2, 3)

rate_limit(max_calls, period, strategy='token_bucket', wait=False, key_func=None)

Декоратор для ограничения частоты вызовов функции (Throttling).

Parameters:

Name	Type	Description	Default
max_calls	int	Максимальное количество вызовов в период.	required
period	float	Период времени в секундах.	required
strategy	str	Стратегия лимитирования ("token_bucket" или "leaky_bucket").	'token_bucket'
wait	bool	Если True, блокирует выполнение до появления токена. Если False, сразу выбрасывает RateLimitExceededError при превышении лимита.	False
key_func	Callable[..., str] | None	Кастомная функция для генерации ключа лимитирования на основе аргументов.	None

Returns:

Type	Description
Callable[[Callable[P, R]], Callable[P, R]]	Декоратор функции.

retry(retries=3, delay=1.0, backoff=2.0, jitter=False, exceptions=(Exception,))

Декоратор для автоматического повторного выполнения функции при возникновении исключений.

Parameters:

Name	Type	Description	Default
retries	int	Количество попыток повтора (не считая первый запуск).	3
delay	float	Базовая задержка между попытками в секундах.	1.0
backoff	float	Множитель задержки для каждой следующей попытки.	2.0
jitter	bool	Добавлять ли случайный шум к задержке.	False
exceptions	tuple[type[Exception], ...]	Кортеж исключений, при которых требуется повтор.	(Exception,)

Returns:

Type	Description
Callable[[Callable[P, R]], Callable[P, R]]	Декоратор функции.

semaphore(max_concurrent, key=None)

Декоратор для ограничения максимального количества параллельных вызовов функции (Semaphore).

Поддерживает как синхронные, так и асинхронные функции. Позволяет группировать ограничения динамически по ключу с помощью параметра key.

Parameters:

Name	Type	Description	Default
max_concurrent	int	Максимальное количество параллельных вызовов.	required
key	Callable[..., Any] | None	Опциональная функция для вычисления динамического ключа группировки на основе аргументов функции.	None

Returns:

Type	Description
Callable[[Callable[P, R]], Callable[P, R]]	Декорированная функция.

timeout(seconds, fallback=_NO_FALLBACK)

Декоратор для ограничения времени выполнения функции.

Поддерживает как синхронные, так и асинхронные функции. Для асинхронных функций использует asyncio.wait_for. Для синхронных функций запускает их в отдельном потоке и ожидает завершения.

Parameters:

Name	Type	Description	Default
seconds	float	Максимальное время выполнения в секундах.	required
fallback	Any	Значение, которое будет возвращено при таймауте. Если не указано, выбрасывается ChutilsTimeoutError.	_NO_FALLBACK

Returns:

Type	Description
Callable[[Callable[P, R]], Callable[P, R]]	Декоратор функции.

Raises:

Type	Description
ChutilsTimeoutError	Если время выполнения превышено и fallback не указан.

options: members:

• retry
• log_function_details
• timeout
• rate_limit
• circuit_breaker

Модуль events (Шина событий)

chutils.events

Модуль шины событий (In-Memory Event Bus).

Предоставляет возможности подписки на события и публикации событий как в синхронном, так и в асинхронном режимах.

ErrorStrategy

Bases: str, Enum

Стратегия обработки ошибок при выполнении обработчиков событий.

EventBus

Внутренняя шина событий (In-Memory Event Bus).

Обеспечивает регистрацию подписчиков и публикацию событий. Потокобезопасна.

__init__(error_strategy=ErrorStrategy.IGNORE)

Инициализирует шину событий.

Parameters:

Name	Type	Description	Default
error_strategy	ErrorStrategy	Стратегия обработки ошибок по умолчанию.	IGNORE

clear()

Очищает всех подписчиков шины событий.

publish(event_name, *args, error_strategy=None, **kwargs)

Синхронно публикует событие.

Синхронные обработчики выполняются немедленно в текущем потоке. Асинхронные обработчики запускаются в фоновом режиме в выделенном Event Loop.

Parameters:

Name	Type	Description	Default
event_name	str	Имя события.	required
*args	Any	Позиционные аргументы для обработчиков.	()
error_strategy	ErrorStrategy | None	Стратегия обработки ошибок для этого вызова.	None
**kwargs	Any	Именованные аргументы для обработчиков.	{}

publish_async(event_name, *args, error_strategy=None, **kwargs) async

Асинхронно публикует событие.

Дожидается выполнения всех подписчиков (как синхронных, так и асинхронных). Синхронные обработчики выполняются в пуле потоков через asyncio.to_thread.

Parameters:

Name	Type	Description	Default
event_name	str	Имя события.	required
*args	Any	Позиционные аргументы для обработчиков.	()
error_strategy	ErrorStrategy | None	Стратегия обработки ошибок для этого вызова.	None
**kwargs	Any	Именованные аргументы для обработчиков.	{}

subscribe(event_name)

Декоратор для регистрации обработчика события на данном инстансе шины.

Parameters:

Name	Type	Description	Default
event_name	str	Имя события, на которое подписывается обработчик.	required

Returns:

Type	Description
Callable[[Callable[..., Any]], Callable[..., Any]]	Декоратор, который регистрирует функцию-обработчик и возвращает её.

unsubscribe(event_name, func)

Отменяет подписку обработчика на событие.

Parameters:

Name	Type	Description	Default
event_name	str	Имя события.	required
func	Callable[..., Any]	Функция-обработчик, которую нужно отписать.	required

clear_event_bus()

Очищает всех подписчиков глобальной шины событий.

publish(event_name, *args, error_strategy=None, **kwargs)

Синхронно публикует событие в глобальной шине.

Parameters:

Name	Type	Description	Default
event_name	str	Имя события.	required
*args	Any	Позиционные аргументы.	()
error_strategy	ErrorStrategy | None	Стратегия обработки ошибок.	None
**kwargs	Any	Именованные аргументы.	{}

publish_async(event_name, *args, error_strategy=None, **kwargs) async

Асинхронно публикует событие в глобальной шине.

Parameters:

Name	Type	Description	Default
event_name	str	Имя события.	required
*args	Any	Позиционные аргументы.	()
error_strategy	ErrorStrategy | None	Стратегия обработки ошибок.	None
**kwargs	Any	Именованные аргументы.	{}

subscribe(event_name)

Декоратор для подписки на событие в глобальной шине.

Parameters:

Name	Type	Description	Default
event_name	str	Имя события.	required

Returns:

Type	Description
Callable[[Callable[..., Any]], Callable[..., Any]]	Декоратор для функции-обработчика.

options: members:

• EventBus
• ErrorStrategy
• subscribe
• publish
• publish_async

Модуль tasks (Планировщик фоновых задач)

chutils.tasks

Модуль планировщика фоновых задач.

options: members:

• periodic_task
• start_scheduler
• stop_scheduler
• ErrorStrategy

Модуль di (Внедрение зависимостей)

chutils.di

options: members:

• Container
• provide
• inject
• Inject

Модуль metrics (Абстракция для метрик)

chutils.metrics

PROMETHEUS_AVAILABLE = importlib.util.find_spec('prometheus_client') is not None module-attribute

Глобальный флаг доступности prometheus_client

InMemoryMetricsProvider

Bases: MetricsProvider

Потокобезопасный in-memory провайдер метрик.

Не требует внешних зависимостей. Форматирует экспорт в стандартный текстовый формат Prometheus для бесшовной интеграции.

__init__()

Инициализирует InMemoryMetricsProvider.

clear()

Очищает все накопленные данные метрик.

generate_latest()

Экспортировать накопленные метрики в текстовом формате.

Returns:

Type	Description
str	Строка с отформатированными метриками.

get_metrics()

Возвращает сырые накопленные метрики в виде словаря (для отладки и тестов).

Returns:

Type	Description
dict[str, Any]	Словарь с сырыми данными по счетчикам, датчикам и гистограммам.

increment(name, value=1.0, labels=None)

Увеличить счетчик (Counter) на заданное значение.

Parameters:

Name	Type	Description	Default
name	str	Имя метрики.	required
value	float	Добавляемое значение.	1.0
labels	dict[str, str] | None	Словарь меток.	None

observe(name, value, labels=None)

Записать значение в гистограмму/таймер (Histogram/Timer).

Parameters:

Name	Type	Description	Default
name	str	Имя метрики.	required
value	float	Записываемое значение.	required
labels	dict[str, str] | None	Словарь меток.	None

set_gauge(name, value, labels=None)

Установить значение датчика (Gauge).

Parameters:

Name	Type	Description	Default
name	str	Имя датчика.	required
value	float	Устанавливаемое значение.	required
labels	dict[str, str] | None	Словарь меток.	None

MetricsProvider

Bases: ABC

Абстрактный базовый класс (интерфейс) для провайдеров метрик.

clear() abstractmethod

Очистить все накопленные данные (для тестов).

generate_latest() abstractmethod

Экспортировать накопленные метрики в текстовом формате.

Returns:

Type	Description
str	Строка с накопленными метриками.

increment(name, value=1.0, labels=None) abstractmethod

Увеличить счетчик (Counter) на заданное значение.

Parameters:

Name	Type	Description	Default
name	str	Имя метрики.	required
value	float	Значение, на которое нужно увеличить счетчик.	1.0
labels	dict[str, str] | None	Словарь меток для метрики.	None

observe(name, value, labels=None) abstractmethod

Записать значение в гистограмму/таймер (Histogram/Timer).

Parameters:

Name	Type	Description	Default
name	str	Имя метрики гистограммы/таймера.	required
value	float	Наблюдаемое значение.	required
labels	dict[str, str] | None	Словарь меток для метрики.	None

set_gauge(name, value, labels=None) abstractmethod

Установить значение датчика (Gauge).

Parameters:

Name	Type	Description	Default
name	str	Имя датчика.	required
value	float	Устанавливаемое значение датчика.	required
labels	dict[str, str] | None	Словарь меток для метрики.	None

PrometheusMetricsProvider

Bases: MetricsProvider

Провайдер метрик, транслирующий вызовы в prometheus_client.

Использует ленивый импорт. Если библиотека prometheus_client отсутствует, выбрасывает OptionalDependencyError при инициализации.

__init__()

Инициализирует PrometheusMetricsProvider.

clear()

Очистить кэш провайдера (но не глобальный REGISTRY Prometheus).

generate_latest()

Экспортировать накопленные метрики в текстовом формате.

Returns:

Type	Description
str	Строка с отформатированными метриками.

increment(name, value=1.0, labels=None)

Увеличить счетчик (Counter) на заданное значение.

Parameters:

Name	Type	Description	Default
name	str	Имя метрики.	required
value	float	Добавляемое значение.	1.0
labels	dict[str, str] | None	Словарь меток.	None

observe(name, value, labels=None)

Записать значение в гистограмму/таймер (Histogram/Timer).

Parameters:

Name	Type	Description	Default
name	str	Имя метрики.	required
value	float	Записываемое значение.	required
labels	dict[str, str] | None	Словарь меток.	None

set_gauge(name, value, labels=None)

Установить значение датчика (Gauge).

Parameters:

Name	Type	Description	Default
name	str	Имя датчика.	required
value	float	Устанавливаемое значение.	required
labels	dict[str, str] | None	Словарь меток.	None

TimerContext

Контекстный менеджер и декоратор для замера времени выполнения функций и блоков кода.

Пример использования в качестве контекстного менеджера

with timer("db_query_duration_seconds", labels={"op": "select"}): db.execute("SELECT ...")

Пример использования в качестве декоратора

@timer("http_request_duration_seconds", labels={"endpoint": "/users"}) def handle(): ...

__call__(func)

Позволяет использовать TimerContext в качестве декоратора функции.

Parameters:

Name	Type	Description	Default
func	F	Декорируемая функция.	required

Returns:

Type	Description
F	Обернутая функция, замеряющая время своего выполнения.

__init__(name, labels=None)

Инициализирует TimerContext.

Parameters:

Name	Type	Description	Default
name	str	Имя метрики гистограммы для записи замера.	required
labels	dict[str, str] | None	Опциональные метки для метрики.	None

clear()

Очистить данные активного провайдера метрик.

generate_latest()

Сгенерировать дамп последних метрик в текстовом формате.

Returns:

Type	Description
str	Дамп метрик в формате Prometheus или пустая строка при ошибке.

get_provider()

Получить текущий активный провайдер метрик.

Если провайдер не задан вручную, инициализирует PrometheusMetricsProvider (если библиотека доступна) или InMemoryMetricsProvider в качестве fallback.

Returns:

Type	Description
MetricsProvider	Текущий активный экземпляр MetricsProvider.

increment(name, value=1.0, labels=None)

Увеличить счетчик (Counter) на заданное значение.

Parameters:

Name	Type	Description	Default
name	str	Имя метрики.	required
value	float	Значение, на которое нужно увеличить счетчик.	1.0
labels	dict[str, str] | None	Словарь меток для метрики.	None

observe(name, value, labels=None)

Записать значение в гистограмму/таймер (Histogram/Timer).

Parameters:

Name	Type	Description	Default
name	str	Имя метрики гистограммы/таймера.	required
value	float	Наблюдаемое значение.	required
labels	dict[str, str] | None	Словарь меток для метрики.	None

set_gauge(name, value, labels=None)

Установить значение датчика (Gauge).

Parameters:

Name	Type	Description	Default
name	str	Имя датчика.	required
value	float	Устанавливаемое значение датчика.	required
labels	dict[str, str] | None	Словарь меток для метрики.	None

set_provider(provider)

Установить провайдер метрик вручную (например, для тестирования).

Parameters:

Name	Type	Description	Default
provider	MetricsProvider	Экземпляр MetricsProvider для установки.	required

options: members:

• increment
• set_gauge
• observe
• timer
• generate_latest
• get_provider
• set_provider
• clear

Исключения

chutils.exceptions

AuditError

Bases: ChutilsException

Базовый класс ошибок модуля audit.

AuditIntegrityError

Bases: AuditError

Ошибка целостности журнала аудита.

Выбрасывается при обнаружении нарушения криптографической цепочки хэшей.

BulkheadLimitExceeded

Bases: ChutilsException

Ошибка: превышен предел параллельных запросов Bulkhead.

CacheError

Bases: ChutilsException

Общая ошибка кэширования.

ChutilsConfigurationError

Bases: ChutilsException

Ошибка конфигурации компонентов chutils.

ChutilsException

Bases: Exception

Базовый класс для всех исключений библиотеки chutils.

Поддерживает структурированный контекст ошибки через именованные аргументы и опциональную подсказку (hint) для пользователя.

message property

Сообщение об ошибке.

Returns:

Type	Description
str	Текст сообщения об ошибке.

__init__(message, hint=None, **context)

Инициализирует базовое исключение ChutilsException.

Parameters:

Name	Type	Description	Default
message	str	Сообщение об ошибке.	required
hint	str | None	Опциональная подсказка по устранению ошибки.	None
**context	Any	Дополнительный контекст ошибки.	{}

ChutilsTimeoutError

Bases: ChutilsException

Ошибка: превышено время ожидания выполнения операции.

ChutilsValidationError

Bases: ChutilsException

Исключение при ошибке валидации данных.

__init__(message, errors=None, raw_error=None, hint=None, **context)

Инициализирует исключение валидации.

Parameters:

Name	Type	Description	Default
message	str	Сообщение об ошибке.	required
errors	list[dict[str, Any]] | None	Список ошибок в структурированном виде.	None
raw_error	Exception | None	Исходное исключение (например, ValidationError), если доступно.	None
hint	str | None	Опциональная подсказка.	None
**context	Any	Дополнительный контекст.	{}

__rich__()

Рендерит красивую таблицу ошибок валидации для rich.

Returns:

Type	Description
Any	Экземпляр rich.table.Table.

CircuitBreakerOpenError

Bases: ChutilsException

Ошибка: цепь предохранителя открыта (запросы заблокированы).

CommandError

Bases: ChutilsException

Ошибка при выполнении CLI команды.

ConfigError

Bases: ChutilsException

Общая ошибка конфигурации.

ConfigKeyNotFoundError

Bases: ConfigError

Ошибка: ключ или секция конфигурации не найдены.

ConfigLoadError

Bases: ConfigError

Ошибка при загрузке файла конфигурации (отсутствие файла, права доступа).

ConfigParseError

Bases: ConfigError

Ошибка при парсинге содержимого конфигурации (невалидный YAML/JSON/INI).

ConfigValidationGroupError

Bases: _BaseExceptionGroup, ConfigError

Группа ошибок валидации ключей конфигурации (отсутствие обязательных ключей).

__init__(message, exceptions, **context)

Инициализирует группу ошибок валидации конфигурации.

Parameters:

Name	Type	Description	Default
message	str	Сообщение об ошибке.	required
exceptions	list[Exception]	Список исключений ConfigKeyNotFoundError.	required
**context	Any	Дополнительный контекст ошибки.	{}

DependencyError

Bases: ChutilsException

Общая ошибка внедрения зависимостей.

DependencyNotFoundError

Bases: DependencyError

Ошибка: запрашиваемая зависимость не зарегистрирована в контейнере.

DependencyResolutionError

Bases: DependencyError

Ошибка при разрешении графа зависимостей (например, некорректная сигнатура, циклические зависимости).

EnvValidationError

Bases: ChutilsException

Исключение при ошибке валидации переменных окружения.

__init__(message, errors=None, hint=None, **context)

Инициализирует исключение валидации переменных окружения.

Parameters:

Name	Type	Description	Default
message	str	Сообщение об ошибке.	required
errors	list[dict[str, Any]] | None	Список ошибок в структурированном виде.	None
hint	str | None	Опциональная подсказка.	None
**context	Any	Дополнительный контекст.	{}

__rich__()

Рендерит красивую таблицу ошибок для rich.

Returns:

Type	Description
Any	Экземпляр rich.table.Table.

EventBusError

Bases: ChutilsException

Общая ошибка шины событий.

EventBusExceptionGroup

Bases: _BaseExceptionGroup, EventBusError

Группа ошибок, возникших при параллельном или последовательном выполнении обработчиков событий шины.

__init__(message, exceptions, **context)

Инициализирует группу исключений шины событий.

Parameters:

Name	Type	Description	Default
message	str	Сообщение об ошибке.	required
exceptions	list[Exception]	Список перехваченных исключений от обработчиков.	required
**context	Any	Дополнительный контекст ошибки.	{}

FileSystemError

Bases: ChutilsException

Общая ошибка при работе с файловой системой.

HttpClientError

Bases: ChutilsException

Базовая ошибка HTTP-клиента chutils.

LoggerConfigurationError

Bases: ChutilsException

Ошибка конфигурации логгера.

OptionalDependencyError

Bases: ChutilsException

Ошибка: отсутствует опциональная зависимость (например, watchdog).

PathTraversalError

Bases: FileSystemError

Ошибка безопасности: попытка выхода за пределы базовой директории (Path Traversal).

__init__(message, attempted_path='unknown', base_path='unknown', hint='Проверьте правильность пути или права доступа.', **context)

Инициализирует исключение попытки выхода за пределы базовой директории.

Parameters:

Name	Type	Description	Default
message	str	Сообщение об ошибке.	required
attempted_path	str | Path	Недопустимый путь, к которому пытались получить доступ.	'unknown'
base_path	str | Path	Базовый разрешенный путь.	'unknown'
hint	str | None	Опциональная подсказка для пользователя.	'Проверьте правильность пути или права доступа.'
**context	Any	Дополнительный контекст ошибки.	{}

RateLimitExceededError

Bases: ChutilsException

Ошибка: превышен лимит частоты вызовов (Rate Limit Exceeded).

SecretError

Bases: ChutilsException

Общая ошибка менеджера секретов.

SecretNotFoundError

Bases: SecretError

Ошибка: секрет не найден.

SecretProviderError

Bases: SecretError

Ошибка конкретного провайдера секретов (например, сбой keyring).

TelegramAccessDeniedError

Bases: TelegramError

Выбрасывается при отказе в доступе к командам или действиям Telegram-бота.

TelegramError

Bases: ChutilsException

Базовое исключение для подсистемы Telegram.

VKMAValidationError

Bases: ChutilsException

Выбрасывается при ошибке валидации параметров запуска (launchParams) или подписи VKMA.

WatcherInitializationError

Bases: ChutilsException

Ошибка инициализации наблюдателя (watcher) за файлами.

Тестирование

Подробную информацию о pytest-фикстурах для тестирования приложений с chutils см. в разделе Тестирование с chutils.

chutils.testing

capture_chutils_logs()

Фикстура для перехвата логов.

• Перехватывает все логи, проходящие через любой логгер (включая те, где propagate=False).
• Позволяет проверять сообщения и поля контекста (например, добавленные через bind_context).

Example

def test_logging(capture_chutils_logs): from chutils.logger import setup_logger logger = setup_logger("test") logger.info("Hello world") assert capture_chutils_logs.has_message("Hello")

mock_chutils_config(monkeypatch)

Фикстура для мокирования конфигурации chutils.

• Отключает переопределение через переменные окружения (CH_DISABLE_ENV_OVERRIDE=true).
• Сбрасывает состояние глобального ConfigManager до и после теста.
• Возвращает объект с методом .set(section, key, value).

mock_chutils_secrets(monkeypatch)

Фикстура для мокирования секретов chutils.

• Заменяет все провайдеры в SecretManager на один MockSecretProvider.
• Отключает предупреждение о миграции keyring.

Модуль dev (AI-валидация и аудит)

chutils.dev

Инструменты разработчика для анализа кодовой базы и генерации контекста.

AI_MANIFEST_FILENAMES = ['GEMINI.md', 'gemini.md', 'antigravity.md', 'ANTIGRAVITY.md', 'agents.md', 'AGENTS.md', '.cursorrules', '.windsurfrules'] module-attribute

Список поддерживаемых AI-манифестов.

BaseRunner

Bases: ABC

Абстрактный базовый класс ранера для управления перезапуском приложений.

is_running property

Возвращает флаг состояния ранера.

restart()

Выполняет перезапуск (остановка -> запуск).

start() abstractmethod

Запускает процесс или целевую функцию.

stop() abstractmethod

Останавливает процесс или целевую функцию.

BaseWatcher

Bases: ABC

Абстрактный базовый класс для отслеживания изменений файлов.

Parameters:

Name	Type	Description	Default
paths	str | list[str]	Директория или список директорий/файлов для отслеживания.	required
extensions	list[str] | None	Список расширений файлов без точки (например, ["py", "json"]).	None
ignore_patterns	list[str] | None	Список шаблонов путей/имен для игнорирования (fnmatch).	None
debounce_seconds	float	Задержка пакетирования событий перезапуска в секундах.	0.5
callback	Callable[[list[str]], None] | None	Функция-коллбек, вызываемая при изменении файлов. Принимает список путей.	None

is_running property

Возвращает статус запуска вотчера.

start() abstractmethod

Запускает отслеживание файлов.

stop() abstractmethod

Останавливает отслеживание файлов.

CleanItem dataclass

Элемент, предназначенный для очистки.

display_size property

Возвращает человекочитаемый размер элемента.

InProcessReloader

Bases: BaseRunner

Ранер для внутрипроцессного перезапуска указанной функции с вызовом очистки lifecycle.

Parameters:

Name	Type	Description	Default
target	str	Строка формата "path.to.module:func_name".	required
args	tuple[object, ...] | None	Опциональные позиционные аргументы функции.	None
kwargs	dict[str, object] | None	Опциональные именованные аргументы функции.	None

restart()

Выполняет остановку, перезагружает модуль и снова вызывает функцию.

start()

Вызывает целевую функцию в текущем процессе.

stop()

Вызывает глобальную очистку коллбеков через trigger_cleanup().

LintResult

Представляет результат одной проверки правила (Fallback версия без Pydantic).

__init__(rule_name, message, severity, file_path=None, line_number=None, fix_suggestion=None)

Инициализирует fallback-результат проверки правила.

Parameters:

Name	Type	Description	Default
rule_name	str	Название правила.	required
message	str	Сообщение об ошибке/предупреждении.	required
severity	str	Критичность проблемы.	required
file_path	str | None	Опциональный путь к файлу.	None
line_number	int | None	Номер строки.	None
fix_suggestion	str | None	Рекомендация по исправлению.	None

LinterEngine

Движок линтера, координирующий сбор файлов, загрузку правил и их выполнение.

__init__(config)

Инициализирует движок с переданной конфигурацией.

Parameters:

Name	Type	Description	Default
config	dict[str, str | bool | list[str] | None]	Словарь настроек линтера.	required

collect_all_files()

Собирает абсолютно все неигнорируемые файлы в проекте.

Returns:

Type	Description
list[str]	Список абсолютных путей к файлам.

collect_files()

Собирает все неигнорируемые файлы в проекте (учитывая флаг staged).

Returns:

Type	Description
list[str]	Список абсолютных путей к файлам.

collect_staged_files()

Собирает список измененных и добавленных файлов, подготовленных к коммиту (staged) в Git.

Returns:

Type	Description
list[str]	Список абсолютных путей к файлам.

load_rules()

Загружает правила (встроенные и кастомные).

print_results(results)

Выводит результаты работы линтера в консоль и возвращает статус завершения.

Parameters:

Name	Type	Description	Default
results	list[LintResult]	Список результатов.	required

Returns:

Type	Description
bool	True, если проверка успешна (нет критических ошибок в строгом режиме/обычном),
bool	False в противном случае.

run()

Запускает все включенные правила на собранных файлах.

Returns:

Type	Description
list[LintResult]	Список результатов проверок с найденными ошибками и предупреждениями.

should_ignore(path)

Проверяет, должен ли данный путь быть проигнорирован.

Parameters:

Name	Type	Description	Default
path	Path	Проверяемый путь.	required

Returns:

Type	Description
bool	True, если путь соответствует какому-либо шаблону игнорирования.

MockServerRunner

Управляющий класс для мок-сервера.

__init__(port=8888, routes_path='mocks.yml', proxy_fallback=None)

Инициализирует MockServerRunner.

Parameters:

Name	Type	Description	Default
port	int	Порт, на котором будет запущен мок-сервер.	8888
routes_path	str	Путь к YAML-файлу с описанием роутов.	'mocks.yml'
proxy_fallback	str | None	URL реального бэкенда для проксирования неизвестных роутов.	None

check_reload()

Проверяет время изменения файла на диске и перезагружает при необходимости.

init_template(output_path)

Создает шаблонный файл конфигурации роутов.

Parameters:

Name	Type	Description	Default
output_path	str	Путь к файлу для сохранения шаблона.	required

load_config()

Загружает роуты из файла (YAML или JSON).

log_event(message)

Выводит отформатированное лог-сообщение в консоль.

Parameters:

Name	Type	Description	Default
message	str	Текст лог-сообщения.	required

run()

Запускает многопоточный HTTP-сервер.

stop()

Останавливает запущенный HTTP-сервер.

PollingWatcher

Bases: BaseWatcher

Вотчер на базе периодического сканирования файловой системы (Fallback mode).

Parameters:

Name	Type	Description	Default
paths	str | list[str]	Директория или список директорий/файлов для отслеживания.	required
extensions	list[str] | None	Список расширений файлов без точки.	None
ignore_patterns	list[str] | None	Шаблоны путей для игнорирования.	None
debounce_seconds	float	Задержка дебаунса.	0.5
poll_interval	float	Интервал между опросами файлов в секундах.	1.0
callback	Callable[[list[str]], None] | None	Коллбек для отправки списка изменившихся файлов.	None

start()

Запускает фоновый поток опроса файловой системы.

stop()

Останавливает фоновый опрос файлов.

Rule

Абстрактный базовый класс для всех правил линтера.

Каждое правило должно переопределить метод check() и задать атрибуты name, description и severity.

Подавление срабатываний инлайн (inline suppress)

Любое срабатывание правила можно подавить без изменения правил, добавив комментарий в конец проблемной строки или в строку непосредственно перед ней::

import logging  # chutils: ignore[ChutilsIntegrationRule]
code()         # chutils: ignore[RuleA, RuleB]
# chutils: ignore[ChutilsIntegrationRule]
some_call()

Для подавления всех правил сразу используйте all::

code()  # chutils: ignore[all]

Правила не должны сами проверять инлайн-комментарии: фильтрация выполняется автоматически в LinterEngine.run().

check(base_dir, files)

Выполняет проверку правила по списку файлов.

Parameters:

Name	Type	Description	Default
base_dir	str	Путь к корню проверяемого проекта.	required
files	list[str]	Список абсолютных путей к файлам проекта.	required

Returns:

Type	Description
list[LintResult]	Список объектов LintResult с найденными проблемами.

Note

Подавить срабатывания отдельного срабатывания можно инлайн-комментарием # chutils: ignore[<name>] — без изменения правила.

SubprocessRunner

Bases: BaseRunner

Ранер для запуска и управления внешним дочерним процессом.

Parameters:

Name	Type	Description	Default
command	str | list[str]	Команда для выполнения (строка или список аргументов).	required
graceful_timeout	float	Время ожидания в секундах перед принудительным завершением (kill).	3.0
cwd	str | None	Рабочая директория для дочернего процесса.	None

process property

Возвращает текущий экземпляр Popen.

start()

Запускает внешнюю команду через subprocess.Popen.

stop()

Мягко останавливает процесс (SIGTERM/SIGINT), затем вызывает kill() при необходимости.

WatchdogWatcher

Bases: BaseWatcher

Вотчер на базе библиотеки watchdog.

Parameters:

Name	Type	Description	Default
paths	str | list[str]	Директория или список директорий/файлов для отслеживания.	required
extensions	list[str] | None	Список расширений файлов без точки.	None
ignore_patterns	list[str] | None	Шаблоны путей для игнорирования.	None
debounce_seconds	float	Задержка дебаунса.	0.5
callback	Callable[[list[str]], None] | None	Коллбек для отправки списка изменившихся файлов.	None

start()

Запускает Observer библиотеки watchdog.

stop()

Останавливает Observer библиотеки watchdog.

collect_context_slice(project_path, modules=None, task=None, layer='public')

Собирает контекстный срез по заданным параметрам.

Parameters:

Name	Type	Description	Default
project_path	Path	Путь к корню проекта.	required
modules	list[str] | None	Список выбранных модулей.	None
task	str | None	Описание задачи.	None
layer	str	Слой абстракции для фильтрации символов.	'public'

Returns:

Type	Description
str	Сгенерированный Markdown с контекстом.

execute_clean(items)

Удаляет найденные мусорные элементы.

Parameters:

Name	Type	Description	Default
items	list[CleanItem]	Список элементов CleanItem для удаления.	required

Returns:

Type	Description
tuple[int, int]	Кортеж (количество удаленных элементов, суммарно освобожденный размер в байтах).

generate_few_shot_bank(project_path, *, force=False, console=None)

Генерирует банк few-shot примеров для целевого проекта.

Анализирует архитектуру проекта, детектирует ключевые абстракции (Use Cases, репозитории, логгеры, исключения, DI-контейнеры) и создаёт параметризованные шаблоны docs/ai_examples/ в корне целевого проекта.

Parameters:

Name	Type	Description	Default
project_path	str	Путь к корневой директории целевого проекта.	required
force	bool	Если True, существующие категории будут перезаписаны.	False
console	_ConsoleProtocol | None	Объект Rich Console для вывода статуса (опционально).	None

Returns:

Type	Description
GenerationResult	GenerationResult с детализацией созданных и пропущенных категорий.

Raises:

Type	Description
FileNotFoundError	Если project_path не существует.
ValueError	При нарушении path traversal защиты.

generate_workflow_yaml(python_versions, with_pytest, with_mypy, with_ruff, with_ai_lint)

Генерирует валидный YAML-конфиг для GitHub Actions на основе setup-uv.

Parameters:

Name	Type	Description	Default
python_versions	list[str]	Список версий Python для матрицы тестирования.	required
with_pytest	bool	Запускать ли тесты с pytest.	required
with_mypy	bool	Запускать ли статический анализ типов с mypy.	required
with_ruff	bool	Запускать ли линтинг кода с ruff.	required
with_ai_lint	bool	Запускать ли аудит готовности к AI с chutils dev ai-lint.	required

Returns:

Type	Description
str	Строка с содержимым YAML-файла.

get_watcher(paths, extensions=None, ignore_patterns=None, debounce_seconds=0.5, poll_interval=1.0, callback=None)

Фабричная функция для создания наилучшего доступного файлового вотчера.

Использует WatchdogWatcher, если установлена библиотека watchdog, иначе выводит предупреждение в лог и использует PollingWatcher.

Parameters:

Name	Type	Description	Default
paths	str | list[str]	Путь или список путей для отслеживания.	required
extensions	list[str] | None	Расширения файлов для отслеживания.	None
ignore_patterns	list[str] | None	Шаблоны для игнорирования.	None
debounce_seconds	float	Таймаут пакетирования событий.	0.5
poll_interval	float	Интервал опроса для PollingWatcher.	1.0
callback	Callable[[list[str]], None] | None	Коллбек при изменении файлов.	None

Returns:

Type	Description
BaseWatcher	Экземпляр BaseWatcher (WatchdogWatcher или PollingWatcher).

run_interactive_menu(project_path)

Запускает красивое интерактивное CLI-меню для выбора модулей.

Parameters:

Name	Type	Description	Default
project_path	Path	Путь к корню проекта.	required

Returns:

Type	Description
list[str]	Список выбранных пользователем модулей.

scan_project(base_dir, excludes=None, default_targets=None, extra_targets=None)

Сканирует проект и возвращает список найденных временных файлов и папок.

Parameters:

Name	Type	Description	Default
base_dir	str | Path	Корневая директория проекта.	required
excludes	list[str] | None	Список папок или шаблонов для исключения из обхода.	None
default_targets	list[str] | None	Базовый список шаблонов временных файлов/папок.	None
extra_targets	list[str] | None	Дополнительные шаблоны для очистки.	None

Returns:

Type	Description
list[CleanItem]	Список объектов CleanItem.

options: members:

• Rule
• LintResult
• LinterEngine
• collect_context_slice
• run_interactive_menu
• generate_few_shot_bank
• MockServerRunner
• Scaffolder
• generate_workflow_yaml

Модуль diagnostics (Мониторинг работоспособности)

chutils.diagnostics

CheckResult dataclass

Результат выполнения проверки диагностики (вариант без Pydantic).

Attributes:

Name	Type	Description
name	str	Название проверки.
success	bool	Флаг успешности проверки.
critical	bool	Флаг критичности проверки.
execution_time	float	Время выполнения проверки в секундах.
error	str | None	Текст ошибки, если проверка завершилась неудачно.
message	str | None	Дополнительное информационное сообщение.

model_dump()

Преобразует модель в словарь.

Returns:

Type	Description
dict[str, str | bool | float | None]	Словарь с данными о результате проверки.

HealthReport dataclass

Отчет о состоянии работоспособности системы (вариант без Pydantic).

Attributes:

Name	Type	Description
status	str	Общий статус системы (HEALTHY, DEGRADED, UNHEALTHY).
results	list[CheckResult]	Список результатов проверок.
total_time	float	Общее время выполнения всех проверок в секундах.

model_dump()

Преобразует отчет в словарь.

Returns:

Type	Description
dict[str, str | list[dict[str, str | bool | float | None]] | float]	Словарь с данными о состоянии здоровья системы.

options: members:

• DiagnosticsManager
• CheckResult
• HealthReport
• get_fastapi_health_handler
• get_flask_health_handler

Модуль env (Манифест окружения)

chutils.env

BaseEnvManifest

Заглушка манифеста переменных окружения (Pydantic не установлен).

load() classmethod

Пытается загрузить манифест без Pydantic.

Returns:

Type	Description
Self	Метод никогда не возвращает значение, так как всегда вызывает исключение.

Raises:

Type	Description
OptionalDependencyError	Всегда выбрасывается, так как Pydantic отсутствует.

has_pydantic()

Возвращает True, если Pydantic установлен.

Returns:

Type	Description
bool	True, если пакет pydantic доступен для импорта.

has_rich()

Возвращает True, если Rich установлен.

Returns:

Type	Description
bool	True, если пакет rich доступен для импорта.

has_watchdog()

Возвращает True, если Watchdog установлен.

Returns:

Type	Description
bool	True, если пакет watchdog доступен для импорта.

is_otel_enabled()

Проверяет, доступен ли OpenTelemetry и не отключен ли он.

Учитывает: - Наличие установленного пакета opentelemetry. - Переменную окружения CH_DISABLE_TRACING

Returns:

Type	Description
bool	True, если OpenTelemetry трассировка включена и доступна.

is_rich_enabled()

Централизованная проверка: доступен ли Rich и разрешен ли он настройками.

Учитывает: - Наличие установленного пакета rich. - Переменные окружения NO_COLOR, CH_NO_COLOR. - Специальную переменную CH_NO_RICH (для тестов и headless).

Returns:

Type	Description
bool	True, если вывод Rich разрешен и пакет установлен, иначе False.

options: members:

• BaseEnvManifest
• is_rich_enabled
• is_otel_enabled

Модуль validation (Валидация данных)

chutils.validation

validate_call(func)

Декоратор для автоматической валидации аргументов вызова функции.

Использует pydantic.validate_call под капотом, если pydantic установлен. В случае ошибки валидации выбрасывает ChutilsValidationError.

Parameters:

Name	Type	Description	Default
func	Callable[_P, _R]	Декорируемая функция (синхронная или асинхронная).	required

Returns:

Type	Description
Callable[_P, _R]	Декорированная функция с автоматической валидацией аргументов.

Raises:

Type	Description
OptionalDependencyError	Если пакет pydantic не установлен в системе.

validate_data(model, data)

Валидирует словарь или JSON-строку по заданной Pydantic модели.

Parameters:

Name	Type	Description	Default
model	type[_T]	Класс Pydantic модели для валидации.	required
data	dict[str, Any] | str	Данные для валидации в виде словаря или JSON-строки.	required

Returns:

Type	Description
_T	Экземпляр провалидированной модели Pydantic.

Raises:

Type	Description
OptionalDependencyError	Если пакет pydantic не установлен.
ChutilsValidationError	Если данные не прошли валидацию или JSON невалиден.

options: members:

• validate_data
• validate_call

Модуль web (Умный HTTP-клиент)

chutils.web

AsyncWebClient

Bases: AsyncClient

Асинхронный HTTP-клиент с поддержкой ротации User-Agent, прокси-пулов,

лимитирования частоты и кэширования GET-запросов.

__init__(*args, user_agent_rotator=None, proxy_pool=None, rotate_ua=True, rotate_proxy=True, retries=0, retry_delay=1.0, retry_backoff=2.0, retry_on_5xx=True, rate_limit_calls=None, rate_limit_period=1.0, rate_limit_strategy='token_bucket', rate_limit_wait=False, cache_ttl=None, cache_backend=None, **kwargs)

Инициализирует AsyncWebClient.

Parameters:

Name	Type	Description	Default
*args	Any	Позиционные аргументы для родительского класса httpx.AsyncClient.	()
user_agent_rotator	UserAgentRotator | None	Ротатор User-Agent.	None
proxy_pool	ProxyPool | None	Менеджер пула прокси.	None
rotate_ua	bool	Включить ли ротацию User-Agent.	True
rotate_proxy	bool	Включить ли смену прокси при ошибках.	True
retries	int	Количество повторов при ошибках.	0
retry_delay	float	Базовая задержка между попытками в секундах.	1.0
retry_backoff	float	Множитель задержки.	2.0
retry_on_5xx	bool	Считать ли 5xx ошибки сбоем для повтора.	True
rate_limit_calls	int | None	Ограничение количества запросов к хосту.	None
rate_limit_period	float	Период ограничения в секундах.	1.0
rate_limit_strategy	str	Стратегия лимитирования ('token_bucket' или 'leaky_bucket').	'token_bucket'
rate_limit_wait	bool	Ждать ли освобождения токена (или вызывать исключение).	False
cache_ttl	int | None	Время жизни кэша GET-запросов в секундах.	None
cache_backend	Any | None	Бэкенд кэша.	None
**kwargs	Any	Именованные аргументы для родительского класса httpx.AsyncClient.	{}

rotate_proxy() async

Асинхронно переключает текущий клиент на следующий прокси из пула.

send(request, *args, **kwargs) async

Перехватывает отправку запроса для ротации, лимитов и кэширования.

Parameters:

Name	Type	Description	Default
request	Request	Объект отправляемого запроса httpx.Request.	required
*args	Any	Произвольные позиционные аргументы.	()
**kwargs	Any	Произвольные именованные аргументы.	{}

Returns:

Type	Description
Response	Ответ сервера httpx.Response.

WebClient

Bases: Client

Синхронный HTTP-клиент с поддержкой ротации User-Agent, прокси-пулов,

лимитирования частоты и кэширования GET-запросов.

__init__(*args, user_agent_rotator=None, proxy_pool=None, rotate_ua=True, rotate_proxy=True, retries=0, retry_delay=1.0, retry_backoff=2.0, retry_on_5xx=True, rate_limit_calls=None, rate_limit_period=1.0, rate_limit_strategy='token_bucket', rate_limit_wait=False, cache_ttl=None, cache_backend=None, **kwargs)

Инициализирует WebClient.

Parameters:

Name	Type	Description	Default
*args	Any	Позиционные аргументы для родительского класса httpx.Client.	()
user_agent_rotator	UserAgentRotator | None	Ротатор User-Agent.	None
proxy_pool	ProxyPool | None	Менеджер пула прокси.	None
rotate_ua	bool	Включить ли ротацию User-Agent.	True
rotate_proxy	bool	Включить ли смену прокси при ошибках.	True
retries	int	Количество повторов при ошибках.	0
retry_delay	float	Базовая задержка между попытками в секундах.	1.0
retry_backoff	float	Множитель задержки.	2.0
retry_on_5xx	bool	Считать ли 5xx ошибки сбоем для повтора.	True
rate_limit_calls	int | None	Ограничение количества запросов к хосту.	None
rate_limit_period	float	Период ограничения в секундах.	1.0
rate_limit_strategy	str	Стратегия лимитирования ('token_bucket' или 'leaky_bucket').	'token_bucket'
rate_limit_wait	bool	Ждать ли освобождения токена (или вызывать исключение).	False
cache_ttl	int | None	Время жизни кэша GET-запросов в секундах.	None
cache_backend	Any | None	Бэкенд кэша.	None
**kwargs	Any	Именованные аргументы для родительского класса httpx.Client.	{}

rotate_proxy()

Переключает текущий клиент на следующий прокси из пула.

send(request, *args, **kwargs)

Перехватывает отправку запроса для ротации, лимитов и кэширования.

Parameters:

Name	Type	Description	Default
request	Request	Объект отправляемого запроса httpx.Request.	required
*args	Any	Произвольные позиционные аргументы.	()
**kwargs	Any	Произвольные именованные аргументы.	{}

Returns:

Type	Description
Response	Ответ сервера httpx.Response.

options: members:

• WebClient
• AsyncWebClient

Модуль scraping.humanize (Имитация поведения человека)

chutils.scraping.humanize

AntidetectConfig

Bases: BaseModel

Конфигурация параметров маскировки браузера (антидетект).

apply_to_nodriver(tab) async

Применяет данную конфигурацию антидетекта к вкладке nodriver Tab.

Parameters:

Name	Type	Description	Default
tab	Any	Экземпляр вкладки nodriver Tab.	required

apply_to_playwright(target) async

Применяет данную конфигурацию антидетекта к Playwright Page или BrowserContext.

Parameters:

Name	Type	Description	Default
target	Any	Экземпляр Playwright BrowserContext или Page.	required

apply_to_selenium(driver)

Применяет данную конфигурацию антидетекта к Selenium WebDriver.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required

from_browserforge(seed=None, *, browser='chrome', os='windows', stealth_minimal=True) classmethod

Генерирует отпечаток через байесовскую сеть browserforge (при наличии пакета).

Parameters:

Name	Type	Description	Default
seed	int | str | None	Опциональный сид для воспроизводимой детерминированной генерации.	None
browser	str	Эмулируемый браузер ('chrome').	'chrome'
os	str	Целевая ОС ('windows').	'windows'
stealth_minimal	bool	Режим маскировки.	True

Returns:

Type	Description
AntidetectConfig	Экземпляр AntidetectConfig.

from_fingerprint(profile, *, stealth_minimal=True) classmethod

Создает AntidetectConfig на основе объекта FingerprintProfile.

Parameters:

Name	Type	Description	Default
profile	FingerprintProfile | Any	Экземпляр FingerprintProfile.	required
stealth_minimal	bool	Если True, не накладывать синтетический шум на Canvas.	True

Returns:

Type	Description
AntidetectConfig	Сконфигурированный экземпляр AntidetectConfig.

from_procedural(seed=None, *, stealth_minimal=True, os_target='windows', locale='ru-RU') classmethod

Синтезирует отпечаток через встроенный процедурный генератор.

Parameters:

Name	Type	Description	Default
seed	int | str | None	Опциональный сид.	None
stealth_minimal	bool	Режим маскировки.	True
os_target	str	Целевая ОС.	'windows'
locale	str	Локаль.	'ru-RU'

Returns:

Type	Description
AntidetectConfig	Экземпляр AntidetectConfig.

from_seed(seed, *, stealth_minimal=True, os_target='windows', locale='ru-RU') classmethod

Синтезирует детерминированную цифровую личность по сиду и возвращает AntidetectConfig.

Один и тот же сид всегда дает абсолютно идентичный и физически согласованный отпечаток (видеокарта, процессор, память, геометрия экрана, панель задач).

Parameters:

Name	Type	Description	Default
seed	int | str	Сид профиля или имя учетной записи.	required
stealth_minimal	bool	Если True, сохраняет чистый отпечаток без искажения Canvas.	True
os_target	str	Целевая ОС ('windows').	'windows'
locale	str	Локаль ('ru-RU', 'en-US').	'ru-RU'

Returns:

Type	Description
AntidetectConfig	Экземпляр AntidetectConfig.

get_behavioral_profile()

Возвращает детерминированный биометрический профиль моторики на основе session_seed.

Returns:

Type	Description
Any	Экземпляр BehavioralProfile.

get_init_script()

Генерирует JavaScript-скрипт антидетекта на основе настроек конфигурации.

Returns:

Type	Description
str	Строка исполняемого JavaScript-кода для инъекции в браузер.

preset_aggressive(*, webgl_vendor=DEFAULT_WEBGL_VENDOR, webgl_renderer=DEFAULT_WEBGL_RENDERER, hardware_concurrency=DEFAULT_HARDWARE_CONCURRENCY, device_memory=DEFAULT_DEVICE_MEMORY, session_seed=1337, client_hints=None, user_agent=None) classmethod

Агрессивный пресет с рандомизацией Canvas/WebGL/Audio (для Playwright/Selenium в headless).

Parameters:

Name	Type	Description	Default
webgl_vendor	str	Эмулируемый производитель WebGL.	DEFAULT_WEBGL_VENDOR
webgl_renderer	str	Эмулируемая видеокарта WebGL.	DEFAULT_WEBGL_RENDERER
hardware_concurrency	int	Эмулируемое количество ядер CPU.	DEFAULT_HARDWARE_CONCURRENCY
device_memory	int	Эмулируемый объем оперативной памяти в ГБ.	DEFAULT_DEVICE_MEMORY
session_seed	str | int	Сид для рандомизации шума Canvas/Audio.	1337
client_hints	dict[str, Any] | None	Дополнительные параметры Client Hints.	None
user_agent	str | None	Опциональная строка User-Agent.	None

Returns:

Type	Description
AntidetectConfig	Экземпляр AntidetectConfig с агрессивной рандомизацией.

preset_minimal(*, session_seed=1337, user_agent=None) classmethod

Минимальный пресет: отключен шум, только базовая защита от утечек и скрытие webdriver.

Parameters:

Name	Type	Description	Default
session_seed	str | int	Сид для инициализации сессии.	1337
user_agent	str | None	Опциональная строка User-Agent.	None

Returns:

Type	Description
AntidetectConfig	Экземпляр AntidetectConfig с минимальной модификацией.

preset_stealth_nodriver(*, session_seed=1337, client_hints=None, user_agent=None) classmethod

Рекомендуемый пресет для nodriver: zero-footprint (без синтетического шума Canvas/WebGL).

Parameters:

Name	Type	Description	Default
session_seed	str | int	Сид для детерминированного генератора псевдослучайных чисел.	1337
client_hints	dict[str, Any] | None	Опциональный словарь с параметрами Client Hints.	None
user_agent	str | None	Опциональная строка User-Agent.	None

Returns:

Type	Description
AntidetectConfig	Экземпляр AntidetectConfig с конфигурацией zero-footprint.

BehavioralProfile

Bases: BaseModel

Конфигурация биометрического профиля моторики (скорость, задержки, опечатки, движение мыши).

error_rate property

Алиас для typo_rate.

wpm property

Алиас для speed_wpm.

async_click(page, selector=None, x=None, y=None, start=None, button='left') async

Выполняет клик по элементу или координатам с биометрией удержания кнопки мыши.

Parameters:

Name	Type	Description	Default
page	Any	Объект страницы Playwright Page или вкладки nodriver Tab.	required
selector	str | None	Селектор целевого элемента (опционально).	None
x	int | None	Конечная координата X клика.	None
y	int | None	Конечная координата Y клика.	None
start	tuple[int, int] | None	Начальные координаты курсора.	None
button	str	Кнопка мыши ('left', 'right', 'middle').	'left'

async_type_text(page, selector, text, paste_threshold=None) async

Вводит текст через Playwright / nodriver с биометрическими параметрами профиля.

Parameters:

Name	Type	Description	Default
page	Any	Объект страницы Playwright Page или вкладки nodriver Tab.	required
selector	str	CSS/XPath селектор поля ввода.	required
text	str	Текст для ввода.	required
paste_threshold	int | None	Порог адаптивной вставки через буфер (если None, берется из профиля).	None

click(driver, selector=None, x=None, y=None, start=None, algorithm='windmouse')

Синхронно выполняет клик через Selenium с биометрией удержания кнопки мыши.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required
selector	str | None	Селектор целевого элемента.	None
x	int | None	Координата X клика.	None
y	int | None	Координата Y клика.	None
start	tuple[int, int] | None	Начальные координаты мыши.	None
algorithm	str	Алгоритм перемещения ('windmouse' или 'bezier').	'windmouse'

create_typo_generator()

Создает генератор опечаток клавиатуры, настроенный под параметры профиля.

Returns:

Type	Description
KeyboardTypoGenerator	Экземпляр KeyboardTypoGenerator.

create_wind_mouse()

Создает генератор траекторий мыши WindMouse, настроенный под параметры профиля.

Returns:

Type	Description
WindMouseGenerator	Экземпляр WindMouseGenerator.

from_seed(seed) classmethod

Создает детерминированный биометрический профиль моторики на основе сида.

Один и тот же сид всегда порождает абсолютно идентичные биометрические характеристики (скорость ввода, опечатки, физику мыши, интервалы удержания), что позволяет зафиксировать уникальный почерк конкретного аккаунта или браузерного профиля.

Parameters:

Name	Type	Description	Default
seed	int | str	Числовой или строковый сид сессии/аккаунта.	required

Returns:

Type	Description
BehavioralProfile	Экземпляр BehavioralProfile с реалистичными биометрическими характеристиками.

type_text(driver, selector, text, paste_threshold=None)

Синхронно вводит текст через Selenium с биометрическими параметрами профиля.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required
selector	str	CSS-селектор поля ввода.	required
text	str	Текст для ввода.	required
paste_threshold	int | None	Порог адаптивной вставки через буфер (если None, берется из профиля).	None

BezierCurveGenerator

Генератор траекторий перемещения на основе кривых Безье.

generate(start, end, steps=30, deviation=0.2)

Генерирует сглаженную траекторию от start к end.

Parameters:

Name	Type	Description	Default
start	tuple[int, int]	Начальная координата (x, y).	required
end	tuple[int, int]	Конечная координата (x, y).	required
steps	int	Количество шагов (точек) в траектории.	30
deviation	float	Максимальное отклонение контрольных точек от прямой линии.	0.2

Returns:

Type	Description
list[tuple[int, int]]	Список координат точек траектории движения.

JitterDelayGenerator

Генератор реалистичных задержек.

__init__(strategy='lognormal', jitter=0.15)

Инициализирует генератор задержек.

Parameters:

Name	Type	Description	Default
strategy	str	Стратегия ('lognormal' или 'normal').	'lognormal'
jitter	float	Коэффициент разброса (джиттер).	0.15

generate(base_delay)

Возвращает сгенерированную задержку на основе базовой.

Parameters:

Name	Type	Description	Default
base_delay	float	Базовая величина задержки (в секундах).	required

Returns:

Type	Description
float	Полученное случайное значение задержки с учетом джиттера.

KeyboardTypoGenerator

Генератор последовательностей ввода символов с реалистичными опечатками.

__init__(layout_error_rate=0.0, delayed_fix_rate=0.0)

Инициализирует генератор опечаток.

Parameters:

Name	Type	Description	Default
layout_error_rate	float	Вероятность ошибки переключения раскладки в начале ввода (0.0 - 1.0).	0.0
delayed_fix_rate	float	Вероятность отложенного исправления опечатки навигацией стрелками (0.0 - 1.0).	0.0

generate_sequence(text, error_rate=0.05, layout_error_rate=None, delayed_fix_rate=None)

Генерирует последовательность нажатий клавиш для ввода текста.

Включает случайные опечатки, их обнаружение и исправление через Backspace. При ненулевой layout_error_rate в самом начале ввода может произойти реалистичная ошибка раскладки (например, ввод нескольких символов латиницей вместо кириллицы с последующим полным стиранием и повторным вводом на правильном языке). При ненулевой delayed_fix_rate моделируется более сложная опечатка: пользователь допускает ошибку, по инерции допечатывает несколько символов/слов, а затем возвращается клавишами стрелок назад (ArrowLeft), исправляет опечатку и прыгает в конец строки (End).

Parameters:

Name	Type	Description	Default
text	str	Исходный текст.	required
error_rate	float	Вероятность совершения ошибки на каждом символе.	0.05
layout_error_rate	float | None	Вероятность ошибки раскладки в начале ввода. Если None, используется значение из конструктора (по умолчанию 0.0).	None
delayed_fix_rate	float | None	Вероятность отложенного исправления опечатки. Если None, используется значение из конструктора (по умолчанию 0.0).	None

Returns:

Type	Description
list[TypoAction]	Список действий TypoAction, имитирующий последовательный ввод текста человеком.

ProfileWarmer

Класс для асинхронного прогрева браузерных профилей (Playwright, nodriver).

Обеспечивает естественный цифровой след путем посещения сайтов, скроллинга, имитации мыши и переходов по внутренним ссылкам.

__init__(browser_or_tab)

Инициализирует ProfileWarmer.

Parameters:

Name	Type	Description	Default
browser_or_tab	Any	Объект страницы Playwright Page или вкладки nodriver Tab.	required

save_profile(filepath, password=None, metadata=None) async

Экспортирует сессию после прогрева и сохраняет её в .chprofile файл через ProfileManager.

Parameters:

Name	Type	Description	Default
filepath	str | Path	Путь к сохраняемому файлу (.chprofile).	required
password	str | None	Опциональный пароль для шифрования данных профиля.	None
metadata	dict[str, str] | None	Пользовательские метаданные.	None

Returns:

Type	Description
Any	Экземпляр BrowserProfile.

warm_up(sites=None, sites_count=3, duration_per_site=(10.0, 30.0), click_random_links=True) async

Запускает процесс прогрева профиля.

Parameters:

Name	Type	Description	Default
sites	list[str] | None	Список URL-адресов трастовых сайтов для прогрева. Если None, используется встроенный список.	None
sites_count	int	Количество посещаемых сайтов.	3
duration_per_site	tuple[float, float]	Диапазон времени пребывания на одном сайте (мин, макс в секундах).	(10.0, 30.0)
click_random_links	bool	Флаг перехода по случайным внутренним ссылкам.	True

warm_up_search(queries=None, category=None, queries_count=2, search_engine='google', click_result=True, surf_result_duration=(5.0, 15.0)) async

Симулирует органический поиск и серфинг по результатам выдачи.

Parameters:

Name	Type	Description	Default
queries	list[str] | None	Список поисковых запросов. Если None, выбираются случайные запросы из банка.	None
category	str | None	Категория запросов ('tech', 'news', 'science', 'lifestyle'), если queries is None.	None
queries_count	int	Количество запросов для поиска.	2
search_engine	str	Поисковая система ('google' или 'yandex').	'google'
click_result	bool	Переходить ли по органической ссылке из выдачи.	True
surf_result_duration	tuple[float, float]	Время пребывания на целевом сайте после перехода (мин, макс в секундах).	(5.0, 15.0)

SyncProfileWarmer

Класс для синхронного прогрева браузерных профилей (Selenium).

__init__(driver)

Инициализирует SyncProfileWarmer.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required

save_profile(filepath, password=None, metadata=None)

Синхронно экспортирует сессию Selenium и сохраняет в .chprofile файл через ProfileManager.

Parameters:

Name	Type	Description	Default
filepath	str | Path	Путь к сохраняемому файлу (.chprofile).	required
password	str | None	Опциональный пароль для шифрования.	None
metadata	dict[str, str] | None	Пользовательские метаданные.	None

Returns:

Type	Description
Any	Экземпляр BrowserProfile.

warm_up(sites=None, sites_count=3, duration_per_site=(10.0, 30.0), click_random_links=True)

Запускает процесс прогрева профиля (синхронно).

Parameters:

Name	Type	Description	Default
sites	list[str] | None	Список URL-адресов трастовых сайтов для прогрева. Если None, используется встроенный список.	None
sites_count	int	Количество посещаемых сайтов.	3
duration_per_site	tuple[float, float]	Диапазон времени пребывания на одном сайте (мин, макс в секундах).	(10.0, 30.0)
click_random_links	bool	Флаг перехода по случайным внутренним ссылкам.	True

warm_up_search(queries=None, category=None, queries_count=2, search_engine='google', click_result=True, surf_result_duration=(5.0, 15.0))

Синхронно симулирует органический поиск и серфинг по результатам выдачи Selenium.

Parameters:

Name	Type	Description	Default
queries	list[str] | None	Список поисковых запросов. Если None, выбираются случайные запросы из банка.	None
category	str | None	Категория запросов ('tech', 'news', 'science', 'lifestyle'), если queries is None.	None
queries_count	int	Количество запросов для поиска.	2
search_engine	str	Поисковая система ('google' или 'yandex').	'google'
click_result	bool	Переходить ли по органической ссылке из выдачи.	True
surf_result_duration	tuple[float, float]	Время пребывания на целевом сайте после перехода (мин, макс в секундах).	(5.0, 15.0)

WindMouseGenerator

Генератор траекторий перемещения мыши на основе физической модели WindMouse (гравитация, ветер, инерция).

__init__(gravity=9.0, wind=3.0, min_wait=0.002, max_wait=0.005, max_step=15.0, target_area=8.0)

Инициализирует генератор WindMouse.

Parameters:

Name	Type	Description	Default
gravity	float	Сила притяжения курсора к целевой точке.	9.0
wind	float	Величина случайного отклонения (ветра/мышечных микроколебаний).	3.0
min_wait	float	Минимальная пауза между смещениями (в секундах).	0.002
max_wait	float	Максимальная пауза между смещениями (в секундах).	0.005
max_step	float	Максимальное расстояние одного шага (скорость).	15.0
target_area	float	Радиус целевой зоны, при входе в которую уменьшается влияние ветра и падает скорость.	8.0

generate(start, end, gravity=None, wind=None, min_wait=None, max_wait=None, max_step=None, target_area=None, *, with_delays=True)

generate(
    start: tuple[int, int],
    end: tuple[int, int],
    gravity: float | None = None,
    wind: float | None = None,
    min_wait: float | None = None,
    max_wait: float | None = None,
    max_step: float | None = None,
    target_area: float | None = None,
    *,
    with_delays: Literal[True] = ...,
) -> list[tuple[int, int, float]]

generate(
    start: tuple[int, int],
    end: tuple[int, int],
    gravity: float | None = None,
    wind: float | None = None,
    min_wait: float | None = None,
    max_wait: float | None = None,
    max_step: float | None = None,
    target_area: float | None = None,
    *,
    with_delays: Literal[False],
) -> list[tuple[int, int]]

generate(
    start: tuple[int, int],
    end: tuple[int, int],
    gravity: float | None = None,
    wind: float | None = None,
    min_wait: float | None = None,
    max_wait: float | None = None,
    max_step: float | None = None,
    target_area: float | None = None,
    *,
    with_delays: bool,
) -> list[tuple[int, int, float]] | list[tuple[int, int]]

Генерирует последовательность точек от start к end.

Parameters:

Name	Type	Description	Default
start	tuple[int, int]	Начальные координаты (x, y).	required
end	tuple[int, int]	Конечные координаты (x, y).	required
gravity	float | None	Переопределение силы гравитации.	None
wind	float | None	Переопределение силы ветра.	None
min_wait	float | None	Переопределение минимальной задержки шага.	None
max_wait	float | None	Переопределение максимальной задержки шага.	None
max_step	float | None	Переопределение максимального размера шага.	None
target_area	float | None	Переопределение радиуса целевой зоны.	None
with_delays	bool	Если True, возвращает кортежи (x, y, delay). Если False, возвращает (x, y).	True

Returns:

Type	Description
list[tuple[int, int, float]] | list[tuple[int, int]]	Список точек пути с задержками или без них.

generate_points(start, end, gravity=None, wind=None, max_step=None, target_area=None)

Генерирует последовательность координат (x, y) без задержек.

Parameters:

Name	Type	Description	Default
start	tuple[int, int]	Начальные координаты (x, y).	required
end	tuple[int, int]	Конечные координаты (x, y).	required
gravity	float | None	Переопределение силы гравитации.	None
wind	float | None	Переопределение силы ветра.	None
max_step	float | None	Переопределение максимального размера шага.	None
target_area	float | None	Переопределение радиуса целевой зоны.	None

Returns:

Type	Description
list[tuple[int, int]]	Список координат (x, y).

apply_antidetect_nodriver(tab, *, config=None, webgl_vendor=DEFAULT_WEBGL_VENDOR, webgl_renderer=DEFAULT_WEBGL_RENDERER, hardware_concurrency=DEFAULT_HARDWARE_CONCURRENCY, device_memory=DEFAULT_DEVICE_MEMORY, stealth_minimal=True, session_seed=1337, client_hints=None, user_agent=None) async

Применяет JS-инъекции анти-детекта к вкладке (Tab) nodriver.

По умолчанию stealth_minimal=True для сохранения естественного отпечатка реального Chromium и предотвращения детекта искусственного шума Canvas/WebGL.

Parameters:

Name	Type	Description	Default
tab	Any	Объект вкладки nodriver Tab.	required
config	AntidetectConfig | None	Экземпляр AntidetectConfig (если указан, параметры берутся из него).	None
webgl_vendor	str	Подменяемый производитель WebGL.	DEFAULT_WEBGL_VENDOR
webgl_renderer	str	Подменяемая видеокарта WebGL.	DEFAULT_WEBGL_RENDERER
hardware_concurrency	int	Эмулируемое количество ядер процессора.	DEFAULT_HARDWARE_CONCURRENCY
device_memory	int	Эмулируемый объем оперативной памяти в ГБ.	DEFAULT_DEVICE_MEMORY
stealth_minimal	bool	Если True, не накладывать синтетический шум на Canvas и не подменять WebGL, сохраняя естественный отпечаток установленного браузера Google Chrome (True по умолчанию).	True
session_seed	str | int	Сид для детерминированного шума Canvas.	1337
client_hints	dict[str, Any] | None	Дополнительные параметры Client Hints (navigator.userAgentData).	None
user_agent	str | None	Пользовательская строка User-Agent для переопределения через CDP.	None

apply_antidetect_playwright(context, *, config=None, webgl_vendor=DEFAULT_WEBGL_VENDOR, webgl_renderer=DEFAULT_WEBGL_RENDERER, hardware_concurrency=DEFAULT_HARDWARE_CONCURRENCY, device_memory=DEFAULT_DEVICE_MEMORY, stealth_minimal=False, session_seed=1337, client_hints=None, user_agent=None) async

Применяет JS-инъекции анти-детекта к контексту Playwright.

Parameters:

Name	Type	Description	Default
context	Any	Объект контекста Playwright BrowserContext.	required
config	AntidetectConfig | None	Экземпляр AntidetectConfig (если указан, параметры берутся из него).	None
webgl_vendor	str	Подменяемый производитель WebGL.	DEFAULT_WEBGL_VENDOR
webgl_renderer	str	Подменяемая видеокарта WebGL.	DEFAULT_WEBGL_RENDERER
hardware_concurrency	int	Эмулируемое количество ядер процессора.	DEFAULT_HARDWARE_CONCURRENCY
device_memory	int	Эмулируемый объем оперативной памяти в ГБ.	DEFAULT_DEVICE_MEMORY
stealth_minimal	bool	Если True, не накладывать синтетический шум на Canvas и не подменять WebGL.	False
session_seed	str | int	Сид для детерминированного шума Canvas.	1337
client_hints	dict[str, Any] | None	Дополнительные параметры Client Hints (navigator.userAgentData).	None
user_agent	str | None	Пользовательская строка User-Agent.	None

apply_antidetect_selenium(driver, *, config=None, webgl_vendor=DEFAULT_WEBGL_VENDOR, webgl_renderer=DEFAULT_WEBGL_RENDERER, hardware_concurrency=DEFAULT_HARDWARE_CONCURRENCY, device_memory=DEFAULT_DEVICE_MEMORY, stealth_minimal=False, session_seed=1337, client_hints=None, user_agent=None)

Применяет JS-инъекции анти-детекта к сессии Selenium.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required
config	AntidetectConfig | None	Экземпляр AntidetectConfig (если указан, параметры берутся из него).	None
webgl_vendor	str	Подменяемый производитель WebGL.	DEFAULT_WEBGL_VENDOR
webgl_renderer	str	Подменяемая видеокарта WebGL.	DEFAULT_WEBGL_RENDERER
hardware_concurrency	int	Эмулируемое количество ядер процессора.	DEFAULT_HARDWARE_CONCURRENCY
device_memory	int	Эмулируемый объем оперативной памяти в ГБ.	DEFAULT_DEVICE_MEMORY
stealth_minimal	bool	Если True, не накладывать синтетический шум на Canvas и не подменять WebGL.	False
session_seed	str | int	Сид для детерминированного шума Canvas.	1337
client_hints	dict[str, Any] | None	Дополнительные параметры Client Hints (navigator.userAgentData).	None
user_agent	str | None	Пользовательская строка User-Agent.	None

async_click(page, selector=None, x=None, y=None, start=None, algorithm='windmouse', button='left', hold_time=(0.05, 0.12), timeout=None) async

Имитирует реалистичный клик мышью (с плавным наведением, микропаузами и удержанием кнопки).

Parameters:

Name	Type	Description	Default
page	Any	Объект страницы Playwright Page или вкладки nodriver Tab.	required
selector	str | None	Селектор целевого элемента (если x, y не заданы).	None
x	int | None	Конечная координата X.	None
y	int | None	Конечная координата Y.	None
start	tuple[int, int] | None	Начальные координаты курсора.	None
algorithm	str	Алгоритм движения ('windmouse' или 'bezier').	'windmouse'
button	str	Кнопка мыши ('left', 'right', 'middle').	'left'
hold_time	tuple[float, float]	Диапазон задержки удержания кнопки мыши (в секундах).	(0.05, 0.12)
timeout	float | None	Таймаут выполнения операции в секундах.	None

async_human_sleep(min_seconds, max_seconds) async

Асинхронно задерживает выполнение на случайное время, имитируя поведение человека.

Parameters:

Name	Type	Description	Default
min_seconds	float	Минимальное время задержки (в секундах).	required
max_seconds	float	Максимальное время задержки (в секундах).	required

async_move_mouse(page, x, y, start=None, steps=30, delay_between_steps=0.01, algorithm='bezier', *, timeout=None) async

Имитирует плавное перемещение мыши Playwright или nodriver.

Parameters:

Name	Type	Description	Default
page	Any	Объект страницы Playwright Page или вкладки nodriver Tab.	required
x	int	Конечная координата X.	required
y	int	Конечная координата Y.	required
start	tuple[int, int] | None	Начальные координаты X, Y. Если не задано, используется (0, 0).	None
steps	int	Количество промежуточных шагов движения (для алгоритма 'bezier').	30
delay_between_steps	float	Задержка между шагами в секундах (для алгоритма 'bezier').	0.01
algorithm	str	Алгоритм генерации траектории ('bezier' или 'windmouse').	'bezier'
timeout	float | None	Максимальное время ожидания операции (в секундах).	None

async_scroll_to(page, x, y, selector=None, steps=10, delay_between_steps=0.01, *, timeout=None) async

Имитирует плавный скроллинг Playwright или nodriver.

Parameters:

Name	Type	Description	Default
page	Any	Объект страницы Playwright Page или вкладки nodriver Tab.	required
x	int	Конечная горизонтальная позиция скролла.	required
y	int	Конечная вертикальная позиция скролла.	required
selector	str | None	Необязательный селектор элемента для скролла.	None
steps	int	Количество промежуточных шагов.	10
delay_between_steps	float	Задержка между шагами в секундах.	0.01
timeout	float | None	Максимальное время ожидания операции (в секундах).	None

async_type_text(page, selector, text, error_rate=0.05, speed_wpm=40.0, key_hold_time=(0.04, 0.09), layout_error_rate=0.0, delayed_fix_rate=0.0, paste_threshold=None, paste_delay_before=(0.4, 1.0), paste_delay_after=(0.3, 0.8), timeout=None) async

Имитирует ввод текста с опечатками Playwright или nodriver.

Поддерживает адаптивный ввод: если длина текста превышает paste_threshold, текст вставляется целиком (имитируя вставку из буфера обмена Ctrl+V / Paste) с естественными паузами обдумывания до и после вставки.

Parameters:

Name	Type	Description	Default
page	Any	Объект страницы Playwright Page или вкладки nodriver Tab.	required
selector	str	Селектор поля ввода.	required
text	str	Текст для ввода.	required
error_rate	float	Вероятность совершения опечатки (0.0 - 1.0).	0.05
speed_wpm	float	Скорость ввода в словах в минуту (WPM).	40.0
key_hold_time	tuple[float, float]	Диапазон задержки удержания клавиши (keyDown -> keyUp) в секундах.	(0.04, 0.09)
layout_error_rate	float	Вероятность ошибки переключения раскладки в начале ввода (0.0 - 1.0).	0.0
delayed_fix_rate	float	Вероятность отложенного исправления опечатки навигацией стрелками (0.0 - 1.0).	0.0
paste_threshold	int | None	Порог длины текста для вставки через буфер обмена. Если None, ввод всегда посимвольный.	None
paste_delay_before	tuple[float, float]	Диапазон паузы обдумывания перед вставкой из буфера (в секундах).	(0.4, 1.0)
paste_delay_after	tuple[float, float]	Диапазон паузы проверки после вставки из буфера (в секундах).	(0.3, 0.8)
timeout	float | None	Таймаут выполнения операции в секундах.	None

click(driver, selector=None, x=None, y=None, start=None, algorithm='windmouse', hold_time=(0.05, 0.12))

Имитирует реалистичный клик мышью Selenium.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required
selector	str | None	CSS-селектор целевого элемента (если x, y не заданы).	None
x	int | None	Конечная координата X.	None
y	int | None	Конечная координата Y.	None
start	tuple[int, int] | None	Начальные координаты курсора.	None
algorithm	str	Алгоритм движения ('windmouse' или 'bezier').	'windmouse'
hold_time	tuple[float, float]	Диапазон задержки удержания кнопки мыши (в секундах).	(0.05, 0.12)

detect_cf_turnstile(tab) async

Обнаруживает присутствие и координаты виджета Cloudflare Turnstile.

Parameters:

Name	Type	Description	Default
tab	Any	Объект вкладки nodriver Tab или Playwright Page.	required

Returns:

Type	Description
dict[str, Any] | None	Словарь с параметрами виджета ('found', 'solved', 'x', 'y', 'width', 'height', 'interactive')
dict[str, Any] | None	либо None, если Turnstile не найден.

get_browser_launch_args(*, no_sandbox=False)

Возвращает расширенный набор аргументов запуска браузера для скрытия автоматизации.

Предотвращает появление инфобаров, системных всплывающих окон Chromium о падениях и некорректном завершении сессий.

Note

Флаг --no-sandbox по умолчанию отключен (False), так как отключение песочницы является первичным триггером для многих систем антифрода (Cloudflare, Google Cloud Armor) и снижает безопасность. Если запуск производится внутри изолированного Docker-контейнера без прав root/SYS_ADMIN, передайте no_sandbox=True.

Флаги --disable-blink-features=AutomationControlled, --use-fake-ui-for-media-stream и подобные намеренно исключены, так как в современных версиях Chromium они вызывают системный инфобар о неподдерживаемых флагах или детектируются антибот-системами. Скрытие navigator.webdriver выполняется через CDP-инъекцию скрипта антидетекта.

Parameters:

Name	Type	Description	Default
no_sandbox	bool	Если True, добавляет флаг --no-sandbox (рекомендуется только для root Docker-контейнеров).	False

Returns:

Type	Description
list[str]	Список аргументов командной строки запуска браузера.

get_client_hints(user_agent=None)

Генерирует словарь согласованных Client Hints (navigator.userAgentData) на основе User-Agent.

Parameters:

Name	Type	Description	Default
user_agent	str | None	Строка User-Agent. Если None, используется стандартный Chrome на Windows.	None

Returns:

Type	Description
dict[str, Any]	Словарь с параметрами Client Hints: platform, mobile, brands.

get_random_search_queries(count=3, category=None)

Возвращает список случайных реалистичных поисковых запросов.

Parameters:

Name	Type	Description	Default
count	int	Количество запрашиваемых поисковых запросов.	3
category	str | None	Необязательная категория ('tech', 'news', 'science', 'lifestyle').	None

Returns:

Type	Description
list[str]	Список строк с поисковыми запросами.

get_search_engine_config(engine='google')

Возвращает конфигурацию для органического поиска в указанной поисковой системе.

Parameters:

Name	Type	Description	Default
engine	str	Имя поисковой системы ('google' или 'yandex').	'google'

Returns:

Type	Description
dict[str, str]	Словарь с параметрами (base_url, search_url, input_selector, submit_selector, organic_selector).

human_sleep(min_seconds, max_seconds)

Синхронно задерживает выполнение на случайное время, имитируя поведение человека.

Parameters:

Name	Type	Description	Default
min_seconds	float	Минимальное время задержки (в секундах).	required
max_seconds	float	Максимальное время задержки (в секундах).	required

is_cf_turnstile_solved(tab) async

Проверяет, решен ли челендж Cloudflare Turnstile в сессии.

Parameters:

Name	Type	Description	Default
tab	Any	Объект вкладки nodriver Tab или Playwright Page.	required

Returns:

Type	Description
bool	True, если в DOM присутствует токен ответа или установлена cookie cf_clearance.

is_organic_url(url, engine='google')

Проверяет, является ли URL органической внешней ссылкой из поисковой выдачи, исключая рекламу, внутренние сервисы поисковика и трекинговые редиректы.

Parameters:

Name	Type	Description	Default
url	str	Проверяемый URL.	required
engine	str	Имя поисковой системы ('google' или 'yandex').	'google'

Returns:

Type	Description
bool	True, если ссылка является валидной органической внешней ссылкой, иначе False.

move_mouse(driver, x, y, start=None, steps=30, delay_between_steps=0.01, algorithm='bezier')

Имитирует плавное перемещение мыши Selenium.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required
x	int	Конечная координата X.	required
y	int	Конечная координата Y.	required
start	tuple[int, int] | None	Начальные координаты X, Y. Если не задано, используется (0, 0).	None
steps	int	Количество промежуточных шагов (для алгоритма 'bezier').	30
delay_between_steps	float	Задержка между шагами в секундах (для алгоритма 'bezier').	0.01
algorithm	str	Алгоритм генерации траектории ('bezier' или 'windmouse').	'bezier'

scroll_to(driver, x, y, selector=None, steps=10, delay_between_steps=0.01)

Имитирует плавный скроллинг Selenium.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required
x	int	Конечная горизонтальная позиция скролла.	required
y	int	Конечная вертикальная позиция скролла.	required
selector	str | None	Необязательный селектор элемента для скролла.	None
steps	int	Количество промежуточных шагов.	10
delay_between_steps	float	Задержка между шагами в секундах.	0.01

solve_cf_turnstile(tab, *, timeout=15.0, check_interval=0.5, click_delay=(0.5, 1.2), click_offset=None, natural_hover=True, raise_on_failure=False) async

Автоматически обнаруживает и решает капчу Cloudflare Turnstile.

Находит интерактивную область чекбокса, выполняет реалистичное наведение курсора мыши по кривой Безье/WindMouse и клик, после чего ожидает получения токена валидации.

Parameters:

Name	Type	Description	Default
tab	Any	Объект вкладки nodriver Tab или Playwright Page.	required
timeout	float	Максимальное время ожидания решения капчи в секундах.	15.0
check_interval	float	Интервал проверки состояния капчи в секундах.	0.5
click_delay	tuple[float, float]	Задержка перед кликом после наведения (min, max).	(0.5, 1.2)
click_offset	tuple[float, float] | None	Пользовательские смещения (offset_x, offset_y) относительно левого верхнего угла виджета. Если None, рассчитываются адаптивно.	None
natural_hover	bool	Если True, моделирует естественный старт движения курсора из случайной точки экрана.	True
raise_on_failure	bool	Если True, при таймауте выбрасывает RuntimeError.	False

Returns:

Type	Description
bool	True, если капча успешно решена, иначе False.

Raises:

Type	Description
RuntimeError	Если raise_on_failure=True и капча не была решена за время таймаута.

type_text(driver, selector, text, error_rate=0.05, speed_wpm=40.0, layout_error_rate=0.0, delayed_fix_rate=0.0, paste_threshold=None, paste_delay_before=(0.4, 1.0), paste_delay_after=(0.3, 0.8))

Имитирует ввод текста с опечатками Selenium.

Поддерживает адаптивный ввод: если длина текста превышает paste_threshold, текст вставляется целиком (Ctrl+V / Paste) с естественными паузами обдумывания.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required
selector	str	CSS-селектор поля ввода.	required
text	str	Текст для ввода.	required
error_rate	float	Вероятность совершения опечатки (0.0 - 1.0).	0.05
speed_wpm	float	Скорость ввода в словах в минуту (WPM).	40.0
layout_error_rate	float	Вероятность ошибки переключения раскладки в начале ввода (0.0 - 1.0).	0.0
delayed_fix_rate	float	Вероятность отложенного исправления опечатки навигацией стрелками (0.0 - 1.0).	0.0
paste_threshold	int | None	Порог длины текста для вставки через буфер обмена. Если None, ввод всегда посимвольный.	None
paste_delay_before	tuple[float, float]	Диапазон паузы обдумывания перед вставкой из буфера (в секундах).	(0.4, 1.0)
paste_delay_after	tuple[float, float]	Диапазон паузы проверки после вставки из буфера (в секундах).	(0.3, 0.8)

options: members:

• BezierCurveGenerator
• JitterDelayGenerator
• KeyboardTypoGenerator
• human_sleep
• async_human_sleep
• move_mouse
• async_move_mouse
• scroll_to
• async_scroll_to
• type_text
• async_type_text
• apply_antidetect_playwright
• apply_antidetect_selenium
• get_browser_launch_args

Модуль scraping.captcha (Решатели капчи)

chutils.scraping.captcha

AntiCaptchaSolver

Bases: BaseCaptchaSolver

Синхронный клиент для Anti-Captcha.

__init__(api_key=None, host='https://api.anti-captcha.com')

Инициализирует AntiCaptchaSolver.

Parameters:

Name	Type	Description	Default
api_key	str | None	Явно заданный API-ключ.	None
host	str	Адрес API-сервиса Anti-Captcha.	'https://api.anti-captcha.com'

solve_image(image_data, timeout=60.0, poll_interval=5.0, **kwargs)

Синхронно решает капчу-изображение.

Parameters:

Name	Type	Description	Default
image_data	bytes | str	Бинарные данные картинки или base64-строка.	required
timeout	float	Максимальное время ожидания решения (в секундах).	60.0
poll_interval	float	Интервал опроса статуса решения (в секундах).	5.0
**kwargs	Any	Дополнительные параметры задачи.	{}

Returns:

Type	Description
str	Распознанный текст с изображения.

solve_recaptcha(sitekey, page_url, timeout=120.0, poll_interval=5.0, **kwargs)

Синхронно решает ReCaptcha v2/v3.

Parameters:

Name	Type	Description	Default
sitekey	str	Ключ рекапчи на целевом сайте.	required
page_url	str	URL страницы, на которой расположена рекапча.	required
timeout	float	Максимальное время ожидания решения (в секундах).	120.0
poll_interval	float	Интервал опроса статуса решения (в секундах).	5.0
**kwargs	Any	Дополнительные параметры задачи.	{}

Returns:

Type	Description
str	Токен ответа рекапчи.

AsyncAntiCaptchaSolver

Bases: BaseAsyncCaptchaSolver

Асинхронный клиент для Anti-Captcha.

__init__(api_key=None, host='https://api.anti-captcha.com')

Инициализирует AsyncAntiCaptchaSolver.

Parameters:

Name	Type	Description	Default
api_key	str | None	Явно заданный API-ключ.	None
host	str	Адрес API-сервиса Anti-Captcha.	'https://api.anti-captcha.com'

solve_image(image_data, timeout=60.0, poll_interval=5.0, **kwargs) async

Асинхронно решает капчу-изображение.

Parameters:

Name	Type	Description	Default
image_data	bytes | str	Бинарные данные картинки или base64-строка.	required
timeout	float	Максимальное время ожидания решения (в секундах).	60.0
poll_interval	float	Интервал опроса статуса решения (в секундах).	5.0
**kwargs	Any	Дополнительные параметры задачи.	{}

Returns:

Type	Description
str	Распознанный текст с изображения.

solve_recaptcha(sitekey, page_url, timeout=120.0, poll_interval=5.0, **kwargs) async

Асинхронно решает ReCaptcha v2/v3.

Parameters:

Name	Type	Description	Default
sitekey	str	Ключ рекапчи на целевом сайте.	required
page_url	str	URL страницы, на которой расположена рекапча.	required
timeout	float	Максимальное время ожидания решения (в секундах).	120.0
poll_interval	float	Интервал опроса статуса решения (в секундах).	5.0
**kwargs	Any	Дополнительные параметры задачи.	{}

Returns:

Type	Description
str	Токен ответа рекапчи.

AsyncCapMonsterSolver

Bases: BaseAsyncCaptchaSolver

Асинхронный клиент для CapMonster Cloud.

__init__(api_key=None, host='https://api.capmonster.cloud')

Инициализирует AsyncCapMonsterSolver.

Parameters:

Name	Type	Description	Default
api_key	str | None	Явно заданный API-ключ.	None
host	str	Адрес API-сервиса CapMonster Cloud.	'https://api.capmonster.cloud'

solve_image(image_data, timeout=60.0, poll_interval=5.0, **kwargs) async

Асинхронно решает капчу-изображение.

Parameters:

Name	Type	Description	Default
image_data	bytes | str	Бинарные данные картинки или base64-строка.	required
timeout	float	Максимальное время ожидания решения (в секундах).	60.0
poll_interval	float	Интервал опроса статуса решения (в секундах).	5.0
**kwargs	Any	Дополнительные параметры задачи.	{}

Returns:

Type	Description
str	Распознанный текст с изображения.

solve_recaptcha(sitekey, page_url, timeout=120.0, poll_interval=5.0, **kwargs) async

Асинхронно решает ReCaptcha v2/v3.

Parameters:

Name	Type	Description	Default
sitekey	str	Ключ рекапчи на целевом сайте.	required
page_url	str	URL страницы, на которой расположена рекапча.	required
timeout	float	Максимальное время ожидания решения (в секундах).	120.0
poll_interval	float	Интервал опроса статуса решения (в секундах).	5.0
**kwargs	Any	Дополнительные параметры задачи.	{}

Returns:

Type	Description
str	Токен ответа рекапчи.

AsyncRuCaptchaSolver

Bases: BaseAsyncCaptchaSolver

Асинхронный клиент для RuCaptcha / 2Captcha.

__init__(api_key=None, host='https://rucaptcha.com')

Инициализирует AsyncRuCaptchaSolver.

Parameters:

Name	Type	Description	Default
api_key	str | None	Явно заданный API-ключ.	None
host	str	Адрес API-сервиса RuCaptcha.	'https://rucaptcha.com'

solve_image(image_data, timeout=60.0, poll_interval=5.0, **kwargs) async

Асинхронно решает капчу-изображение.

Parameters:

Name	Type	Description	Default
image_data	bytes | str	Бинарные данные картинки или base64-строка.	required
timeout	float	Максимальное время ожидания решения (в секундах).	60.0
poll_interval	float	Интервал опроса статуса решения (в секундах).	5.0
**kwargs	Any	Дополнительные параметры задачи.	{}

Returns:

Type	Description
str	Распознанный текст с изображения.

solve_recaptcha(sitekey, page_url, timeout=120.0, poll_interval=5.0, **kwargs) async

Асинхронно решает ReCaptcha v2/v3.

Parameters:

Name	Type	Description	Default
sitekey	str	Ключ рекапчи на целевом сайте.	required
page_url	str	URL страницы, на которой расположена рекапча.	required
timeout	float	Максимальное время ожидания решения (в секундах).	120.0
poll_interval	float	Интервал опроса статуса решения (в секундах).	5.0
**kwargs	Any	Дополнительные параметры задачи.	{}

Returns:

Type	Description
str	Токен ответа рекапчи.

CapMonsterSolver

Bases: BaseCaptchaSolver

Синхронный клиент для CapMonster Cloud.

__init__(api_key=None, host='https://api.capmonster.cloud')

Инициализирует CapMonsterSolver.

Parameters:

Name	Type	Description	Default
api_key	str | None	Явно заданный API-ключ.	None
host	str	Адрес API-сервиса CapMonster Cloud.	'https://api.capmonster.cloud'

solve_image(image_data, timeout=60.0, poll_interval=5.0, **kwargs)

Синхронно решает капчу-изображение.

Parameters:

Name	Type	Description	Default
image_data	bytes | str	Бинарные данные картинки или base64-строка.	required
timeout	float	Максимальное время ожидания решения (в секундах).	60.0
poll_interval	float	Интервал опроса статуса решения (в секундах).	5.0
**kwargs	Any	Дополнительные параметры задачи.	{}

Returns:

Type	Description
str	Распознанный текст с изображения.

solve_recaptcha(sitekey, page_url, timeout=120.0, poll_interval=5.0, **kwargs)

Синхронно решает ReCaptcha v2/v3.

Parameters:

Name	Type	Description	Default
sitekey	str	Ключ рекапчи на целевом сайте.	required
page_url	str	URL страницы, на которой расположена рекапча.	required
timeout	float	Максимальное время ожидания решения (в секундах).	120.0
poll_interval	float	Интервал опроса статуса решения (в секундах).	5.0
**kwargs	Any	Дополнительные параметры задачи.	{}

Returns:

Type	Description
str	Токен ответа рекапчи.

CaptchaBalanceError

Bases: CaptchaError

Ошибка: недостаточный баланс на аккаунте сервиса капчи.

CaptchaError

Bases: ChutilsException

Базовая ошибка при решении капчи.

CaptchaServiceError

Bases: CaptchaError

Ошибка: сервис решения капчи вернул ошибку API (например, неверный ключ, плохие параметры).

CaptchaTimeoutError

Bases: CaptchaError

Ошибка: превышено время ожидания решения капчи.

RuCaptchaSolver

Bases: BaseCaptchaSolver

Синхронный клиент для RuCaptcha / 2Captcha.

__init__(api_key=None, host='https://rucaptcha.com')

Инициализирует RuCaptchaSolver.

Parameters:

Name	Type	Description	Default
api_key	str | None	Явно заданный API-ключ.	None
host	str	Адрес API-сервиса RuCaptcha.	'https://rucaptcha.com'

solve_image(image_data, timeout=60.0, poll_interval=5.0, **kwargs)

Синхронно решает капчу-изображение.

Parameters:

Name	Type	Description	Default
image_data	bytes | str	Бинарные данные картинки или base64-строка.	required
timeout	float	Максимальное время ожидания решения (в секундах).	60.0
poll_interval	float	Интервал опроса статуса решения (в секундах).	5.0
**kwargs	Any	Дополнительные параметры задачи.	{}

Returns:

Type	Description
str	Распознанный текст с изображения.

solve_recaptcha(sitekey, page_url, timeout=120.0, poll_interval=5.0, **kwargs)

Синхронно решает ReCaptcha v2/v3.

Parameters:

Name	Type	Description	Default
sitekey	str	Ключ рекапчи на целевом сайте.	required
page_url	str	URL страницы, на которой расположена рекапча.	required
timeout	float	Максимальное время ожидания решения (в секундах).	120.0
poll_interval	float	Интервал опроса статуса решения (в секундах).	5.0
**kwargs	Any	Дополнительные параметры задачи.	{}

Returns:

Type	Description
str	Токен ответа рекапчи.

options: members:

• RuCaptchaSolver
• AsyncRuCaptchaSolver
• AntiCaptchaSolver
• AsyncAntiCaptchaSolver
• CapMonsterSolver
• AsyncCapMonsterSolver
• CaptchaError
• CaptchaTimeoutError
• CaptchaBalanceError
• CaptchaServiceError

Модуль plugins (Система плагинов)

chutils.plugins

Модуль системы плагинов для chutils. Позволяет расширять провайдеры секретов, конфигураций, метрик и логирования.

registry = PluginRegistry() module-attribute

Глобальный экземпляр реестра

BasePlugin

Bases: ABC

Базовый абстрактный класс для всех плагинов chutils. Каждый плагин должен иметь уникальное имя.

description property

Описание плагина.

Returns:

Type	Description
str	Описание плагина.

name abstractmethod property

Уникальное имя плагина.

Returns:

Type	Description
str	Имя плагина.

version property

Версия плагина.

Returns:

Type	Description
str	Строка с версией плагина.

BrowserStealthPlugin

Bases: BasePlugin

Интерфейс для плагина глубокой маскировки и анонимизации браузера (Anti-Detect Stealth). Позволяет сторонним аддонам (например, chutils-stealth) подключать расширенную защиту от фингерпринтинга (AudioContext, WebRTC, Canvas, Client Hints, Fonts).

apply_nodriver(tab, **kwargs) abstractmethod

Применяет расширенные стелс-патчи к nodriver Tab.

Parameters:

Name	Type	Description	Default
tab	Any	Объект вкладки браузера nodriver.	required
**kwargs	Any	Дополнительные параметры конфигурации маскировки.	{}

apply_playwright(context, **kwargs) abstractmethod

Применяет расширенные стелс-патчи к Playwright BrowserContext или Page.

Parameters:

Name	Type	Description	Default
context	Any	Объект контекста браузера или страницы Playwright.	required
**kwargs	Any	Дополнительные параметры конфигурации маскировки.	{}

apply_selenium(driver, **kwargs) abstractmethod

Применяет расширенные стелс-патчи к Selenium WebDriver.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр драйвера Selenium.	required
**kwargs	Any	Дополнительные параметры конфигурации маскировки.	{}

CaptchaSolverPlugin

Bases: BasePlugin

Интерфейс для плагина решения капч. Позволяет подключать кастомные/сторонние сервисы и ML-модели для капч.

async_solve_recaptcha(sitekey, page_url, timeout=120.0, poll_interval=5.0, **kwargs) async

Асинхронно решает reCAPTCHA. По умолчанию вызывает синхронную версию.

Parameters:

Name	Type	Description	Default
sitekey	str	Ключ сайта reCAPTCHA.	required
page_url	str	URL страницы.	required
timeout	float	Таймаут ожидания решения в секундах.	120.0
poll_interval	float	Интервал опроса статуса решения.	5.0
**kwargs	Any	Дополнительные параметры.	{}

Returns:

Type	Description
str	Строка ответа.

solve_recaptcha(sitekey, page_url, timeout=120.0, poll_interval=5.0, **kwargs) abstractmethod

Решает reCAPTCHA и возвращает g-recaptcha-response токен.

Parameters:

Name	Type	Description	Default
sitekey	str	Ключ сайта reCAPTCHA.	required
page_url	str	URL страницы.	required
timeout	float	Таймаут ожидания решения в секундах.	120.0
poll_interval	float	Интервал опроса статуса решения.	5.0
**kwargs	Any	Дополнительные параметры.	{}

Returns:

Type	Description
str	Строка ответа (g-recaptcha-response).

ConfigProviderPlugin

Bases: BasePlugin, ConfigProvider

Интерфейс для плагина-провайдера конфигураций. Позволяет загружать и сохранять конфигурации из внешних систем (например, Consul, Etcd).

HttpBackendPlugin

Bases: BasePlugin

Интерфейс для плагина кастомного сетевого бэкенда HTTP-клиента. Позволяет подключать альтернативные сетевые движки (например, curl_cffi с TLS/JA3/JA4 impersonation).

create_async_client(**kwargs) abstractmethod

Создает и возвращает асинхронный HTTP-клиент или сессию.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Параметры конфигурации (базовый URL, заголовки, таймауты, impersonate и др.).	{}

Returns:

Type	Description
Any	Экземпляр асинхронного HTTP-клиента.

create_client(**kwargs) abstractmethod

Создает и возвращает синхронный HTTP-клиент или сессию.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Параметры конфигурации (базовый URL, заголовки, таймауты, impersonate и др.).	{}

Returns:

Type	Description
Any	Экземпляр HTTP-клиента.

LoggerHandlerPlugin

Bases: BasePlugin

Интерфейс для плагина-обработчика логов. Позволяет добавлять кастомные logging.Handler в конфигурацию логирования.

get_handler(**kwargs) abstractmethod

Создает и возвращает настроенный экземпляр logging.Handler.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Параметры конфигурации для инициализации хэндлера.	{}

Returns:

Type	Description
Handler	Настроенный объект logging.Handler.

MetricsPlugin

Bases: BasePlugin, MetricsProvider

Интерфейс для плагина-провайдера метрик. Позволяет подключить стороннюю систему сбора метрик (например, Datadog, StatsD).

PluginError

Bases: Exception

Базовое исключение для ошибок системы плагинов.

PluginRegistry

Реестр плагинов chutils. Управляет жизненным циклом, регистрацией и автообнаружением плагинов.

__init__()

Инициализирует PluginRegistry.

clear()

Очистить все зарегистрированные плагины (в основном для тестов).

discover_plugins(group='chutils.plugins')

Автоматическое обнаружение плагинов через Python entry_points. Исключения при загрузке плагина логируются, но не прерывают работу всей системы.

Parameters:

Name	Type	Description	Default
group	str	Имя группы entry points для поиска плагинов.	'chutils.plugins'

get_all_plugins()

Получить список всех зарегистрированных плагинов.

Returns:

Type	Description
list[Any]	Список всех зарегистрированных плагинов.

get_plugin(name)

Получить зарегистрированный плагин по имени.

Parameters:

Name	Type	Description	Default
name	str	Имя плагина.	required

Returns:

Type	Description
Any | None	Экземпляр плагина или None, если он не найден.

get_plugins_by_type(plugin_type)

Получить все плагины, которые являются экземплярами или наследниками указанного типа.

Parameters:

Name	Type	Description	Default
plugin_type	type[Any]	Класс/тип плагина для фильтрации.	required

Returns:

Type	Description
list[Any]	Список плагинов, соответствующих указанному типу.

register(plugin)

Явно зарегистрировать плагин. Плагин должен иметь атрибут name.

Parameters:

Name	Type	Description	Default
plugin	Any	Объект или класс регистрируемого плагина.	required

SecretProviderPlugin

Bases: BasePlugin, SecretProvider

Интерфейс для плагина-провайдера секретов. Позволяет подключить стороннее хранилище секретов (например, AWS Secrets Manager, Vault).

TaskQueuePlugin

Bases: BasePlugin

Интерфейс для плагина очереди задач скрапинга. Позволяет подключать сторонние очереди (например, RabbitMQ, NATS, Kafka).

create_queue(name, **kwargs) abstractmethod

Создает и возвращает экземпляр очереди задач.

Parameters:

Name	Type	Description	Default
name	str	Имя очереди задач.	required
**kwargs	Any	Дополнительные параметры конфигурации очереди.	{}

Returns:

Type	Description
Any	Экземпляр очереди задач.

get_browser_stealth_plugins()

Возвращает список всех зарегистрированных плагинов глубокой маскировки браузера (BrowserStealthPlugin).

Выполняет автообнаружение из групп chutils.plugins.stealth и chutils.plugins.

Returns:

Type	Description
list[Any]	Список экземпляров плагинов маскировки браузера.

get_captcha_solver_plugin(name)

Возвращает зарегистрированный плагин солвера капчи по имени.

Выполняет автообнаружение из группы chutils.plugins.captcha.

Parameters:

Name	Type	Description	Default
name	str	Имя плагина.	required

Returns:

Type	Description
Any | None	Экземпляр плагина или None.

get_http_backend_plugin(name)

Возвращает зарегистрированный плагин HTTP-бэкенда по имени.

Выполняет автообнаружение из групп chutils.plugins.http и chutils.plugins.

Parameters:

Name	Type	Description	Default
name	str	Имя бэкенда (например, 'curl_cffi', 'tls_client').	required

Returns:

Type	Description
Any | None	Экземпляр плагина или None.

get_task_queue_plugin(name)

Возвращает зарегистрированный плагин очереди задач по имени.

Выполняет автообнаружение из группы chutils.plugins.scraping.

Parameters:

Name	Type	Description	Default
name	str	Имя плагина.	required

Returns:

Type	Description
Any | None	Экземпляр плагина или None.

register_plugin(plugin)

Публичная функция для явной регистрации плагина.

Parameters:

Name	Type	Description	Default
plugin	Any	Объект или класс регистрируемого плагина.	required

options: members:

• register_plugin
• registry
• BasePlugin
• SecretProviderPlugin
• ConfigProviderPlugin
• LoggerHandlerPlugin
• MetricsPlugin

Модуль http (HTTP-клиент и отказоустойчивость)

chutils.http

chutils.http — Лёгковесный HTTP-клиент с батареями.

Предоставляет синхронный и асинхронный HTTP-клиенты с встроенной поддержкой отказоустойчивости, трассировки и маскирования секретов.

Основное использование:

from chutils.http import HttpClient, ResiliencePolicy

policy = ResiliencePolicy(retries=3, timeout=10.0)
with HttpClient(base_url="https://api.example.com", policy=policy) as client:
    resp = client.get("/users/1")
    resp.raise_for_status()
    data = resp.json()

Stand-alone функции:

from chutils import http
resp = http.get("https://httpbin.org/get")

Async-использование:

from chutils.http import AsyncHttpClient

async with AsyncHttpClient(base_url="https://api.example.com") as client:
    resp = await client.get("/status")

CURL_CFFI_AVAILABLE = importlib.util.find_spec('curl_cffi') is not None module-attribute

Флаг доступности библиотеки curl-cffi.

DEFAULT_IMPERSONATE_PROFILE = 'chrome120' module-attribute

Профиль браузера по умолчанию для TLS Client Impersonation.

AsyncEventStreamClient

Асинхронный клиент для HTTP Streaming и SSE.

AsyncHttpClient

Асинхронный HTTP-клиент на базе httpx.AsyncClient.

Требует установленного httpx. При его отсутствии вызывает OptionalDependencyError при инициализации.

Parameters:

Name	Type	Description	Default
base_url	str	Базовый URL-префикс для всех запросов.	''
default_headers	dict[str, str] | None	Заголовки по умолчанию.	None
timeout	float | None	Таймаут запросов в секундах.	30.0
policy	ResiliencePolicy | None	Политика отказоустойчивости.	None
sensitive_headers	set[str] | None	Дополнительные заголовки для маскирования.	None

Example

from chutils.http import AsyncHttpClient, ResiliencePolicy

policy = ResiliencePolicy(retries=2, timeout=5.0)
async with AsyncHttpClient(
    base_url="https://api.example.com", policy=policy
) as client:
    resp = await client.get("/status")
    resp.raise_for_status()

__aenter__() async

Поддержка async-контекстного менеджера.

Returns:

Type	Description
Self	Сам экземпляр клиента.

__aexit__(*args) async

Закрывает async-клиент при выходе из контекстного менеджера.

__init__(*, base_url='', default_headers=None, timeout=30.0, policy=None, sensitive_headers=None)

Инициализирует AsyncHttpClient.

Parameters:

Name	Type	Description	Default
base_url	str	Базовый URL для всех запросов.	''
default_headers	dict[str, str] | None	Заголовки по умолчанию.	None
timeout	float | None	Таймаут в секундах.	30.0
policy	ResiliencePolicy | None	Политика отказоустойчивости.	None
sensitive_headers	set[str] | None	Имена заголовков для маскирования.	None

Raises:

Type	Description
OptionalDependencyError	Если httpx не установлен.

aclose() async

Закрывает async-клиент и освобождает ресурсы.

delete(path, *, headers=None, timeout=None) async

Выполняет async DELETE-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

get(path, *, headers=None, timeout=None) async

Выполняет async GET-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

patch(path, *, headers=None, json_data=None, data=None, timeout=None) async

Выполняет async PATCH-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела.	None
data	bytes | str | None	Сырое тело.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

post(path, *, headers=None, json_data=None, data=None, timeout=None) async

Выполняет async POST-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела.	None
data	bytes | str | None	Сырое тело.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

put(path, *, headers=None, json_data=None, data=None, timeout=None) async

Выполняет async PUT-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела.	None
data	bytes | str | None	Сырое тело.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

request(method, path, *, headers=None, json_data=None, data=None, timeout=None) async

Выполняет асинхронный HTTP-запрос.

Parameters:

Name	Type	Description	Default
method	str	HTTP-метод (GET, POST, PUT, DELETE, PATCH).	required
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела.	None
data	bytes | str | None	Сырое тело запроса.	None
timeout	float | None	Таймаут для этого конкретного запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

AsyncWebSocketClient

Асинхронный клиент для WebSockets.

connect() async

Устанавливает асинхронное соединение по WebSocket.

recv() async

Принимает текстовое или бинарное сообщение из WebSocket.

Returns:

Type	Description
str | bytes	Принятое сообщение.

send(message) async

Отправляет текстовое или бинарное сообщение через WebSocket.

Parameters:

Name	Type	Description	Default
message	str | bytes	Сообщение для отправки.	required

EventStreamClient

Синхронный клиент-обертка для HTTP Streaming и SSE.

HttpClient

Синхронный HTTP-клиент с батареями (httpx + fallback на urllib).

При наличии httpx использует его как транспорт. При отсутствии — прозрачно переключается на встроенный urllib.request, выводя единоразовое предупреждение в лог.

Parameters:

Name	Type	Description	Default
base_url	str	Базовый URL-префикс для всех запросов.	''
default_headers	dict[str, str] | None	Заголовки, добавляемые к каждому запросу.	None
timeout	float | None	Таймаут запросов по умолчанию в секундах.	30.0
policy	ResiliencePolicy | None	Политика отказоустойчивости (retry, semaphore и т.д.).	None
sensitive_headers	set[str] | None	Дополнительные заголовки для маскирования в логах.	None

Example

from chutils.http import HttpClient, ResiliencePolicy

policy = ResiliencePolicy(retries=3, timeout=10.0)
with HttpClient(base_url="https://api.example.com", policy=policy) as client:
    resp = client.get("/users/1")
    resp.raise_for_status()
    data = resp.json()

__enter__()

Поддержка контекстного менеджера.

Returns:

Type	Description
Self	Сам экземпляр клиента.

__exit__(*args)

Закрывает клиент при выходе из контекстного менеджера.

__init__(*, base_url='', default_headers=None, timeout=30.0, policy=None, sensitive_headers=None)

Инициализирует HttpClient.

Parameters:

Name	Type	Description	Default
base_url	str	Базовый URL для всех запросов.	''
default_headers	dict[str, str] | None	Заголовки по умолчанию для каждого запроса.	None
timeout	float | None	Таймаут в секундах.	30.0
policy	ResiliencePolicy | None	Политика отказоустойчивости.	None
sensitive_headers	set[str] | None	Имена заголовков для маскирования в логах.	None

close()

Закрывает клиент и освобождает ресурсы.

delete(path, *, headers=None, timeout=None)

Выполняет DELETE-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

get(path, *, headers=None, timeout=None)

Выполняет GET-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

patch(path, *, headers=None, json_data=None, data=None, timeout=None)

Выполняет PATCH-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела.	None
data	bytes | str | None	Сырое тело.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

post(path, *, headers=None, json_data=None, data=None, timeout=None)

Выполняет POST-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела.	None
data	bytes | str | None	Сырое тело.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

put(path, *, headers=None, json_data=None, data=None, timeout=None)

Выполняет PUT-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела.	None
data	bytes | str | None	Сырое тело.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

request(method, path, *, headers=None, json_data=None, data=None, timeout=None)

Выполняет HTTP-запрос.

Parameters:

Name	Type	Description	Default
method	str	HTTP-метод (GET, POST, PUT, DELETE, PATCH).	required
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела запроса.	None
data	bytes | str | None	Сырое тело запроса (bytes или str).	None
timeout	float | None	Таймаут для этого конкретного запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

HttpResponse dataclass

Ответ HTTP-запроса.

Attributes:

Name	Type	Description
status_code	int	HTTP-статус-код ответа.
headers	dict[str, str]	Заголовки ответа.
content	bytes	Тело ответа в байтах.
elapsed	float	Время выполнения запроса в секундах.
url	str	Итоговый URL (с учётом редиректов).

text property

Тело ответа в виде строки UTF-8.

Returns:

Type	Description
str	Декодированное тело ответа.

json()

Десериализует тело ответа как JSON.

Returns:

Type	Description
object	Распарсенный JSON-объект.

Raises:

Type	Description
ValueError	Если тело не является корректным JSON.

raise_for_status()

Вызывает исключение, если статус-код указывает на ошибку (4xx / 5xx).

Raises:

Type	Description
HttpClientError	Если статус-код >= 400.

ResiliencePolicy

Политика отказоустойчивости: retry, timeout, semaphore, circuit breaker.

Применяется к произвольным синхронным (apply_sync) и асинхронным (apply_async) вызовам для обеспечения надёжности.

Attributes:

Name	Type	Description
retries		Количество повторных попыток после первого отказа.
retry_delay		Базовая задержка (сек.) между попытками.
retry_backoff		Множитель задержки для экспоненциального отступа.
retry_jitter		Добавлять ли случайный шум к задержке.
retry_exceptions		Кортеж классов исключений, при которых выполняется повтор.
retry_on_status_codes		Набор HTTP-статус-кодов, при которых выполняется повтор.
timeout		Максимальное время выполнения вызова (сек.); None — без ограничения.
max_concurrency		Максимальное число одновременных вызовов; None — без ограничения.
cb_failure_threshold		Порог отказов для размыкания Circuit Breaker.
cb_recovery_timeout		Время (сек.) до попытки восстановления Circuit Breaker.

Example

policy = ResiliencePolicy(retries=3, timeout=5.0, max_concurrency=10)
result = policy.apply_sync(requests.get, url)

__init__(*, retries=3, retry_delay=0.5, retry_backoff=2.0, retry_jitter=False, retry_exceptions=(Exception,), retry_on_status_codes=(429, 500, 502, 503, 504), timeout=None, max_concurrency=None, cb_failure_threshold=5, cb_recovery_timeout=30.0)

Инициализирует политику отказоустойчивости.

Parameters:

Name	Type	Description	Default
retries	int	Количество повторных попыток после первого отказа.	3
retry_delay	float	Базовая задержка между попытками в секундах.	0.5
retry_backoff	float	Множитель задержки для экспоненциального отступа.	2.0
retry_jitter	bool	Если True, добавляет случайный шум к задержке.	False
retry_exceptions	tuple[type[Exception], ...]	Кортеж классов исключений, при которых выполняется retry.	(Exception,)
retry_on_status_codes	tuple[int, ...]	HTTP-статус-коды для retry (используется с extractor).	(429, 500, 502, 503, 504)
timeout	float | None	Максимальное время выполнения вызова в секундах.	None
max_concurrency	int | None	Максимальное число одновременных вызовов.	None
cb_failure_threshold	int	Порог отказов для открытия Circuit Breaker.	5
cb_recovery_timeout	float	Пауза перед попыткой восстановления Circuit Breaker.	30.0

apply_async(func, *args, http_error_extractor=None, **kwargs) async

Применяет политику к асинхронному вызову.

Оборачивает await func(*args, **kwargs) в retry, timeout и semaphore.

Parameters:

Name	Type	Description	Default
func	Callable[..., object]	Асинхронный вызываемый объект (coroutine function).	required
*args	object	Позиционные аргументы для func.	()
http_error_extractor	Callable[[Exception], int] | None	Опциональная функция для извлечения HTTP-статус-кода из пойманного исключения.	None
**kwargs	object	Именованные аргументы для func.	{}

Returns:

Type	Description
object	Результат await func(*args, **kwargs).

Raises:

Type	Description
ChutilsTimeoutError	При превышении timeout.
CircuitBreakerOpenError	Если Circuit Breaker разомкнут.
Exception	Последнее перехваченное исключение после исчерпания retry.

apply_sync(func, *args, http_error_extractor=None, **kwargs)

Применяет политику к синхронному вызову.

Оборачивает func(*args, **kwargs) в retry, timeout и semaphore.

Parameters:

Name	Type	Description	Default
func	Callable[..., object]	Вызываемый объект.	required
*args	object	Позиционные аргументы для func.	()
http_error_extractor	Callable[[Exception], int] | None	Опциональная функция для извлечения HTTP-статус-кода из пойманного исключения. Используется для retry по retry_on_status_codes.	None
**kwargs	object	Именованные аргументы для func.	{}

Returns:

Type	Description
object	Результат func(*args, **kwargs).

Raises:

Type	Description
ChutilsTimeoutError	При превышении timeout.
CircuitBreakerOpenError	Если Circuit Breaker разомкнут.
Exception	Последнее перехваченное исключение после исчерпания retry.

ServerSentEvent dataclass

Представляет собой отдельное событие Server-Sent Events (SSE).

TLSAsyncClient

Асинхронный HTTP-клиент с поддержкой TLS/HTTP2 Client Impersonation (curl-cffi).

__init__(impersonate=DEFAULT_IMPERSONATE_PROFILE, proxy=None, proxy_pool=None, fallback_to_standard=False, timeout=30.0, **kwargs)

Инициализирует TLSAsyncClient.

Parameters:

Name	Type	Description	Default
impersonate	str	Профиль маскировки браузера (напр. 'chrome120', 'safari17_0').	DEFAULT_IMPERSONATE_PROFILE
proxy	ProxyConfig | str | None	Прокси-сервер (ProxyConfig или строка).	None
proxy_pool	ProxyPool | None	Пул прокси chutils.	None
fallback_to_standard	bool	Флаг автоматического отката на AsyncHttpClient при отсутствии curl-cffi.	False
timeout	float	Таймаут запросов в секундах.	30.0
**kwargs	Any	Дополнительные параметры конфигурации.	{}

Raises:

Type	Description
OptionalDependencyError	Если curl-cffi отсутствует и fallback_to_standard=False.

aclose() async

Закрывает асинхронную сессию.

close() async

Псевдоним для aclose.

delete(url, **kwargs) async

Выполняет асинхронный DELETE запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

from_browser_session(target, impersonate=DEFAULT_IMPERSONATE_PROFILE, **kwargs) async classmethod

Создает асинхронный клиент TLSAsyncClient, предзаполненный cookies и User-Agent из браузера.

Parameters:

Name	Type	Description	Default
target	Any	Экземпляр Playwright (Page, Context), Nodriver Tab или Selenium WebDriver.	required
impersonate	str	Профиль маскировки браузера.	DEFAULT_IMPERSONATE_PROFILE
**kwargs	Any	Дополнительные параметры для TLSAsyncClient.	{}

Returns:

Type	Description
Self	Экземпляр TLSAsyncClient.

get(url, **kwargs) async

Выполняет асинхронный GET запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

patch(url, **kwargs) async

Выполняет асинхронный PATCH запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

post(url, **kwargs) async

Выполняет асинхронный POST запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

put(url, **kwargs) async

Выполняет асинхронный PUT запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

request(method, url, **kwargs) async

Выполняет асинхронный HTTP-запрос.

Parameters:

Name	Type	Description	Default
method	str	HTTP метод (GET, POST, etc.).	required
url	str	Целевой URL.	required
**kwargs	Any	Параметры запроса (headers, params, data, json, timeout).	{}

Returns:

Type	Description
HttpResponse	Унифицированный объект ответа HttpResponse.

TLSSession

Синхронный HTTP-клиент с поддержкой TLS/HTTP2 Client Impersonation (curl-cffi).

__init__(impersonate=DEFAULT_IMPERSONATE_PROFILE, proxy=None, proxy_pool=None, fallback_to_standard=False, timeout=30.0, **kwargs)

Инициализирует TLSSession.

Parameters:

Name	Type	Description	Default
impersonate	str	Профиль маскировки браузера (напр. 'chrome120', 'safari17_0').	DEFAULT_IMPERSONATE_PROFILE
proxy	ProxyConfig | str | None	Прокси-сервер (ProxyConfig или строка).	None
proxy_pool	ProxyPool | None	Пул прокси chutils.	None
fallback_to_standard	bool	Флаг автоматического отката на HttpClient при отсутствии curl-cffi.	False
timeout	float	Таймаут запросов в секундах.	30.0
**kwargs	Any	Дополнительные параметры конфигурации.	{}

Raises:

Type	Description
OptionalDependencyError	Если curl-cffi отсутствует и fallback_to_standard=False.

close()

Закрывает базовую сессию.

delete(url, **kwargs)

Выполняет DELETE запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

from_browser_session(target, impersonate=DEFAULT_IMPERSONATE_PROFILE, **kwargs) classmethod

Создает сессию TLSSession, предзаполненную cookies и User-Agent из браузера.

Parameters:

Name	Type	Description	Default
target	Any	Экземпляр Selenium WebDriver.	required
impersonate	str	Профиль маскировки браузера.	DEFAULT_IMPERSONATE_PROFILE
**kwargs	Any	Дополнительные параметры для TLSSession.	{}

Returns:

Type	Description
Self	Экземпляр TLSSession.

get(url, **kwargs)

Выполняет GET запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

patch(url, **kwargs)

Выполняет PATCH запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

post(url, **kwargs)

Выполняет POST запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

put(url, **kwargs)

Выполняет PUT запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

request(method, url, **kwargs)

Выполняет синхронный HTTP-запрос.

Parameters:

Name	Type	Description	Default
method	str	HTTP метод (GET, POST, etc.).	required
url	str	Целевой URL.	required
**kwargs	Any	Параметры запроса (headers, params, data, json, timeout).	{}

Returns:

Type	Description
HttpResponse	Унифицированный объект ответа HttpResponse.

UrllibFallbackClient

Синхронный HTTP-клиент на базе urllib.request.

Используется как fallback, когда httpx не доступен. Поддерживает интеграцию с ResiliencePolicy для retry, timeout и semaphore.

Parameters:

Name	Type	Description	Default
base_url	str	Базовый URL, который будет префиксом для всех запросов.	''
default_headers	dict[str, str] | None	Заголовки по умолчанию для всех запросов.	None
timeout	float | None	Таймаут подключения и чтения в секундах.	30.0
policy	ResiliencePolicy | None	Политика отказоустойчивости.	None
sensitive_headers	set[str] | None	Дополнительные заголовки для маскирования в логах.	None

Example

client = UrllibFallbackClient(
    base_url="https://api.example.com",
    default_headers={"Authorization": "Bearer token"},
    timeout=10.0,
)
response = client.get("/users/1")
response.raise_for_status()
data = response.json()

__enter__()

Поддержка контекстного менеджера.

Returns:

Type	Description
Self	Сам экземпляр клиента.

__exit__(*args)

Закрывает клиент при выходе из контекстного менеджера.

__init__(*, base_url='', default_headers=None, timeout=30.0, policy=None, sensitive_headers=None)

Инициализирует fallback HTTP-клиент.

Parameters:

Name	Type	Description	Default
base_url	str	Базовый URL для всех запросов.	''
default_headers	dict[str, str] | None	Заголовки, добавляемые к каждому запросу.	None
timeout	float | None	Таймаут в секундах (подключение + чтение).	30.0
policy	ResiliencePolicy | None	Политика отказоустойчивости (retry, semaphore и т.д.).	None
sensitive_headers	set[str] | None	Дополнительные имена заголовков для маскирования.	None

close()

Закрывает клиент (no-op для urllib-клиента, для совместимости API).

delete(path, *, headers=None, timeout=None)

Выполняет DELETE-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

get(path, *, headers=None, timeout=None)

Выполняет GET-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

patch(path, *, headers=None, json_data=None, data=None, timeout=None)

Выполняет PATCH-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела запроса.	None
data	bytes | str | None	Сырое тело запроса.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

post(path, *, headers=None, json_data=None, data=None, timeout=None)

Выполняет POST-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела запроса.	None
data	bytes | str | None	Сырое тело запроса.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

put(path, *, headers=None, json_data=None, data=None, timeout=None)

Выполняет PUT-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела запроса.	None
data	bytes | str | None	Сырое тело запроса.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

request(method, path, *, headers=None, json_data=None, data=None, timeout=None)

Выполняет HTTP-запрос с заданным методом.

Parameters:

Name	Type	Description	Default
method	str	HTTP-метод (GET, POST, PUT, DELETE, PATCH).	required
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки запроса.	None
json_data	object | None	Данные для сериализации в JSON-тело запроса.	None
data	bytes | str | None	Сырое тело запроса (bytes или str).	None
timeout	float | None	Таймаут для этого конкретного запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

Raises:

Type	Description
HttpClientError	При сетевой ошибке.
ValueError	Если переданы одновременно json_data и data.

WebSocketClient

Синхронный клиент-обертка для WebSockets.

connect()

Устанавливает синхронное соединение по WebSocket.

recv()

Принимает текстовое или бинарное сообщение из WebSocket.

Returns:

Type	Description
str | bytes	Принятое сообщение.

send(message)

Отправляет текстовое или бинарное сообщение через WebSocket.

Parameters:

Name	Type	Description	Default
message	str | bytes	Сообщение для отправки.	required

create_curl_async_session(impersonate, proxy=None, **kwargs)

Создает асинхронную сессию curl_cffi с заданным профилем impersonate.

Parameters:

Name	Type	Description	Default
impersonate	str	Имя профиля браузера (например, 'chrome120').	required
proxy	str | None	URL прокси-сервера.	None
**kwargs	Any	Дополнительные параметры для AsyncSession.	{}

Returns:

Type	Description
Any	Экземпляр curl_cffi.requests.AsyncSession.

create_curl_session(impersonate, proxy=None, **kwargs)

Создает синхронную сессию curl_cffi с заданным профилем impersonate.

Parameters:

Name	Type	Description	Default
impersonate	str	Имя профиля браузера (например, 'chrome120').	required
proxy	str | None	URL прокси-сервера.	None
**kwargs	Any	Дополнительные параметры для Session.	{}

Returns:

Type	Description
Any	Экземпляр curl_cffi.requests.Session.

create_http_span(method, url, tracer_name='chutils.http')

Создаёт OTEL-спан для исходящего HTTP-запроса.

Если OpenTelemetry не установлен, возвращает None.

Parameters:

Name	Type	Description	Default
method	str	HTTP-метод (GET, POST и т.д.).	required
url	str	Полный URL запроса.	required
tracer_name	str	Имя трейсера (используется для группировки спанов).	'chutils.http'

Returns:

Type	Description
object | None	Контекстный менеджер спана или None, если OTEL недоступен.

Example

from chutils.http.tracing import create_http_span

span = create_http_span("GET", "https://api.example.com/users")
if span is not None:
    with span:
        response = requests.get(url)

delete(url, *, headers=None, timeout=None, policy=None)

Выполняет DELETE-запрос.

Parameters:

Name	Type	Description	Default
url	str	Абсолютный URL запроса.	required
headers	dict[str, str] | None	Дополнительные HTTP-заголовки.	None
timeout	float | None	Таймаут запроса в секундах.	None
policy	ResiliencePolicy | None	Политика отказоустойчивости.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

get(url, *, headers=None, timeout=None, policy=None)

Выполняет GET-запрос.

Создаёт временный HttpClient, выполняет запрос и возвращает ответ.

Parameters:

Name	Type	Description	Default
url	str	Абсолютный URL запроса.	required
headers	dict[str, str] | None	Дополнительные HTTP-заголовки.	None
timeout	float | None	Таймаут запроса в секундах.	None
policy	ResiliencePolicy | None	Политика отказоустойчивости (retry, timeout, semaphore).	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse с телом, заголовками и статус-кодом ответа.

Example

from chutils import http

resp = http.get("https://httpbin.org/get", timeout=5.0)
resp.raise_for_status()
data = resp.json()

inject_trace_headers(headers)

Инжектирует W3C Trace Context заголовки в словарь заголовков запроса.

Если OpenTelemetry не установлен или трассировка не настроена, возвращает заголовки без изменений.

Инжектируемые заголовки: - traceparent: идентификаторы trace и span (формат W3C). - tracestate: дополнительное состояние вендора (опционально).

Parameters:

Name	Type	Description	Default
headers	dict[str, str]	Исходный словарь HTTP-заголовков запроса.	required

Returns:

Type	Description
dict[str, str]	Обновлённый словарь с добавленными заголовками трассировки
dict[str, str]	(или оригинальный, если OTEL недоступен).

Example

from chutils.http.tracing import inject_trace_headers

headers = {"Authorization": "Bearer token"}
headers = inject_trace_headers(headers)
# headers теперь содержит "traceparent" если OTEL активен

patch(url, *, headers=None, json_data=None, data=None, timeout=None, policy=None)

Выполняет PATCH-запрос.

Parameters:

Name	Type	Description	Default
url	str	Абсолютный URL запроса.	required
headers	dict[str, str] | None	Дополнительные HTTP-заголовки.	None
json_data	object | None	Данные для JSON-тела запроса.	None
data	bytes | str | None	Сырое тело запроса.	None
timeout	float | None	Таймаут запроса в секундах.	None
policy	ResiliencePolicy | None	Политика отказоустойчивости.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

post(url, *, headers=None, json_data=None, data=None, timeout=None, policy=None)

Выполняет POST-запрос.

Parameters:

Name	Type	Description	Default
url	str	Абсолютный URL запроса.	required
headers	dict[str, str] | None	Дополнительные HTTP-заголовки.	None
json_data	object | None	Данные для сериализации в JSON-тело запроса.	None
data	bytes | str | None	Сырое тело запроса (bytes или str).	None
timeout	float | None	Таймаут запроса в секундах.	None
policy	ResiliencePolicy | None	Политика отказоустойчивости.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

Example

resp = http.post(
    "https://api.example.com/users",
    json_data={"name": "Alice", "email": "alice@example.com"},
)
resp.raise_for_status()

put(url, *, headers=None, json_data=None, data=None, timeout=None, policy=None)

Выполняет PUT-запрос.

Parameters:

Name	Type	Description	Default
url	str	Абсолютный URL запроса.	required
headers	dict[str, str] | None	Дополнительные HTTP-заголовки.	None
json_data	object | None	Данные для JSON-тела запроса.	None
data	bytes | str | None	Сырое тело запроса.	None
timeout	float | None	Таймаут запроса в секундах.	None
policy	ResiliencePolicy | None	Политика отказоустойчивости.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

options: members:

• HttpClient
• AsyncHttpClient
• ResiliencePolicy
• HttpResponse
• get
• post
• put
• delete
• patch

Модуль dev (Инструменты разработчика и Live Dev)

chutils.dev

Инструменты разработчика для анализа кодовой базы и генерации контекста.

AI_MANIFEST_FILENAMES = ['GEMINI.md', 'gemini.md', 'antigravity.md', 'ANTIGRAVITY.md', 'agents.md', 'AGENTS.md', '.cursorrules', '.windsurfrules'] module-attribute

Список поддерживаемых AI-манифестов.

BaseRunner

Bases: ABC

Абстрактный базовый класс ранера для управления перезапуском приложений.

is_running property

Возвращает флаг состояния ранера.

restart()

Выполняет перезапуск (остановка -> запуск).

start() abstractmethod

Запускает процесс или целевую функцию.

stop() abstractmethod

Останавливает процесс или целевую функцию.

BaseWatcher

Bases: ABC

Абстрактный базовый класс для отслеживания изменений файлов.

Parameters:

Name	Type	Description	Default
paths	str | list[str]	Директория или список директорий/файлов для отслеживания.	required
extensions	list[str] | None	Список расширений файлов без точки (например, ["py", "json"]).	None
ignore_patterns	list[str] | None	Список шаблонов путей/имен для игнорирования (fnmatch).	None
debounce_seconds	float	Задержка пакетирования событий перезапуска в секундах.	0.5
callback	Callable[[list[str]], None] | None	Функция-коллбек, вызываемая при изменении файлов. Принимает список путей.	None

is_running property

Возвращает статус запуска вотчера.

start() abstractmethod

Запускает отслеживание файлов.

stop() abstractmethod

Останавливает отслеживание файлов.

CleanItem dataclass

Элемент, предназначенный для очистки.

display_size property

Возвращает человекочитаемый размер элемента.

InProcessReloader

Bases: BaseRunner

Ранер для внутрипроцессного перезапуска указанной функции с вызовом очистки lifecycle.

Parameters:

Name	Type	Description	Default
target	str	Строка формата "path.to.module:func_name".	required
args	tuple[object, ...] | None	Опциональные позиционные аргументы функции.	None
kwargs	dict[str, object] | None	Опциональные именованные аргументы функции.	None

restart()

Выполняет остановку, перезагружает модуль и снова вызывает функцию.

start()

Вызывает целевую функцию в текущем процессе.

stop()

Вызывает глобальную очистку коллбеков через trigger_cleanup().

LintResult

Представляет результат одной проверки правила (Fallback версия без Pydantic).

__init__(rule_name, message, severity, file_path=None, line_number=None, fix_suggestion=None)

Инициализирует fallback-результат проверки правила.

Parameters:

Name	Type	Description	Default
rule_name	str	Название правила.	required
message	str	Сообщение об ошибке/предупреждении.	required
severity	str	Критичность проблемы.	required
file_path	str | None	Опциональный путь к файлу.	None
line_number	int | None	Номер строки.	None
fix_suggestion	str | None	Рекомендация по исправлению.	None

LinterEngine

Движок линтера, координирующий сбор файлов, загрузку правил и их выполнение.

__init__(config)

Инициализирует движок с переданной конфигурацией.

Parameters:

Name	Type	Description	Default
config	dict[str, str | bool | list[str] | None]	Словарь настроек линтера.	required

collect_all_files()

Собирает абсолютно все неигнорируемые файлы в проекте.

Returns:

Type	Description
list[str]	Список абсолютных путей к файлам.

collect_files()

Собирает все неигнорируемые файлы в проекте (учитывая флаг staged).

Returns:

Type	Description
list[str]	Список абсолютных путей к файлам.

collect_staged_files()

Собирает список измененных и добавленных файлов, подготовленных к коммиту (staged) в Git.

Returns:

Type	Description
list[str]	Список абсолютных путей к файлам.

load_rules()

Загружает правила (встроенные и кастомные).

print_results(results)

Выводит результаты работы линтера в консоль и возвращает статус завершения.

Parameters:

Name	Type	Description	Default
results	list[LintResult]	Список результатов.	required

Returns:

Type	Description
bool	True, если проверка успешна (нет критических ошибок в строгом режиме/обычном),
bool	False в противном случае.

run()

Запускает все включенные правила на собранных файлах.

Returns:

Type	Description
list[LintResult]	Список результатов проверок с найденными ошибками и предупреждениями.

should_ignore(path)

Проверяет, должен ли данный путь быть проигнорирован.

Parameters:

Name	Type	Description	Default
path	Path	Проверяемый путь.	required

Returns:

Type	Description
bool	True, если путь соответствует какому-либо шаблону игнорирования.

MockServerRunner

Управляющий класс для мок-сервера.

__init__(port=8888, routes_path='mocks.yml', proxy_fallback=None)

Инициализирует MockServerRunner.

Parameters:

Name	Type	Description	Default
port	int	Порт, на котором будет запущен мок-сервер.	8888
routes_path	str	Путь к YAML-файлу с описанием роутов.	'mocks.yml'
proxy_fallback	str | None	URL реального бэкенда для проксирования неизвестных роутов.	None

check_reload()

Проверяет время изменения файла на диске и перезагружает при необходимости.

init_template(output_path)

Создает шаблонный файл конфигурации роутов.

Parameters:

Name	Type	Description	Default
output_path	str	Путь к файлу для сохранения шаблона.	required

load_config()

Загружает роуты из файла (YAML или JSON).

log_event(message)

Выводит отформатированное лог-сообщение в консоль.

Parameters:

Name	Type	Description	Default
message	str	Текст лог-сообщения.	required

run()

Запускает многопоточный HTTP-сервер.

stop()

Останавливает запущенный HTTP-сервер.

PollingWatcher

Bases: BaseWatcher

Вотчер на базе периодического сканирования файловой системы (Fallback mode).

Parameters:

Name	Type	Description	Default
paths	str | list[str]	Директория или список директорий/файлов для отслеживания.	required
extensions	list[str] | None	Список расширений файлов без точки.	None
ignore_patterns	list[str] | None	Шаблоны путей для игнорирования.	None
debounce_seconds	float	Задержка дебаунса.	0.5
poll_interval	float	Интервал между опросами файлов в секундах.	1.0
callback	Callable[[list[str]], None] | None	Коллбек для отправки списка изменившихся файлов.	None

start()

Запускает фоновый поток опроса файловой системы.

stop()

Останавливает фоновый опрос файлов.

Rule

Абстрактный базовый класс для всех правил линтера.

Каждое правило должно переопределить метод check() и задать атрибуты name, description и severity.

Подавление срабатываний инлайн (inline suppress)

Любое срабатывание правила можно подавить без изменения правил, добавив комментарий в конец проблемной строки или в строку непосредственно перед ней::

import logging  # chutils: ignore[ChutilsIntegrationRule]
code()         # chutils: ignore[RuleA, RuleB]
# chutils: ignore[ChutilsIntegrationRule]
some_call()

Для подавления всех правил сразу используйте all::

code()  # chutils: ignore[all]

Правила не должны сами проверять инлайн-комментарии: фильтрация выполняется автоматически в LinterEngine.run().

check(base_dir, files)

Выполняет проверку правила по списку файлов.

Parameters:

Name	Type	Description	Default
base_dir	str	Путь к корню проверяемого проекта.	required
files	list[str]	Список абсолютных путей к файлам проекта.	required

Returns:

Type	Description
list[LintResult]	Список объектов LintResult с найденными проблемами.

Note

Подавить срабатывания отдельного срабатывания можно инлайн-комментарием # chutils: ignore[<name>] — без изменения правила.

SubprocessRunner

Bases: BaseRunner

Ранер для запуска и управления внешним дочерним процессом.

Parameters:

Name	Type	Description	Default
command	str | list[str]	Команда для выполнения (строка или список аргументов).	required
graceful_timeout	float	Время ожидания в секундах перед принудительным завершением (kill).	3.0
cwd	str | None	Рабочая директория для дочернего процесса.	None

process property

Возвращает текущий экземпляр Popen.

start()

Запускает внешнюю команду через subprocess.Popen.

stop()

Мягко останавливает процесс (SIGTERM/SIGINT), затем вызывает kill() при необходимости.

WatchdogWatcher

Bases: BaseWatcher

Вотчер на базе библиотеки watchdog.

Parameters:

Name	Type	Description	Default
paths	str | list[str]	Директория или список директорий/файлов для отслеживания.	required
extensions	list[str] | None	Список расширений файлов без точки.	None
ignore_patterns	list[str] | None	Шаблоны путей для игнорирования.	None
debounce_seconds	float	Задержка дебаунса.	0.5
callback	Callable[[list[str]], None] | None	Коллбек для отправки списка изменившихся файлов.	None

start()

Запускает Observer библиотеки watchdog.

stop()

Останавливает Observer библиотеки watchdog.

collect_context_slice(project_path, modules=None, task=None, layer='public')

Собирает контекстный срез по заданным параметрам.

Parameters:

Name	Type	Description	Default
project_path	Path	Путь к корню проекта.	required
modules	list[str] | None	Список выбранных модулей.	None
task	str | None	Описание задачи.	None
layer	str	Слой абстракции для фильтрации символов.	'public'

Returns:

Type	Description
str	Сгенерированный Markdown с контекстом.

execute_clean(items)

Удаляет найденные мусорные элементы.

Parameters:

Name	Type	Description	Default
items	list[CleanItem]	Список элементов CleanItem для удаления.	required

Returns:

Type	Description
tuple[int, int]	Кортеж (количество удаленных элементов, суммарно освобожденный размер в байтах).

generate_few_shot_bank(project_path, *, force=False, console=None)

Генерирует банк few-shot примеров для целевого проекта.

Анализирует архитектуру проекта, детектирует ключевые абстракции (Use Cases, репозитории, логгеры, исключения, DI-контейнеры) и создаёт параметризованные шаблоны docs/ai_examples/ в корне целевого проекта.

Parameters:

Name	Type	Description	Default
project_path	str	Путь к корневой директории целевого проекта.	required
force	bool	Если True, существующие категории будут перезаписаны.	False
console	_ConsoleProtocol | None	Объект Rich Console для вывода статуса (опционально).	None

Returns:

Type	Description
GenerationResult	GenerationResult с детализацией созданных и пропущенных категорий.

Raises:

Type	Description
FileNotFoundError	Если project_path не существует.
ValueError	При нарушении path traversal защиты.

generate_workflow_yaml(python_versions, with_pytest, with_mypy, with_ruff, with_ai_lint)

Генерирует валидный YAML-конфиг для GitHub Actions на основе setup-uv.

Parameters:

Name	Type	Description	Default
python_versions	list[str]	Список версий Python для матрицы тестирования.	required
with_pytest	bool	Запускать ли тесты с pytest.	required
with_mypy	bool	Запускать ли статический анализ типов с mypy.	required
with_ruff	bool	Запускать ли линтинг кода с ruff.	required
with_ai_lint	bool	Запускать ли аудит готовности к AI с chutils dev ai-lint.	required

Returns:

Type	Description
str	Строка с содержимым YAML-файла.

get_watcher(paths, extensions=None, ignore_patterns=None, debounce_seconds=0.5, poll_interval=1.0, callback=None)

Фабричная функция для создания наилучшего доступного файлового вотчера.

Использует WatchdogWatcher, если установлена библиотека watchdog, иначе выводит предупреждение в лог и использует PollingWatcher.

Parameters:

Name	Type	Description	Default
paths	str | list[str]	Путь или список путей для отслеживания.	required
extensions	list[str] | None	Расширения файлов для отслеживания.	None
ignore_patterns	list[str] | None	Шаблоны для игнорирования.	None
debounce_seconds	float	Таймаут пакетирования событий.	0.5
poll_interval	float	Интервал опроса для PollingWatcher.	1.0
callback	Callable[[list[str]], None] | None	Коллбек при изменении файлов.	None

Returns:

Type	Description
BaseWatcher	Экземпляр BaseWatcher (WatchdogWatcher или PollingWatcher).

run_interactive_menu(project_path)

Запускает красивое интерактивное CLI-меню для выбора модулей.

Parameters:

Name	Type	Description	Default
project_path	Path	Путь к корню проекта.	required

Returns:

Type	Description
list[str]	Список выбранных пользователем модулей.

scan_project(base_dir, excludes=None, default_targets=None, extra_targets=None)

Сканирует проект и возвращает список найденных временных файлов и папок.

Parameters:

Name	Type	Description	Default
base_dir	str | Path	Корневая директория проекта.	required
excludes	list[str] | None	Список папок или шаблонов для исключения из обхода.	None
default_targets	list[str] | None	Базовый список шаблонов временных файлов/папок.	None
extra_targets	list[str] | None	Дополнительные шаблоны для очистки.	None

Returns:

Type	Description
list[CleanItem]	Список объектов CleanItem.

options: members:

• BaseWatcher
• PollingWatcher
• WatchdogWatcher
• get_watcher
• BaseRunner
• SubprocessRunner
• InProcessReloader
• LinterEngine
• MockServerRunner

Модуль scraping.concurrency (Умная очередь задач и воркеры)

chutils.scraping.concurrency

Модуль chutils.scraping.concurrency: Умная очередь задач, распределение нагрузки и воркеры.

BaseTaskQueue

Bases: ABC

Абстрактная очередь задач скрапинга.

clear() abstractmethod async

Очищает очередь и сбрасывает историю дедупликации.

complete(task) abstractmethod async

Помечает задачу как успешно выполненную.

Parameters:

Name	Type	Description	Default
task	ScrapingTask	Выполненная задача.	required

fail(task, error) abstractmethod async

Обрабатывает ошибку выполнения задачи.

Parameters:

Name	Type	Description	Default
task	ScrapingTask	Сбойная задача.	required
error	str	Текст ошибки.	required

pop() abstractmethod async

Извлекает задачу с наибольшим приоритетом из очереди.

Returns:

Type	Description
ScrapingTask | None	Экземпляр ScrapingTask или None, если очередь пуста.

push(task) abstractmethod async

Добавляет задачу в очередь.

Parameters:

Name	Type	Description	Default
task	ScrapingTask	Задача для добавления.	required

Returns:

Type	Description
bool	True, если задача добавлена; False, если задача дедуплицирована.

size() abstractmethod async

Возвращает количество элементов в очереди.

Returns:

Type	Description
int	Размер очереди.

DomainRateLimiter

Ограничитель частоты запросов и параллельных соединений с привязкой к доменам.

__init__(default_delay=1.0, domain_rules=None, max_domain_concurrency=None)

Инициализирует лимитер.

Parameters:

Name	Type	Description	Default
default_delay	float	Задержка по умолчанию между запросами к одному домену (в секундах).	1.0
domain_rules	dict[str, float] | None	Кастомные задержки по маскам хостов (напр., {"*.wikipedia.org": 2.0}).	None
max_domain_concurrency	dict[str, int] | None	Максимальное количество одновременных подключений к домену.	None

acquire(url) async

Запрашивает разрешение на отправку запроса к указанному URL.

При необходимости выполняет задержку.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required

get_domain(url)

Извлекает домен в нижнем регистре из URL.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required

Returns:

Type	Description
str	Имя хоста (домена).

get_rule_key_and_delay(domain)

Возвращает ключ группы правил и соответствующую задержку.

Parameters:

Name	Type	Description	Default
domain	str	Имя домена.	required

Returns:

Type	Description
tuple[str, float]	Кортеж (ключ_правила, задержка).

release(url)

Освобождает слот подключения после завершения запроса.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required

IdleBrowserReaper

Bases: Generic[T]

Сторожевой таймер неактивности (Watchdog) для пула браузеров и воркеров с поддержкой Scale-to-Zero.

Отслеживает время последнего использования (last_active_time) активных воркеров/браузеров и автоматически инициирует корректное завершение простаивающих процессов для освобождения RAM. Поддерживает двухуровневый таймаут: 1. idle_timeout_seconds — для избыточных инстансов (когда активно >1). 2. scale_to_zero_seconds — для закрытия последнего оставшегося инстанса при полном бездействии.

check_interval_seconds property

Интервал фоновой проверки.

config property

Текущая конфигурация сторожевого таймера.

enabled property

Включена ли очистка простаивающих ресурсов.

idle_timeout_seconds property

Таймаут простоя избыточных инстансов.

is_running property

Запущен ли фоновый мониторинг.

scale_to_zero_seconds property

Таймаут полного Scale-to-Zero.

__aenter__() async

Асинхронный контекстный менеджер для автоматического старта.

__aexit__(exc_type, exc_val, exc_tb) async

Асинхронный контекстный менеджер для автоматической остановки.

__init__(close_worker_fn, is_worker_busy_fn, get_active_workers_fn, get_last_used_fn, config=None, *, idle_timeout_seconds=None, scale_to_zero_seconds=None, check_interval_seconds=None, enabled=None)

Инициализирует сборщик простаивающих воркеров.

Parameters:

Name	Type	Description	Default
close_worker_fn	Callable[[T], Awaitable[None] | None]	Функция (синхронная или асинхронная) корректного закрытия воркера.	required
is_worker_busy_fn	Callable[[T], bool]	Функция проверки, выполняет ли воркер в данный момент задачу.	required
get_active_workers_fn	Callable[[], list[T]]	Функция получения списка идентификаторов запущенных воркеров.	required
get_last_used_fn	Callable[[T], float]	Функция получения timestamp последнего использования воркера.	required
config	IdleReaperConfig | None	Экземпляр IdleReaperConfig с готовыми настройками.	None
idle_timeout_seconds	float | None	Таймаут неактивности для избыточных инстансов (переопределяет config).	None
scale_to_zero_seconds	float | None	Таймаут неактивности для Scale-to-Zero (переопределяет config).	None
check_interval_seconds	float | None	Периодичность проверки в секундах (переопределяет config).	None
enabled	bool | None	Флаг включения очистки (переопределяет config).	None

configure(config=None, *, idle_timeout_seconds=None, scale_to_zero_seconds=None, check_interval_seconds=None, enabled=None)

Динамически обновляет настройки сторожевого таймера на лету.

Parameters:

Name	Type	Description	Default
config	IdleReaperConfig | None	Новый базовый объект конфигурации.	None
idle_timeout_seconds	float | None	Таймаут неактивности для завершения избыточных инстансов.	None
scale_to_zero_seconds	float | None	Таймаут полного простоя до закрытия последнего инстанса.	None
check_interval_seconds	float | None	Интервал регулярной проверки.	None
enabled	bool | None	Флаг активности таймера.	None

from_config(close_worker_fn, is_worker_busy_fn, get_active_workers_fn, get_last_used_fn, config=None, config_section='reaper', **overrides) classmethod

Создает экземпляр с автоматическим чтением параметров из конфигурации chutils.

Parameters:

Name	Type	Description	Default
close_worker_fn	Callable[[T], Awaitable[None] | None]	Функция закрытия инстанса воркера/браузера.	required
is_worker_busy_fn	Callable[[T], bool]	Функция проверки занятости воркера выполнением задачи.	required
get_active_workers_fn	Callable[[], list[T]]	Функция получения списка всех активных воркеров.	required
get_last_used_fn	Callable[[T], float]	Функция получения timestamp последнего использования воркера.	required
config	IdleReaperConfig | None	Готовый объект конфигурации.	None
config_section	str	Название секции в файле настроек.	'reaper'
**overrides	Any	Переопределения отдельных параметров конфигурации.	{}

Returns:

Type	Description
IdleBrowserReaper[T]	Инициализированный экземпляр IdleBrowserReaper.

reap() async

Выполняет одну итерацию проверки и закрывает простаивающие браузеры.

Returns:

Type	Description
int	Количество закрытых экземпляров браузеров / воркеров.

start()

Запускает фоновую задачу периодической очистки, если она еще не запущена.

stop() async

Останавливает фоновую задачу мониторинга.

IdleReaperConfig

Bases: BaseModel

Декларативная конфигурация сторожевого таймера неактивности и Scale-to-Zero.

from_settings(section='reaper', config_dict=None, **overrides) classmethod

Загружает параметры из секции конфигурации chutils или переданного словаря.

Parameters:

Name	Type	Description	Default
section	str	Имя секции конфигурационного файла (по умолчанию 'reaper').	'reaper'
config_dict	dict[str, Any] | None	Явный словарь настроек. Если None, данные извлекаются через chutils.config.	None
**overrides	Any	Точечные переопределения параметров.	{}

Returns:

Type	Description
IdleReaperConfig	Экземпляр IdleReaperConfig.

preset_aggressive() classmethod

Агрессивный пресет для экономии RAM: сброс избыточных за 30с, Scale-to-Zero за 60с.

Returns:

Type	Description
IdleReaperConfig	Экземпляр IdleReaperConfig с агрессивными параметрами.

preset_keep_warm() classmethod

Пресет с удержанием 1 постоянного прогретого инстанса (Scale-to-Zero отключен).

Returns:

Type	Description
IdleReaperConfig	Экземпляр IdleReaperConfig с отключенным Scale-to-Zero.

preset_relaxed() classmethod

Щадящий пресет для интерактивной работы: сброс избыточных за 5 мин, Scale-to-Zero за 15 мин.

Returns:

Type	Description
IdleReaperConfig	Экземпляр IdleReaperConfig с умеренными параметрами.

InMemoryTaskQueue

Bases: BaseTaskQueue

Быстрая очередь задач в оперативной памяти.

clear() async

Очищает очередь и сбрасывает историю дедупликации.

complete(task) async

Помечает задачу как выполненную.

Parameters:

Name	Type	Description	Default
task	ScrapingTask	Выполненная задача.	required

fail(task, error) async

Обрабатывает ошибку выполнения задачи.

Parameters:

Name	Type	Description	Default
task	ScrapingTask	Сбойная задача.	required
error	str	Сообщение об ошибке.	required

pop() async

Извлекает задачу с наивысшим приоритетом из очереди.

Returns:

Type	Description
ScrapingTask | None	Экземпляр ScrapingTask или None, если очередь пуста.

push(task) async

Добавляет задачу в оперативную очередь.

Parameters:

Name	Type	Description	Default
task	ScrapingTask	Задача для добавления.	required

Returns:

Type	Description
bool	True, если задача успешно добавлена; False, если задача дедуплицирована.

size() async

Возвращает количество ожидающих задач в очереди.

Returns:

Type	Description
int	Размер очереди.

PersistentTaskQueue

Bases: BaseTaskQueue

Очередь задач с персистентным сохранением состояния в SQLite.

clear() async

Удаляет все записи очередей и истории дедупликации из БД.

close() async

Освобождает ресурсы и закрывает подключение к SQLite.

complete(task) async

Обновляет статус задачи в БД на 'completed'.

Parameters:

Name	Type	Description	Default
task	ScrapingTask	Выполненная задача.	required

fail(task, error) async

Обновляет количество попыток и статус сбойной задачи в БД.

Parameters:

Name	Type	Description	Default
task	ScrapingTask	Сбойная задача.	required
error	str	Текст ошибки.	required

pop() async

Извлекает следующую ожидающую задачу из базы данных SQLite.

Returns:

Type	Description
ScrapingTask | None	Экземпляр ScrapingTask или None, если очередь пуста.

push(task) async

Сохраняет задачу в базы данных SQLite.

Parameters:

Name	Type	Description	Default
task	ScrapingTask	Задача для сохранения.	required

Returns:

Type	Description
bool	True, если задача сохранена; False, если задача дедуплицирована.

size() async

Подсчитывает количество ожидающих задач в БД.

Returns:

Type	Description
int	Количество задач со статусом 'pending'.

RedisTaskQueue

Bases: BaseTaskQueue

Распределенная очередь задач на базе Redis.

clear() async

Удаляет ключи очереди из Redis.

complete(task) async

Удаляет данные выполненной задачи из Redis.

Parameters:

Name	Type	Description	Default
task	ScrapingTask	Выполненная задача.	required

fail(task, error) async

Обрабатывает ошибку задачи и помещает ее обратно при наличии попыток.

Parameters:

Name	Type	Description	Default
task	ScrapingTask	Сбойная задача.	required
error	str	Сообщение об ошибке.	required

pop() async

Извлекает наивысшую по приоритету задачу из Redis.

Returns:

Type	Description
ScrapingTask | None	Экземпляр ScrapingTask или None, если очередь пуста.

push(task) async

Добавляет задачу в структуру Redis ZSET.

Parameters:

Name	Type	Description	Default
task	ScrapingTask	Задача для добавления.	required

Returns:

Type	Description
bool	True, если задача добавлена; False, если задача дедуплицирована.

size() async

Возвращает количество элементов в очереди Redis.

Returns:

Type	Description
int	Число элементов.

ScrapingTask dataclass

Модель задачи скрапинга.

Attributes:

Name	Type	Description
url	str	Целевой URL.
priority	int	Числовой приоритет (чем выше, тем раньше выполняется).
payload	dict[str, Any]	Произвольный словарь пользовательских данных.
attempts	int	Количество предпринятых попыток выполнения.
max_attempts	int	Максимально допустимое количество попыток.
task_id	str	Уникальный идентификатор задачи.
dedup_key	str	Ключ для дедупликации (по умолчанию совпадает с url).
created_at	float	Временная метка создания задачи.
last_error	str | None	Сообщение о последней возникшей ошибке.

WorkerPool

Управляющий пул воркеров с поддержкой асинхронных и синхронных обработчиков.

completed_count property

Количество успешно выполненных задач.

failed_count property

Количество проваленных задач.

__init__(queue, handler, limiter=None, max_workers=5, retry_backoff=2.0)

Инициализирует пул воркеров.

Parameters:

Name	Type	Description	Default
queue	BaseTaskQueue	Очередь задач скрапинга.	required
handler	Callable[[ScrapingTask], Any]	Синхронная или асинхронная функция-обработчик задач.	required
limiter	DomainRateLimiter | None	Опциональный DomainRateLimiter для контроля нагрузки.	None
max_workers	int	Количество параллельных воркеров.	5
retry_backoff	float	Коэффициент повторного вызова (backoff).	2.0

run_until_complete(poll_interval=0.05) async

Запускает пул и выполняет задачи до полного опустошения очереди.

Parameters:

Name	Type	Description	Default
poll_interval	float	Интервал проверки состояния очереди в секундах.	0.05

start() async

Запускает фоновые задачи воркеров.

stop() async

Останавливает все воркеры.

options: members:

• ScrapingTask
• BaseTaskQueue
• InMemoryTaskQueue
• PersistentTaskQueue
• RedisTaskQueue
• DomainRateLimiter
• WorkerPool
• IdleBrowserReaper
• IdleBrowserReaperConfig
• IdleReaper
• IdleReaperConfig

Модуль qt (Интеграция PyQt6 / PySide6)

chutils.qt

Модуль chutils.qt: Интеграция PyQt6/PySide6 (логирование, асинхронность, базовые виджеты, типизированные сигналы).

AutoBindMixin

Миксин для автоматического подключения сигналов в init.

BaseDialog

Bases: QDialog if QtWidgets is not None else object

Базовый диалог с логированием жизненного цикла.

__init__(*args, **kwargs)

Инициализирует базовый диалог.

closeEvent(event)

Обработчик события закрытия диалога.

Parameters:

Name	Type	Description	Default
event	Any	QCloseEvent.	required

showEvent(event)

Обработчик события отображения диалога.

Parameters:

Name	Type	Description	Default
event	Any	QShowEvent.	required

BaseMainWindow

Bases: QMainWindow if QtWidgets is not None else object

Базовое главное окно с встроенным логированием и сохранением геометрии.

__init__(*args, **kwargs)

Инициализирует базовое главное окно.

closeEvent(event)

Обработчик события закрытия окна.

Parameters:

Name	Type	Description	Default
event	Any	QCloseEvent.	required

restore_geometry_settings(key='geometry')

Восстанавливает размеры и положение окна из QSettings.

Parameters:

Name	Type	Description	Default
key	str	Ключ настройки.	'geometry'

save_geometry_settings(key='geometry')

Сохраняет размеры и положение окна в QSettings.

Parameters:

Name	Type	Description	Default
key	str	Ключ настройки.	'geometry'

showEvent(event)

Обработчик события отображения окна.

Parameters:

Name	Type	Description	Default
event	Any	QShowEvent.	required

BoundTypedSignal

Bases: Generic[P]

Связанный типизированный сигнал Qt с точной типизацией connect и emit.

__init__(raw_signal)

Инициализирует связанный сигнал.

Parameters:

Name	Type	Description	Default
raw_signal	Any	Нативный сигнал PyQt6 / PySide6.	required

connect(slot)

Подключает слот к сигналу.

Parameters:

Name	Type	Description	Default
slot	Callable[P, Any]	Функция-обработчик сигналов.	required

Returns:

Type	Description
Any	Результат выполнения вызова connect.

disconnect(slot=None)

Отключает слот от сигнала.

Parameters:

Name	Type	Description	Default
slot	Callable[P, Any] | None	Опциональная функция-обработчик.	None

Returns:

Type	Description
Any	Результат выполнения вызова disconnect.

emit(*args, **kwargs)

Излучает сигнал с переданными аргументами.

Parameters:

Name	Type	Description	Default
*args	args	Позиционные аргументы.	()
**kwargs	kwargs	Именованные аргументы.	{}

QtAsyncWorker

Bases: QThread if QtCore is not None else object

QThread для фонового выполнения асинхронных корутин или тяжелых синхронных функций.

__init__(target, *args, **kwargs)

Инициализирует воркер.

Parameters:

Name	Type	Description	Default
target	Callable[..., Coroutine[Any, Any, T] | T]	Асинхронная корутина или синхронная функция для выполнения.	required
*args	Any	Позиционные аргументы.	()
**kwargs	Any	Именованные аргументы.	{}

run()

Основной метод потока QThread.

start(priority=None)

Запускает выполнение потока.

Parameters:

Name	Type	Description	Default
priority	Any	Приоритет потока Qt.	None

QtLogHandler

Bases: Handler

Обработчик логов, транслирующий сообщения в Qt сигналы.

__init__(level=logging.NOTSET)

Инициализирует обработчик логов.

Parameters:

Name	Type	Description	Default
level	int	Уровень логирования.	NOTSET

emit(record)

Отправляет форматированное сообщение лога в сигнал Qt.

Parameters:

Name	Type	Description	Default
record	LogRecord	Запись лога.	required

TypedSignal

Bases: Generic[P]

Дескриптор типизированного сигнала для Qt классов.

__init__(*types)

Инициализирует типизированный сигнал.

Parameters:

Name	Type	Description	Default
*types	type	Типы передаваемых сигналом аргументов.	()

async_to_qt(on_success=None, on_error=None)

Декоратор для автоматического запуска асинхронной функции в фоновом потоке Qt.

Parameters:

Name	Type	Description	Default
on_success	Callable[[Any], None] | None	Коллбэк для успешного результата.	None
on_error	Callable[[Exception], None] | None	Коллбэк для ошибки.	None

Returns:

Type	Description
Callable[[Callable[..., Coroutine[Any, Any, T] | T]], Callable[..., QtAsyncWorker]]	Декорированная функция, возвращающая QtAsyncWorker.

bind_qt_signals(instance, bind_by_signature=False)

Автоматически связывает сигналы объекта со слотами по соглашению об именовании on_<signal_name>.

Parameters:

Name	Type	Description	Default
instance	Any	Экземпляр QObject или любого класса с сигналами и слотами.	required
bind_by_signature	bool	Включить ли экспериментальное связывание по совпадению типов.	False

Returns:

Type	Description
int	Количество успешно подключенных сигналов.

qt_slot(*types, catch_exceptions=True, logger_name=None)

Декоратор для безопасных слотов Qt с автоматическим логированием ошибок.

Parameters:

Name	Type	Description	Default
*types	type	Типы аргументов слота Qt.	()
catch_exceptions	bool	Перехватывать ли исключения.	True
logger_name	str | None	Имя логгера для фиксации ошибок.	None

Returns:

Type	Description
Callable[[Callable[P, T]], Callable[P, T | None]]	Декорированная функция-слот.

remove_qt_logging(handler, logger_name=None)

Удаляет QtLogHandler из chutils.logger и стандартного logging.

Parameters:

Name	Type	Description	Default
handler	QtLogHandler	Обработчик QtLogHandler для удаления.	required
logger_name	str | None	Имя конкретного логгера или None для глобального удаления.	None

require_qt()

Проверяет наличие установленной библиотеки Qt (PyQt6 или PySide6).

Raises:

Type	Description
OptionalDependencyError	Если ни PyQt6, ни PySide6 не установлены.

run_async_task(target, *args, on_success=None, on_error=None, **kwargs)

Запускает функцию или корутину в фоновом потоке QThread без блокировки UI.

Parameters:

Name	Type	Description	Default
target	Callable[..., Coroutine[Any, Any, T] | T]	Корутина или синхронная функция.	required
*args	Any	Аргументы функции.	()
on_success	Callable[[T], None] | None	Слот/коллбэк при успешном завершении задачи.	None
on_error	Callable[[Exception], None] | None	Слот/коллбэк при обработке исключения.	None
**kwargs	Any	Именованные аргументы функции.	{}

Returns:

Type	Description
QtAsyncWorker	Экземпляр запущенного QtAsyncWorker.

setup_qt_logging(widget=None, level=logging.INFO, formatter=None, logger_name=None)

Быстро подключает вывод логов к Qt виджету или сигналу.

Parameters:

Name	Type	Description	Default
widget	Any	Виджет Qt (QPlainTextEdit, QTextEdit, QStatusBar, QLabel) или слот-функция.	None
level	int	Уровень логирования.	INFO
formatter	Formatter | None	Кастомный форматировщик логов.	None
logger_name	str | None	Имя логгера (None для корневого логгера).	None

Returns:

Type	Description
QtLogHandler	Экземпляр QtLogHandler.

options: members:

• QT_BINDING
• require_qt
• QtLogHandler
• setup_qt_logging
• remove_qt_logging
• QtAsyncWorker
• run_async_task
• async_to_qt
• BaseMainWindow
• BaseDialog
• TypedSignal
• BoundTypedSignal
• qt_slot
• bind_qt_signals
• AutoBindMixin

Модуль telegram (Интеграция с Telegram)

chutils.telegram

AccessListManager

Менеджер белых и черных списков пользователей Telegram.

__init__(storage_path=None, allowed_ids=None, allowed_usernames=None, blocked_ids=None, blocked_usernames=None)

Инициализирует AccessListManager.

Parameters:

Name	Type	Description	Default
storage_path	str | Path | None	Опциональный путь к JSON-файлу для автосохранения списков.	None
allowed_ids	list[int] | None	Начальный белый список Telegram ID.	None
allowed_usernames	list[str] | None	Начальный белый список юзернеймов.	None
blocked_ids	list[int] | None	Начальный черный список Telegram ID.	None
blocked_usernames	list[str] | None	Начальный черный список юзернеймов.	None

allow_user(user_id_or_username)

Добавляет пользователя в белый список и убирает из черного.

Parameters:

Name	Type	Description	Default
user_id_or_username	int | str	ID пользователя Telegram или его юзернейм.	required

block_user(user_id_or_username)

Добавляет пользователя в черный список и убирает из белого.

Parameters:

Name	Type	Description	Default
user_id_or_username	int | str	ID пользователя Telegram или его юзернейм.	required

is_user_allowed(user_id=None, username=None)

Проверяет разрешения для пользователя.

Parameters:

Name	Type	Description	Default
user_id	int | None	Telegram ID пользователя.	None
username	str | None	Username пользователя.	None

Returns:

Type	Description
bool	True, если пользователь имеет доступ, иначе False.

load()

Загружает списки из JSON-файла.

remove_user(user_id_or_username)

Удаляет пользователя из белого и черного списков.

Parameters:

Name	Type	Description	Default
user_id_or_username	int | str	ID пользователя Telegram или его юзернейм.	required

save()

Атомарно сохраняет списки в JSON-файл.

AdminFilter

Bases: BaseFilter

Фильтр проверки прав администратора для aiogram 3.x.

Пример использования

@router.message(AdminFilter(admin_ids=[12345678])) async def admin_cmd(message: Message): await message.answer("Привет, админ!")

__call__(event, **kwargs) async

Проверяет, отправлено ли событие (Message/CallbackQuery) администратором.

Parameters:

Name	Type	Description	Default
event	Any	Объект Telegram Update / Message / CallbackQuery из aiogram.	required
**kwargs	Any	Дополнительные контекстные данные.	{}

Returns:

Type	Description
bool	True, если пользователь является администратором.

HealthCheckAlertBridge

Мост отправки Telegram-уведомлений при изменении статусов здоровья chutils.diagnostics.

on_health_check(service_name, status, details=None)

Обрабатывает событие проверки здоровья и отправляет алерт при проблемах.

Parameters:

Name	Type	Description	Default
service_name	str	Имя сервиса/компонента.	required
status	str	Статус (HEALTHY, DEGRADED, UNHEALTHY).	required
details	dict[str, Any] | None	Подробности ошибки или метрики.	None

Returns:

Type	Description
bool	True, если алерт был отправлен, иначе False.

PaginatorKeyboard

Управляющий класс пагинации динамических Inline-клавиатур.

total_pages property

Возвращает общее количество страниц.

__init__(items, per_page=5, callback_prefix='page')

Инициализирует PaginatorKeyboard.

Parameters:

Name	Type	Description	Default
items	Sequence[Any]	Полный список элементов.	required
per_page	int	Количество элементов на странице (по умолчанию 5).	5
callback_prefix	str	Префикс callback_data для навигации.	'page'

build_keyboard(page=1, item_button_factory=None, footer_buttons=None, buttons_per_row=1, as_aiogram=False)

Строит готовую клавиатуру со срезом элементов и пагинационной панелью.

Parameters:

Name	Type	Description	Default
page	int	Номер запрашиваемой страницы.	1
item_button_factory	Any	Опциональная функция приведения элемента к ButtonSpec.	None
footer_buttons	Sequence[ButtonSpec] | None	Дополнительные кнопки под панелью пагинации.	None
buttons_per_row	int	Ряды элементов страницы.	1
as_aiogram	bool	Возвращать ли aiogram InlineKeyboardMarkup.	False

Returns:

Type	Description
Any	Готовая клавиатура.

get_page_items(page=1)

Возвращает срез элементов для указанной страницы (1-indexed).

Parameters:

Name	Type	Description	Default
page	int	Номер страницы (1..total_pages).	1

Returns:

Type	Description
list[Any]	Список элементов текущей страницы.

SecretUserFilter

Bases: BaseFilter

Фильтр белых и черных списков пользователей для aiogram 3.x.

__call__(event, **kwargs) async

Проверяет разрешения пользователя на основе списков.

Parameters:

Name	Type	Description	Default
event	Any	Входящее событие Telegram (Message, CallbackQuery).	required
**kwargs	Any	Контекстные данные.	{}

Returns:

Type	Description
bool	True, если доступ разрешен.

TelegramLogHandler

Bases: Handler

Handler стандартного модуля logging для отправки критических логов в Telegram.

add_flapping_filter(patterns, threshold=3, failure_timeout=60.0)

Добавляет фильтр подавления кратковременных транзиентных ошибок (флаппинга).

Сообщения об ошибках, совпадающие с patterns, будут отсекаться до тех пор, пока количество последовательных сбоев не достигнет threshold или время сбоя не превысит failure_timeout.

Parameters:

Name	Type	Description	Default
patterns	str | Pattern[str] | Sequence[str | Pattern[str]]	Шаблоны ошибок (подстрока, регулярное выражение или список таковых).	required
threshold	int	Порог последовательных ошибок до отправки алерта в Telegram.	3
failure_timeout	float	Таймаут сбоя в секундах до отправки алерта.	60.0

Returns:

Type	Description
TelegramLogHandler	Текущий экземпляр обработчика.

emit(record)

Отправляет отформатированную запись лога в Telegram.

Parameters:

Name	Type	Description	Default
record	LogRecord	Запись лога logging.LogRecord.	required

TelegramLoggingMiddleware

Bases: BaseMiddleware

Middleware контекстного логирования и измерений времени выполнения для aiogram 3.x.

__call__(handler, event, data) async

Обрабатывает события и логирует контекст в цепочке Middleware.

Parameters:

Name	Type	Description	Default
handler	Callable[[Any, dict[str, Any]], Any]	Следующий хэндлер в цепочке.	required
event	Any	Входящее событие Telegram.	required
data	dict[str, Any]	Контекстные данные события.	required

Returns:

Type	Description
Any	Результат выполнения хэндлера.

TelegramRateLimiter

Движок ограничений вызовов (Rate Limiter) для Telegram-ботов.

__init__(rate=1, per=1.0)

Инициализирует TelegramRateLimiter.

Parameters:

Name	Type	Description	Default
rate	int	Максимальное количество допустимых вызовов.	1
per	float	Период времени в секундах.	1.0

check_rate_limit(key)

Проверяет превышение лимита вызовов для ключа.

Parameters:

Name	Type	Description	Default
key	str	Уникальный идентификатор сущности (user_id / chat_id).	required

Returns:

Type	Description
tuple[bool, float]	Кортеж (is_limited, wait_sec), где is_limited - флаг превышения, wait_sec - секунд до разблокировки.

TelegramThrottlingMiddleware

Bases: BaseMiddleware

Middleware отслеживания и предотвращения спама (Throttling) для aiogram 3.x.

__call__(handler, event, data) async

Обрабатывает входящее событие в цепочке Middleware.

Parameters:

Name	Type	Description	Default
handler	Callable[[Any, dict[str, Any]], Any]	Следующий хэндлер в цепочке.	required
event	Any	Входящее событие Telegram.	required
data	dict[str, Any]	Контекстные данные события.	required

Returns:

Type	Description
Any	Результат выполнения хэндлера.

trace_telegram_update

Контекстный менеджер и декоратор трейсинга и логирования Telegram-апдейтов.

__call__(func)

Оборачивает функцию декоратором трейсинга.

Parameters:

Name	Type	Description	Default
func	F	Целевая функция.	required

Returns:

Type	Description
F	Обернутая функция.

__init__(event=None, logger_instance=None)

Инициализирует trace_telegram_update.

Parameters:

Name	Type	Description	Default
event	Any	Входящее событие/апдейт Telegram.	None
logger_instance	Any	Опциональный кастомный логгер.	None

admin_only(admin_ids=None, admin_usernames=None, is_admin_func=None, refusal_text='⛔ Доступ запрещен: требуется статус администратора', silent=False, raise_on_denied=False)

Декоратор для ограничения доступа к синхронным и асинхронным хэндлерам Telegram-ботов.

Parameters:

Name	Type	Description	Default
admin_ids	list[int] | None	Разрешенные Telegram ID.	None
admin_usernames	list[str] | None	Разрешенные юзернеймы.	None
is_admin_func	Callable[[int | None, str | None], bool] | None	Кастомный предикат проверки.	None
refusal_text	str | None	Текст сообщения при отказе в доступе.	'⛔ Доступ запрещен: требуется статус администратора'
silent	bool	Если True, тихо игнорировать неавторизованные запросы.	False
raise_on_denied	bool	Если True, выбрасывать TelegramAccessDeniedError.	False

Returns:

Type	Description
Callable[[F], F]	Обернутый хэндлер.

allowed_only(manager=None, allowed_ids=None, allowed_usernames=None, blocked_ids=None, blocked_usernames=None, refusal_text='⛔ У вас нет доступа к этой функции', silent=False, raise_on_denied=False)

Декоратор ограничения доступа по белым и черным спискам.

Parameters:

Name	Type	Description	Default
manager	AccessListManager | None	Готовый экземпляр AccessListManager.	None
allowed_ids	list[int] | None	Белый список Telegram ID.	None
allowed_usernames	list[str] | None	Белый список юзернеймов.	None
blocked_ids	list[int] | None	Черный список Telegram ID.	None
blocked_usernames	list[str] | None	Черный список юзернеймов.	None
refusal_text	str | None	Сообщение об отказе.	'⛔ У вас нет доступа к этой функции'
silent	bool	Если True, отбрасывать запросы без вывода ответа.	False
raise_on_denied	bool	Если True, выбрасывать TelegramAccessDeniedError.	False

Returns:

Type	Description
Callable[[F], F]	Обернутая функция.

build_inline_keyboard(buttons, buttons_per_row=2, as_aiogram=False)

Создает сетку Inline-клавиатуры Telegram из списка кнопок.

Parameters:

Name	Type	Description	Default
buttons	Sequence[ButtonSpec]	Список спецификаций кнопок (кортежи или словари).	required
buttons_per_row	int	Количество кнопок в одном ряду (по умолчанию 2).	2
as_aiogram	bool	Если True, возвращает aiogram InlineKeyboardMarkup (при наличии aiogram).	False

Returns:

Type	Description
Any	Словарь вида {'inline_keyboard': [...]} или aiogram InlineKeyboardMarkup.

download_user_file(bot, file_id, target_dir, custom_filename=None, allow_unsafe_path=False, max_size_bytes=None) async

Безопасно выкачивает файл из Telegram по file_id в указанную директорию target_dir.

Parameters:

Name	Type	Description	Default
bot	Any	Экземпляр бота (aiogram.Bot или аналогичный с методом get_file/download_file) или bot_token (str).	required
file_id	str	Уникальный идентификатор файла в Telegram API.	required
target_dir	str | Path	Целевая папка для сохранения.	required
custom_filename	str | None	Желаемое имя файла. Если не указано, используется имя из Telegram или file_id.	None
allow_unsafe_path	bool	Если True, отключает строгую проверку Path Traversal (записывается предупреждение).	False
max_size_bytes	int | None	Максимальный допустимый размер файла в байтах.	None

Returns:

Type	Description
Path	Абсолютный путь (Path) к сохраненному файлу.

Raises:

Type	Description
PathTraversalError	При попытке выхода за границы target_dir (когда allow_unsafe_path=False).
ChutilsException	При превышении max_size_bytes или ошибке загрузки.

escape_html(text)

Экранирует специальные символы в тексте для парс-режима HTML в Telegram.

Parameters:

Name	Type	Description	Default
text	str	Исходный текст.	required

Returns:

Type	Description
str	Экранированный HTML текст.

escape_markdown(text, version=2)

Экранирует специальные символы в тексте для парс-режима Markdown в Telegram.

Parameters:

Name	Type	Description	Default
text	str	Исходный текст.	required
version	int	Версия синтаксиса Markdown (1 или 2, по умолчанию: 2).	2

Returns:

Type	Description
str	Экранированный текст.

is_admin(user_id=None, username=None, admin_ids=None, admin_usernames=None, is_admin_func=None)

Проверяет, является ли пользователь администратором.

Если явные списки admin_ids / admin_usernames не заданы, считывает их из конфигурации chutils (секция 'Telegram', ключи 'admin_ids' / 'admin_usernames').

Parameters:

Name	Type	Description	Default
user_id	int | None	Telegram ID пользователя.	None
username	str | None	Telegram username пользователя.	None
admin_ids	list[int] | None	Список разрешенных Telegram ID администраторов.	None
admin_usernames	list[str] | None	Список разрешенных username администраторов.	None
is_admin_func	Callable[[int | None, str | None], bool] | None	Кастомный предикат проверки.	None

Returns:

Type	Description
bool	True, если пользователь является администратором, иначе False.

send_alert(title, message, bot_token=None, chat_id=None, level='ERROR')

Отправляет кастомное алерты-уведомление администраторам в Telegram.

Parameters:

Name	Type	Description	Default
title	str	Заголовок алерта.	required
message	str	Текст сообщения.	required
bot_token	str | None	Опциональный токен бота.	None
chat_id	int | str | None	Опциональный ID чата администратора.	None
level	str	Уровень алерта (INFO, WARNING, ERROR, CRITICAL).	'ERROR'

Returns:

Type	Description
bool	True при успешной отправке, иначе False.

send_telegram_file(bot, chat_id, file_path, caption=None, parse_mode=None, allow_unsafe_path=False, base_dir=None) async

Безопасно отправляет файл или папку (с авто-упаковкой в ZIP) в Telegram.

Parameters:

Name	Type	Description	Default
bot	Any	Экземпляр бота (aiogram.Bot) или raw bot_token (str).	required
chat_id	int | str	Идентификатор чата или получателя.	required
file_path	str | Path	Путь к отправляемому файлу или директории.	required
caption	str | None	Опциональная подпись к файлу (автоматически обрезается под 1024 символа).	None
parse_mode	str | None	Режим разметки подписи ('HTML', 'MarkdownV2', etc.).	None
allow_unsafe_path	bool	Если True, отключает проверку Path Traversal.	False
base_dir	str | Path | None	Базовая директория для проверки выхода за границы.	None

Returns:

Type	Description
Any	Объект отправленного сообщения Telegram API.

Raises:

Type	Description
PathTraversalError	Если файл находится за пределами base_dir.
ChutilsException	При превышении лимита 50 МБ или ошибках отправки.

smart_truncate(text, max_length=4096, suffix='...')

Безопасно обрезает текст до max_length с закрытием кодовых блоков (```).

Parameters:

Name	Type	Description	Default
text	str	Исходный текст сообщения.	required
max_length	int	Максимальная допустимая длина (по умолчанию 4096).	4096
suffix	str	Суффикс для обрезанного сообщения.	'...'

Returns:

Type	Description
str	Обрезанный валидный текст.

split_message(text, max_length=4096, mode='line')

Разбивает длинный текст на список валидных сообщений не превышающих max_length.

Parameters:

Name	Type	Description	Default
text	str	Исходный длинный текст.	required
max_length	int	Максимальный размер одного сообщения (по умолчанию: 4096).	4096
mode	Literal['paragraph', 'line', 'word', 'char']	Стратегия разбиения: - 'paragraph': сплит по абзацам (\n\n) - 'line': сплит по строкам (\n, по умолчанию) - 'word': сплит по словам (пробелам) - 'char': жесткий сплит посимвольно	'line'

Returns:

Type	Description
list[str]	Список чанков текста.

tg_rate_limit(rate=1, per=1.0, scope='user_id', warning_text='⏱ Пожалуйста, подождите {wait_sec} сек. перед повторной отправкой.', silent=False, raise_on_limit=False)

Декоратор ограничения частоты запросов для Telegram-ботов.

Parameters:

Name	Type	Description	Default
rate	int	Количество разрешенных запросов.	1
per	float	Временное окно в секундах.	1.0
scope	str	Область ограничения: 'user_id', 'chat_id' или 'user_and_chat'.	'user_id'
warning_text	str | None	Шаблон предупреждения. Поддерживает форматирование {wait_sec}.	'⏱ Пожалуйста, подождите {wait_sec} сек. перед повторной отправкой.'
silent	bool	Если True, отбрасывать запросы без вывода предупреждения.	False
raise_on_limit	bool	Если True, выбрасывать RateLimitExceededError при флуде.	False

Returns:

Type	Description
Callable[[F], F]	Обернутая функция-хэндлер.

options: members:

• download_user_file
• send_telegram_file
• is_admin
• admin_only
• AdminFilter
• tg_rate_limit
• TelegramThrottlingMiddleware
• AccessListManager
• allowed_only
• SecretUserFilter
• trace_telegram_update
• TelegramLoggingMiddleware
• escape_markdown
• escape_html
• smart_truncate
• split_message
• TelegramLogHandler
• send_alert
• HealthCheckAlertBridge
• build_inline_keyboard
• build_reply_keyboard
• PaginatorKeyboard

Модуль vk (ВКонтакте Callback API)

chutils.vk

Экспорт основного модуля chutils.vk.

VKCallbackError

Bases: ChutilsException

Исключение при обработке VK Callback API события.

VKCallbackRouter

Маршрутизатор событий VK Callback API.

Автоматически подтверждает сервер (confirmation_code), проверяет секретный ключ (secret_key) и диспатчит входящие события по зарегистрированным хэндлерам.

__init__(confirmation_code=None, secret_key=None, path='/vk-callback')

Инициализирует VKCallbackRouter.

Parameters:

Name	Type	Description	Default
confirmation_code	str | None	Строка подтверждения сервера ВКонтакте.	None
secret_key	str | None	Секретный ключ группы для проверки authenticity.	None
path	str	HTTP путь вебхука в приложениях FastAPI / Starlette.	'/vk-callback'

get_fastapi_router()

Создает и возвращает настроенный FastAPI APIRouter.

Returns:

Type	Description
Any	Экземпляр fastapi.APIRouter.

handle_event(event_data) async

Обрабатывает входящее событие VK Callback API.

Parameters:

Name	Type	Description	Default
event_data	dict[str, Any]	Словарь запроса VK Callback API.	required

Returns:

Type	Description
str	Текст ответа (confirmation_code или "ok").

Raises:

Type	Description
VKCallbackError	Если проверка secret_key не пройдена.

on_event(event_type)

Декоратор подписки на тип события VK Callback API (например, 'message_new').

Parameters:

Name	Type	Description	Default
event_type	str	Строковое имя типа события VK API.	required

Returns:

Type	Description
Callable[[Callable[..., Any]], Callable[..., Any]]	Декоратор функции-обработчика.

on_message_new(func)

Алиас декоратора для события 'message_new'.

Parameters:

Name	Type	Description	Default
func	Callable[..., Any]	Функция-обработчик события.	required

Returns:

Type	Description
Callable[..., Any]	Переданная функция-обработчик.

on_unhandled_event(func)

Декоратор для обработки незарегистрированных типов событий.

Parameters:

Name	Type	Description	Default
func	Callable[..., Any]	Функция-обработчик несопоставленных событий.	required

Returns:

Type	Description
Callable[..., Any]	Переданная функция-обработчик.

on_wall_post_new(func)

Алиас декоратора для события 'wall_post_new'.

Parameters:

Name	Type	Description	Default
func	Callable[..., Any]	Функция-обработчик события.	required

Returns:

Type	Description
Callable[..., Any]	Переданная функция-обработчик.

options: members:

• VKCallbackRouter
• VKCallbackError

Модуль vkma (VK Mini Apps Валидация)

chutils.vkma

Экспорт основного функционала chutils.vkma.

VKMALaunchParams

Bases: BaseModel

Строго типизированная Pydantic-модель параметров запуска VK Mini App.

Официальная документация VK Mini Apps parameters: https://dev.vk.com/ru/mini-apps/development/launch-params

app_id property

Alias для vk_app_id.

is_app_user property

Установлено ли приложение пользователем (True/False).

language property

Alias для vk_language.

platform property

Alias для vk_platform.

ts property

Alias для vk_ts.

user_id property

Alias для vk_user_id.

VKMAValidationError

Bases: ChutilsException

Выбрасывается при ошибке валидации параметров запуска (launchParams) или подписи VKMA.

parse_vkma_launch_params(raw_query, client_secret=None, max_age_seconds=None)

Валидирует подпись и парсит query-строку/словарь в модель VKMALaunchParams.

Parameters:

Name	Type	Description	Default
raw_query	str | dict[str, Any]	Строка URL/initData или словарь с параметрами.	required
client_secret	str | None	Защищенный ключ приложения VK.	None
max_age_seconds	int | None	Максимальный допустимый возраст подписи.	None

Returns:

Type	Description
VKMALaunchParams	Экземпляр VKMALaunchParams.

validate_vkma_launch_params(raw_query, client_secret=None, max_age_seconds=None)

Проверяет HMAC-SHA256 подпись VK Mini App launchParams.

Parameters:

Name	Type	Description	Default
raw_query	str | dict[str, Any]	Строка параметров URL / initData или словарь параметров.	required
client_secret	str | None	Защищенный ключ приложения VK. Если None, ищется автоматически.	None
max_age_seconds	int | None	Максимальное время жизни подписи в секундах (по vk_ts).	None

Returns:

Type	Description
bool	True, если подпись валидна и время жизни не истекло.

Raises:

Type	Description
VKMAValidationError	Выбрасывается при любой ошибке (подделана или неверна подпись, истек срок действия vk_ts или не хватает параметров). Всегда оборачивайте вызов в except VKMAValidationError.

options: members:

• validate_vkma_sign
• parse_vkma_launch_params
• VKLaunchParams
• VKUser
• VKMAAuthError

Модуль audit (Журнал аудита)

chutils.audit

chutils.audit — Неизменяемый журнал событий аудита.

Предоставляет: - AuditEvent: Pydantic-схема записи аудита с криптографической цепочкой. - BaseAuditBackend, FileBackend, SqliteBackend, PostgresBackend: бэкенды хранения. - audit_event: декоратор для автоматической регистрации событий. - audit_context: контекстный менеджер для блока операций.

Использование

from chutils.audit import FileBackend, audit_event

backend = FileBackend("audit.jsonl")

@audit_event(action="user.login", actor="system") def login(user_id: str) -> None: ...

BaseAuditBackend

Bases: ABC

Абстракция хранилища записей аудита.

Все бэкенды должны реализовать метод log() для записи событий и verify_integrity() для проверки криптографической цепочки.

log(action, actor, *, target=None, status='success', details=None) abstractmethod

Записывает событие в журнал аудита.

Parameters:

Name	Type	Description	Default
action	str	Название операции.	required
actor	str	Субъект действия.	required
target	str | None	Объект операции (опционально).	None
status	str	Результат — 'success' или 'failed'.	'success'
details	dict[str, object] | None	Произвольные детали события.	None

Returns:

Type	Description
str	Идентификатор (UUID) созданной записи.

verify_integrity() abstractmethod

Проверяет целостность криптографической цепочки хэшей.

Returns:

Type	Description
bool	True если цепочка не нарушена.

Raises:

Type	Description
AuditIntegrityError	Если обнаружено нарушение целостности.

FileBackend

Bases: BaseAuditBackend

Бэкенд хранения событий аудита в JSONL-файле.

Каждая строка файла — одна запись в формате JSON. Записи связаны в криптографическую цепочку через поле prev_hash. Запись и вычисление хэшей потокобезопасны.

Parameters:

Name	Type	Description	Default
path	str | Path	Путь к файлу журнала (будет создан при первой записи).	required

__init__(path)

Инициализирует FileBackend с указанным путём к файлу журнала.

Parameters:

Name	Type	Description	Default
path	str | Path	Путь к JSONL-файлу журнала (будет создан при первой записи).	required

log(action, actor, *, target=None, status='success', details=None)

Добавляет событие в JSONL-файл.

Parameters:

Name	Type	Description	Default
action	str	Название операции.	required
actor	str	Субъект действия.	required
target	str | None	Объект операции (опционально).	None
status	str	Результат — 'success' или 'failed'.	'success'
details	dict[str, object] | None	Произвольные детали события.	None

Returns:

Type	Description
str	UUID созданной записи.

verify_integrity()

Проверяет целостность цепочки хэшей в JSONL-файле.

Returns:

Type	Description
bool	True если цепочка не нарушена.

Raises:

Type	Description
AuditIntegrityError	При обнаружении повреждённой записи.

PostgresBackend

Bases: BaseAuditBackend

Бэкенд хранения событий аудита в PostgreSQL.

Принимает DBAPI2-совместимый объект соединения (psycopg2, psycopg и т.д.). Не импортирует драйвер самостоятельно — управление соединением остаётся на стороне приложения.

Parameters:

Name	Type	Description	Default
connection	_DBAPIConnection	Открытое DBAPI2-соединение с PostgreSQL.	required

__init__(connection)

Инициализирует PostgresBackend и создаёт таблицу audit_log.

Parameters:

Name	Type	Description	Default
connection	_DBAPIConnection	Открытое DBAPI2-соединение с PostgreSQL.	required

log(action, actor, *, target=None, status='success', details=None)

Добавляет событие в таблицу audit_log PostgreSQL.

Parameters:

Name	Type	Description	Default
action	str	Название операции.	required
actor	str	Субъект действия.	required
target	str | None	Объект операции (опционально).	None
status	str	Результат — 'success' или 'failed'.	'success'
details	dict[str, object] | None	Произвольные детали события.	None

Returns:

Type	Description
str	UUID созданной записи.

verify_integrity()

Проверяет целостность цепочки хэшей в таблице PostgreSQL.

Returns:

Type	Description
bool	True если цепочка не нарушена.

Raises:

Type	Description
AuditIntegrityError	При обнаружении повреждённой записи.

SqliteBackend

Bases: BaseAuditBackend

Бэкенд хранения событий аудита в таблице SQLite.

Использует только стандартную библиотеку sqlite3 — без SQLAlchemy. Записи связаны в криптографическую цепочку через поле prev_hash. Запись потокобезопасна (threading.Lock + WAL режим SQLite).

Parameters:

Name	Type	Description	Default
path	str | Path	Путь к файлу БД (будет создан при первой записи).	required

__init__(path)

Инициализирует SqliteBackend и создаёт таблицу audit_log если она отсутствует.

Parameters:

Name	Type	Description	Default
path	str | Path	Путь к файлу SQLite БД (будет создан автоматически).	required

log(action, actor, *, target=None, status='success', details=None)

Добавляет событие в таблицу audit_log.

Parameters:

Name	Type	Description	Default
action	str	Название операции.	required
actor	str	Субъект действия.	required
target	str | None	Объект операции (опционально).	None
status	str	Результат — 'success' или 'failed'.	'success'
details	dict[str, object] | None	Произвольные детали события.	None

Returns:

Type	Description
str	UUID созданной записи.

verify_integrity()

Проверяет целостность цепочки хэшей в таблице audit_log.

Returns:

Type	Description
bool	True если цепочка не нарушена.

Raises:

Type	Description
AuditIntegrityError	При обнаружении повреждённой записи.

audit_context(action, actor, *, target=None, backend)

Контекстный менеджер для регистрации события аудита в блоке кода.

При нормальном завершении блока записывает status='success'. При исключении — status='failed' с информацией об ошибке в details. Исключение всегда пробрасывается вверх.

Parameters:

Name	Type	Description	Default
action	str	Название операции.	required
actor	str	Субъект действия.	required
target	str | None	Объект операции (опционально).	None
backend	object	Экземпляр BaseAuditBackend для записи события.	required

Yields:

Name	Type	Description
_AuditContextState	_AuditContextState	Объект с изменяемыми полями status и details.

Example

with audit_context(action="order.pay", actor="user_1", backend=backend) as ctx: ctx.details["amount"] = 100

audit_event(action, actor='system', *, target=None, backend)

Декоратор для автоматической регистрации события аудита при вызове функции.

Работает с синхронными и асинхронными функциями. При успешном завершении записывает status='success', при исключении — status='failed' с деталями ошибки. Исключение всегда пробрасывается вверх.

Parameters:

Name	Type	Description	Default
action	str	Название операции (например, 'user.login').	required
actor	_ActorOrCallable	Субъект действия — строка или callable(args, *kwargs) -> str.	'system'
target	_TargetOrCallable	Объект операции — строка, callable или None.	None
backend	object	Экземпляр BaseAuditBackend для записи события.	required

Returns:

Type	Description
Callable	Декоратор, оборачивающий функцию.

Example

@audit_event(action="user.delete", actor=lambda a, *kw: kw["user_id"], backend=backend) def delete_user(user_id: str) -> None: ...

options: members:

• AuditLogger
• AuditRecord
• BaseAuditBackend
• MemoryAuditBackend
• FileAuditBackend

Модуль store (Key-Value хранилище)

chutils.store

Модуль chutils.store — Абстракция Key-Value хранилища.

BaseStoreBackend

Bases: ABC

Абстрактный базовый класс для всех бэкендов Key-Value хранилищ.

aclear() abstractmethod async

Полностью очищает хранилище (асинхронно).

Returns:

Type	Description
bool	True при успешной очистке.

adelete(key) abstractmethod async

Удаляет запись по ключу (асинхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required

Returns:

Type	Description
bool	True, если ключ существовал и был удален.

aexists(key) abstractmethod async

Проверяет существование ключа (асинхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required

Returns:

Type	Description
bool	True, если ключ существует и не просрочен.

aget(key, default=None) abstractmethod async

Извлекает значение по ключу (асинхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required
default	Any	Значение по умолчанию, если ключ не найден или просрочен.	None

Returns:

Type	Description
Any	Сохраненное значение или default.

aset(key, value, ttl=None) abstractmethod async

Сохраняет значение по ключу с опциональным TTL (асинхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required
value	Any	Сохраняемое значение.	required
ttl	float | None	Время жизни записи в секундах.	None

Returns:

Type	Description
bool	True, если запись успешно сохранена.

clear() abstractmethod

Полностью очищает хранилище (синхронно).

Returns:

Type	Description
bool	True при успешной очистке.

delete(key) abstractmethod

Удаляет запись по ключу (синхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required

Returns:

Type	Description
bool	True, если ключ существовал и был удален.

exists(key) abstractmethod

Проверяет существование ключа (синхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required

Returns:

Type	Description
bool	True, если ключ существует и не просрочен.

get(key, default=None) abstractmethod

Извлекает значение по ключу (синхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required
default	Any	Значение по умолчанию, если ключ не найден или просрочен.	None

Returns:

Type	Description
Any	Сохраненное значение или default.

set(key, value, ttl=None) abstractmethod

Сохраняет значение по ключу с опциональным TTL (синхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required
value	Any	Сохраняемое значение.	required
ttl	float | None	Время жизни записи в секундах.	None

Returns:

Type	Description
bool	True, если запись успешно сохранена.

MemoryStore

Bases: BaseStoreBackend

Потокобезопасный in-memory бэкенд хранилища с поддержкой TTL.

aclear() async

Полностью очищает хранилище (асинхронно).

Returns:

Type	Description
bool	True при успешной очистке.

adelete(key) async

Удаляет запись по ключу (асинхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required

Returns:

Type	Description
bool	True, если ключ существовал и был удален.

aexists(key) async

Проверяет существование ключа (асинхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required

Returns:

Type	Description
bool	True, если ключ существует и не просрочен.

aget(key, default=None) async

Извлекает значение по ключу (асинхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required
default	Any	Значение по умолчанию, если ключ не найден или просрочен.	None

Returns:

Type	Description
Any	Сохраненное значение или default.

aset(key, value, ttl=None) async

Сохраняет значение по ключу (асинхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required
value	Any	Сохраняемое значение.	required
ttl	float | None	Время жизни записи в секундах.	None

Returns:

Type	Description
bool	True, если запись успешно сохранена.

clear()

Полностью очищает хранилище (синхронно).

Returns:

Type	Description
bool	True при успешной очистке.

delete(key)

Удаляет запись по ключу (синхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required

Returns:

Type	Description
bool	True, если ключ существовал и был удален.

exists(key)

Проверяет существование ключа (синхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required

Returns:

Type	Description
bool	True, если ключ существует и не просрочен.

get(key, default=None)

Извлекает значение по ключу (синхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required
default	Any	Значение по умолчанию, если ключ не найден или просрочен.	None

Returns:

Type	Description
Any	Сохраненное значение или default.

set(key, value, ttl=None)

Сохраняет значение по ключу с опциональным TTL (синхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required
value	Any	Сохраняемое значение.	required
ttl	float | None	Время жизни записи в секундах.	None

Returns:

Type	Description
bool	True, если запись успешно сохранена.

StoreManager

Центральный менеджер Key-Value хранилища.

aclear() async

Очищает хранилище (асинхронно).

Returns:

Type	Description
bool	True при успешной очистке.

adelete(key) async

Удаляет запись по ключу (асинхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required

Returns:

Type	Description
bool	True, если ключ существовал и был удален.

aexists(key) async

Проверяет существование ключа (асинхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required

Returns:

Type	Description
bool	True, если ключ существует.

aget(key, default=None) async

Извлекает и десериализует значение по ключу (асинхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required
default	Any	Значение по умолчанию, если ключ не найден.	None

Returns:

Type	Description
Any	Десериализованное значение или default.

aset(key, value, ttl=None) async

Сериализует и сохраняет значение по ключу (асинхронно).

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required
value	Any	Значение для сохранения.	required
ttl	float | None	Время жизни записи в секундах.	None

Returns:

Type	Description
bool	True, если запись успешно сохранена.

clear()

Очищает хранилище.

Returns:

Type	Description
bool	True при успешной очистке.

delete(key)

Удаляет запись по ключу.

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required

Returns:

Type	Description
bool	True, если ключ существовал и был удален.

exists(key)

Проверяет существование ключа.

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required

Returns:

Type	Description
bool	True, если ключ существует.

from_config(config=None) classmethod

Создает менеджер хранилища на основе конфигурационного словаря.

Parameters:

Name	Type	Description	Default
config	dict[str, Any] | None	Словарь конфигурации.	None

Returns:

Type	Description
StoreManager	Новый экземпляр StoreManager.

get(key, default=None)

Извлекает и десериализует значение по ключу.

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required
default	Any	Значение по умолчанию, если ключ не найден.	None

Returns:

Type	Description
Any	Десериализованное значение или default.

set(key, value, ttl=None)

Сериализует и сохраняет значение по ключу.

Parameters:

Name	Type	Description	Default
key	str	Ключ записи.	required
value	Any	Значение для сохранения.	required
ttl	float | None	Время жизни записи в секундах.	None

Returns:

Type	Description
bool	True, если запись успешно сохранена.

options: members:

• StoreManager
• MemoryStoreBackend
• RedisStoreBackend

Модуль db (Работа с базами данных)

chutils.db

Модуль chutils.db — готовый менеджер подключений к реляционным БД.

Предоставляет класс :class:DatabaseManager для управления асинхронным соединением с базой данных через SQLAlchemy 2.0.

Зависимости — опциональные. При их отсутствии вызов модуля завершается с :exc:~chutils.exceptions.OptionalDependencyError.

Пример использования::

from chutils.db import DatabaseManager

db = DatabaseManager(database_url="sqlite+aiosqlite:///:memory:")

async with db.transaction() as session:
    result = await session.execute(text("SELECT 1"))

await db.ping()
db.register_cleanup()

DatabaseManager

Менеджер подключений к реляционным БД на основе SQLAlchemy 2.0 (async).

Инкапсулирует создание асинхронного движка, фабрику сессий, контекстные менеджеры для транзакций и интеграцию с жизненным циклом chutils.

Зависимости (опциональные): sqlalchemy, asyncpg, aiosqlite.

Parameters:

Name	Type	Description	Default
database_url	str | None	URL подключения к БД. Если не передан, считывается из конфигурации chutils в следующем порядке: Секция [Database], ключ url или database_url. Секция [Secrets], ключ database_url.	None
echo	bool	Включить вывод SQL-запросов в консоль (для отладки). По умолчанию False.	False
**engine_kwargs	object	Дополнительные параметры, передаваемые в :func:sqlalchemy.ext.asyncio.create_async_engine.	{}

Raises:

Type	Description
ConfigError	Если URL подключения не задан ни явно, ни в конфигурации.

Example

Базовое использование::

db = DatabaseManager(database_url="sqlite+aiosqlite:///:memory:")

async with db.transaction() as session:
    await session.execute(text("INSERT INTO ..."))

Автоматическое чтение URL из конфига::

# config.ini:
# [Database]
# url = postgresql+asyncpg://user:pass@localhost/mydb

db = DatabaseManager()

__init__(database_url=None, echo=False, **engine_kwargs)

Инициализирует DatabaseManager и создаёт асинхронный движок.

Parameters:

Name	Type	Description	Default
database_url	str | None	URL подключения к БД. Если None, URL считывается из конфигурации chutils.	None
echo	bool	Если True, все SQL-запросы выводятся в stdout.	False
**engine_kwargs	object	Дополнительные именованные аргументы для :func:~sqlalchemy.ext.asyncio.create_async_engine.	{}

Raises:

Type	Description
ConfigError	Если URL не найден ни в параметрах, ни в конфигурации.

ping() async

Проверяет доступность подключения к базе данных.

Выполняет простой запрос SELECT 1 и возвращает результат проверки.

Returns:

Type	Description
bool	True если соединение успешно, False — при любой ошибке.

Example::

is_alive = await db.ping()
if not is_alive:
    logger.error("База данных недоступна!")

register_cleanup()

Регистрирует метод закрытия движка в менеджере жизненного цикла chutils.

После вызова этого метода движок (и пул соединений) будет корректно освобождён при завершении приложения через :func:~chutils.lifecycle.register_cleanup.

Example::

db = DatabaseManager(database_url="postgresql+asyncpg://...")
db.register_cleanup()  # автоматически закроет пул при shutdown

session() async

Асинхронный контекстный менеджер, возвращающий сессию SQLAlchemy.

Сессия не управляет транзакцией автоматически — для этого используйте :meth:transaction.

Yields:

Name	Type	Description
Открытая	AsyncIterator[AsyncSession]	class:~sqlalchemy.ext.asyncio.AsyncSession.

Example::

async with db.session() as session:
    result = await session.execute(text("SELECT 1"))

transaction() async

Асинхронный контекстный менеджер для транзакций.

Автоматически вызывает :meth:commit по выходу из блока или :meth:rollback при возникновении исключения.

Yields:

Type	Description
AsyncIterator[AsyncSession]	class:~sqlalchemy.ext.asyncio.AsyncSession в рамках активной транзакции.

Raises:

Type	Description
Exception	Любое исключение из тела блока async with инициирует откат транзакции и пробрасывается дальше.

Example::

async with db.transaction() as session:
    session.add(MyModel(name="test"))

options: members:

• DatabaseManager
• DatabaseConfig

Модуль lifecycle (Управление жизненным циклом и graceful shutdown)

chutils.lifecycle

Управление жизненным циклом приложения.

Обеспечивает механизмы регистрации функций очистки (cleanup callbacks), которые будут выполнены при завершении работы приложения.

CleanupCallback = Callable[[], Any] | Callable[[], Awaitable[Any]] module-attribute

Тип для функций очистки.

AsyncLifecycleContext

Контекстный менеджер для управления жизненным циклом ресурсов приложения.

Поддерживает протоколы async with и with.

__aenter__() async

Вход в асинхронный контекстный менеджер.

__aexit__(exc_type, exc_val, exc_tb) async

Выход из асинхронного контекстного менеджера.

__enter__()

Вход в синхронный контекстный менеджер.

__exit__(exc_type, exc_val, exc_tb)

Выход из синхронного контекстного менеджера.

__init__(setup_signals=True, auto_cleanup_subsystems=True, manager=None)

Инициализирует контекстный менеджер жизненного цикла.

Parameters:

Name	Type	Description	Default
setup_signals	bool	Автоматически перехватывать сигналы завершения ОС (SIGINT, SIGTERM).	True
auto_cleanup_subsystems	bool	Автоматически очищать подсистемы chutils (db, tasks, logger).	True
manager	LifecycleManager | None	Опциональный менеджер жизненного цикла (по умолчанию глобальный).	None

LifecycleManager

Менеджер жизненного цикла, управляющий реестром функций очистки.

__init__()

Инициализирует LifecycleManager.

get_cleanup_callbacks()

Возвращает список зарегистрированных функций в порядке LIFO.

Returns:

Type	Description
list[CleanupCallback]	Список функций очистки в порядке LIFO.

register_cleanup(func)

Регистрирует функцию для выполнения при завершении работы.

Функции выполняются в порядке LIFO (Last-In-First-Out). Поддерживаются как синхронные, так и асинхронные функции.

Parameters:

Name	Type	Description	Default
func	CleanupCallback	Функция или корутина для регистрации.	required

Returns:

Type	Description
CleanupCallback	Та же функция (позволяет использовать как декоратор).

restore_signals()

Восстанавливает исходные обработчики сигналов ОС.

setup_graceful_shutdown(signals=None)

Настраивает перехват сигналов завершения работы.

Parameters:

Name	Type	Description	Default
signals	list[int] | None	Опциональный список сигналов для отслеживания.	None

unregister_cleanup(func)

Удаляет функцию из реестра функций очистки.

Parameters:

Name	Type	Description	Default
func	CleanupCallback	Функция или корутина для удаления.	required

Returns:

Type	Description
bool	True, если функция была найдена и удалена, иначе False.

async_run_cleanup() async

Асинхронно выполняет все зарегистрированные функции очистки LIFO.

lifecycle(setup_signals=True, auto_cleanup_subsystems=True)

Возвращает контекстный менеджер для управления жизненным циклом ресурсов.

Parameters:

Name	Type	Description	Default
setup_signals	bool	Перехватывать сигналы ОС (SIGINT, SIGTERM).	True
auto_cleanup_subsystems	bool	Очищать подсистемы chutils при выходе.	True

Returns:

Type	Description
AsyncLifecycleContext	Экземпляр AsyncLifecycleContext, поддерживающий async with и with.

Example

async with chutils.lifecycle(setup_signals=True):
    await app.run()

register_cleanup(func)

Регистрирует функцию очистки в менеджере.

Эта функция является публичным API для добавления колбэков, которые будут вызваны при завершении работы приложения.

Parameters:

Name	Type	Description	Default
func	CleanupCallback	Функция-колбэк, которую нужно зарегистрировать. Должна соответствовать типу CleanupCallback.	required

Returns:

Type	Description
CleanupCallback	Зарегистрированная функция (возвращает тот же объект для
CleanupCallback	использования в качестве декоратора).

Example

Использование в качестве декоратора: @register_cleanup async def close_db(): await db.close()

Использование как обычной функции: def cleanup_logs(): print("Cleaning up logs...") register_cleanup(cleanup_logs)

run_cleanup()

Выполняет все зарегистрированные функции очистки LIFO (безопасно для вызова из синхронного кода и активных Event Loop).

setup_graceful_shutdown()

Публичный API для настройки Graceful Shutdown.

Рекомендуется вызывать в самом начале работы приложения.

unregister_cleanup(func)

Удаляет функцию из реестра функций очистки.

Parameters:

Name	Type	Description	Default
func	CleanupCallback	Функция или корутина для удаления.	required

Returns:

Type	Description
bool	True, если функция была найдена и удалена, иначе False.

options: members:

• register_cleanup
• unregister_cleanup
• run_cleanup
• async_run_cleanup
• setup_graceful_shutdown
• lifecycle
• AsyncLifecycleContext

Модуль http (HTTP-клиент и TLS Impersonation)

chutils.http

chutils.http — Лёгковесный HTTP-клиент с батареями.

Предоставляет синхронный и асинхронный HTTP-клиенты с встроенной поддержкой отказоустойчивости, трассировки и маскирования секретов.

Основное использование:

from chutils.http import HttpClient, ResiliencePolicy

policy = ResiliencePolicy(retries=3, timeout=10.0)
with HttpClient(base_url="https://api.example.com", policy=policy) as client:
    resp = client.get("/users/1")
    resp.raise_for_status()
    data = resp.json()

Stand-alone функции:

from chutils import http
resp = http.get("https://httpbin.org/get")

Async-использование:

from chutils.http import AsyncHttpClient

async with AsyncHttpClient(base_url="https://api.example.com") as client:
    resp = await client.get("/status")

CURL_CFFI_AVAILABLE = importlib.util.find_spec('curl_cffi') is not None module-attribute

Флаг доступности библиотеки curl-cffi.

DEFAULT_IMPERSONATE_PROFILE = 'chrome120' module-attribute

Профиль браузера по умолчанию для TLS Client Impersonation.

AsyncEventStreamClient

Асинхронный клиент для HTTP Streaming и SSE.

AsyncHttpClient

Асинхронный HTTP-клиент на базе httpx.AsyncClient.

Требует установленного httpx. При его отсутствии вызывает OptionalDependencyError при инициализации.

Parameters:

Name	Type	Description	Default
base_url	str	Базовый URL-префикс для всех запросов.	''
default_headers	dict[str, str] | None	Заголовки по умолчанию.	None
timeout	float | None	Таймаут запросов в секундах.	30.0
policy	ResiliencePolicy | None	Политика отказоустойчивости.	None
sensitive_headers	set[str] | None	Дополнительные заголовки для маскирования.	None

Example

from chutils.http import AsyncHttpClient, ResiliencePolicy

policy = ResiliencePolicy(retries=2, timeout=5.0)
async with AsyncHttpClient(
    base_url="https://api.example.com", policy=policy
) as client:
    resp = await client.get("/status")
    resp.raise_for_status()

__aenter__() async

Поддержка async-контекстного менеджера.

Returns:

Type	Description
Self	Сам экземпляр клиента.

__aexit__(*args) async

Закрывает async-клиент при выходе из контекстного менеджера.

__init__(*, base_url='', default_headers=None, timeout=30.0, policy=None, sensitive_headers=None)

Инициализирует AsyncHttpClient.

Parameters:

Name	Type	Description	Default
base_url	str	Базовый URL для всех запросов.	''
default_headers	dict[str, str] | None	Заголовки по умолчанию.	None
timeout	float | None	Таймаут в секундах.	30.0
policy	ResiliencePolicy | None	Политика отказоустойчивости.	None
sensitive_headers	set[str] | None	Имена заголовков для маскирования.	None

Raises:

Type	Description
OptionalDependencyError	Если httpx не установлен.

aclose() async

Закрывает async-клиент и освобождает ресурсы.

delete(path, *, headers=None, timeout=None) async

Выполняет async DELETE-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

get(path, *, headers=None, timeout=None) async

Выполняет async GET-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

patch(path, *, headers=None, json_data=None, data=None, timeout=None) async

Выполняет async PATCH-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела.	None
data	bytes | str | None	Сырое тело.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

post(path, *, headers=None, json_data=None, data=None, timeout=None) async

Выполняет async POST-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела.	None
data	bytes | str | None	Сырое тело.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

put(path, *, headers=None, json_data=None, data=None, timeout=None) async

Выполняет async PUT-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела.	None
data	bytes | str | None	Сырое тело.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

request(method, path, *, headers=None, json_data=None, data=None, timeout=None) async

Выполняет асинхронный HTTP-запрос.

Parameters:

Name	Type	Description	Default
method	str	HTTP-метод (GET, POST, PUT, DELETE, PATCH).	required
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела.	None
data	bytes | str | None	Сырое тело запроса.	None
timeout	float | None	Таймаут для этого конкретного запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

AsyncWebSocketClient

Асинхронный клиент для WebSockets.

connect() async

Устанавливает асинхронное соединение по WebSocket.

recv() async

Принимает текстовое или бинарное сообщение из WebSocket.

Returns:

Type	Description
str | bytes	Принятое сообщение.

send(message) async

Отправляет текстовое или бинарное сообщение через WebSocket.

Parameters:

Name	Type	Description	Default
message	str | bytes	Сообщение для отправки.	required

EventStreamClient

Синхронный клиент-обертка для HTTP Streaming и SSE.

HttpClient

Синхронный HTTP-клиент с батареями (httpx + fallback на urllib).

При наличии httpx использует его как транспорт. При отсутствии — прозрачно переключается на встроенный urllib.request, выводя единоразовое предупреждение в лог.

Parameters:

Name	Type	Description	Default
base_url	str	Базовый URL-префикс для всех запросов.	''
default_headers	dict[str, str] | None	Заголовки, добавляемые к каждому запросу.	None
timeout	float | None	Таймаут запросов по умолчанию в секундах.	30.0
policy	ResiliencePolicy | None	Политика отказоустойчивости (retry, semaphore и т.д.).	None
sensitive_headers	set[str] | None	Дополнительные заголовки для маскирования в логах.	None

Example

from chutils.http import HttpClient, ResiliencePolicy

policy = ResiliencePolicy(retries=3, timeout=10.0)
with HttpClient(base_url="https://api.example.com", policy=policy) as client:
    resp = client.get("/users/1")
    resp.raise_for_status()
    data = resp.json()

__enter__()

Поддержка контекстного менеджера.

Returns:

Type	Description
Self	Сам экземпляр клиента.

__exit__(*args)

Закрывает клиент при выходе из контекстного менеджера.

__init__(*, base_url='', default_headers=None, timeout=30.0, policy=None, sensitive_headers=None)

Инициализирует HttpClient.

Parameters:

Name	Type	Description	Default
base_url	str	Базовый URL для всех запросов.	''
default_headers	dict[str, str] | None	Заголовки по умолчанию для каждого запроса.	None
timeout	float | None	Таймаут в секундах.	30.0
policy	ResiliencePolicy | None	Политика отказоустойчивости.	None
sensitive_headers	set[str] | None	Имена заголовков для маскирования в логах.	None

close()

Закрывает клиент и освобождает ресурсы.

delete(path, *, headers=None, timeout=None)

Выполняет DELETE-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

get(path, *, headers=None, timeout=None)

Выполняет GET-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

patch(path, *, headers=None, json_data=None, data=None, timeout=None)

Выполняет PATCH-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела.	None
data	bytes | str | None	Сырое тело.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

post(path, *, headers=None, json_data=None, data=None, timeout=None)

Выполняет POST-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела.	None
data	bytes | str | None	Сырое тело.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

put(path, *, headers=None, json_data=None, data=None, timeout=None)

Выполняет PUT-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела.	None
data	bytes | str | None	Сырое тело.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

request(method, path, *, headers=None, json_data=None, data=None, timeout=None)

Выполняет HTTP-запрос.

Parameters:

Name	Type	Description	Default
method	str	HTTP-метод (GET, POST, PUT, DELETE, PATCH).	required
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела запроса.	None
data	bytes | str | None	Сырое тело запроса (bytes или str).	None
timeout	float | None	Таймаут для этого конкретного запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

HttpResponse dataclass

Ответ HTTP-запроса.

Attributes:

Name	Type	Description
status_code	int	HTTP-статус-код ответа.
headers	dict[str, str]	Заголовки ответа.
content	bytes	Тело ответа в байтах.
elapsed	float	Время выполнения запроса в секундах.
url	str	Итоговый URL (с учётом редиректов).

text property

Тело ответа в виде строки UTF-8.

Returns:

Type	Description
str	Декодированное тело ответа.

json()

Десериализует тело ответа как JSON.

Returns:

Type	Description
object	Распарсенный JSON-объект.

Raises:

Type	Description
ValueError	Если тело не является корректным JSON.

raise_for_status()

Вызывает исключение, если статус-код указывает на ошибку (4xx / 5xx).

Raises:

Type	Description
HttpClientError	Если статус-код >= 400.

ResiliencePolicy

Политика отказоустойчивости: retry, timeout, semaphore, circuit breaker.

Применяется к произвольным синхронным (apply_sync) и асинхронным (apply_async) вызовам для обеспечения надёжности.

Attributes:

Name	Type	Description
retries		Количество повторных попыток после первого отказа.
retry_delay		Базовая задержка (сек.) между попытками.
retry_backoff		Множитель задержки для экспоненциального отступа.
retry_jitter		Добавлять ли случайный шум к задержке.
retry_exceptions		Кортеж классов исключений, при которых выполняется повтор.
retry_on_status_codes		Набор HTTP-статус-кодов, при которых выполняется повтор.
timeout		Максимальное время выполнения вызова (сек.); None — без ограничения.
max_concurrency		Максимальное число одновременных вызовов; None — без ограничения.
cb_failure_threshold		Порог отказов для размыкания Circuit Breaker.
cb_recovery_timeout		Время (сек.) до попытки восстановления Circuit Breaker.

Example

policy = ResiliencePolicy(retries=3, timeout=5.0, max_concurrency=10)
result = policy.apply_sync(requests.get, url)

__init__(*, retries=3, retry_delay=0.5, retry_backoff=2.0, retry_jitter=False, retry_exceptions=(Exception,), retry_on_status_codes=(429, 500, 502, 503, 504), timeout=None, max_concurrency=None, cb_failure_threshold=5, cb_recovery_timeout=30.0)

Инициализирует политику отказоустойчивости.

Parameters:

Name	Type	Description	Default
retries	int	Количество повторных попыток после первого отказа.	3
retry_delay	float	Базовая задержка между попытками в секундах.	0.5
retry_backoff	float	Множитель задержки для экспоненциального отступа.	2.0
retry_jitter	bool	Если True, добавляет случайный шум к задержке.	False
retry_exceptions	tuple[type[Exception], ...]	Кортеж классов исключений, при которых выполняется retry.	(Exception,)
retry_on_status_codes	tuple[int, ...]	HTTP-статус-коды для retry (используется с extractor).	(429, 500, 502, 503, 504)
timeout	float | None	Максимальное время выполнения вызова в секундах.	None
max_concurrency	int | None	Максимальное число одновременных вызовов.	None
cb_failure_threshold	int	Порог отказов для открытия Circuit Breaker.	5
cb_recovery_timeout	float	Пауза перед попыткой восстановления Circuit Breaker.	30.0

apply_async(func, *args, http_error_extractor=None, **kwargs) async

Применяет политику к асинхронному вызову.

Оборачивает await func(*args, **kwargs) в retry, timeout и semaphore.

Parameters:

Name	Type	Description	Default
func	Callable[..., object]	Асинхронный вызываемый объект (coroutine function).	required
*args	object	Позиционные аргументы для func.	()
http_error_extractor	Callable[[Exception], int] | None	Опциональная функция для извлечения HTTP-статус-кода из пойманного исключения.	None
**kwargs	object	Именованные аргументы для func.	{}

Returns:

Type	Description
object	Результат await func(*args, **kwargs).

Raises:

Type	Description
ChutilsTimeoutError	При превышении timeout.
CircuitBreakerOpenError	Если Circuit Breaker разомкнут.
Exception	Последнее перехваченное исключение после исчерпания retry.

apply_sync(func, *args, http_error_extractor=None, **kwargs)

Применяет политику к синхронному вызову.

Оборачивает func(*args, **kwargs) в retry, timeout и semaphore.

Parameters:

Name	Type	Description	Default
func	Callable[..., object]	Вызываемый объект.	required
*args	object	Позиционные аргументы для func.	()
http_error_extractor	Callable[[Exception], int] | None	Опциональная функция для извлечения HTTP-статус-кода из пойманного исключения. Используется для retry по retry_on_status_codes.	None
**kwargs	object	Именованные аргументы для func.	{}

Returns:

Type	Description
object	Результат func(*args, **kwargs).

Raises:

Type	Description
ChutilsTimeoutError	При превышении timeout.
CircuitBreakerOpenError	Если Circuit Breaker разомкнут.
Exception	Последнее перехваченное исключение после исчерпания retry.

ServerSentEvent dataclass

Представляет собой отдельное событие Server-Sent Events (SSE).

TLSAsyncClient

Асинхронный HTTP-клиент с поддержкой TLS/HTTP2 Client Impersonation (curl-cffi).

__init__(impersonate=DEFAULT_IMPERSONATE_PROFILE, proxy=None, proxy_pool=None, fallback_to_standard=False, timeout=30.0, **kwargs)

Инициализирует TLSAsyncClient.

Parameters:

Name	Type	Description	Default
impersonate	str	Профиль маскировки браузера (напр. 'chrome120', 'safari17_0').	DEFAULT_IMPERSONATE_PROFILE
proxy	ProxyConfig | str | None	Прокси-сервер (ProxyConfig или строка).	None
proxy_pool	ProxyPool | None	Пул прокси chutils.	None
fallback_to_standard	bool	Флаг автоматического отката на AsyncHttpClient при отсутствии curl-cffi.	False
timeout	float	Таймаут запросов в секундах.	30.0
**kwargs	Any	Дополнительные параметры конфигурации.	{}

Raises:

Type	Description
OptionalDependencyError	Если curl-cffi отсутствует и fallback_to_standard=False.

aclose() async

Закрывает асинхронную сессию.

close() async

Псевдоним для aclose.

delete(url, **kwargs) async

Выполняет асинхронный DELETE запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

from_browser_session(target, impersonate=DEFAULT_IMPERSONATE_PROFILE, **kwargs) async classmethod

Создает асинхронный клиент TLSAsyncClient, предзаполненный cookies и User-Agent из браузера.

Parameters:

Name	Type	Description	Default
target	Any	Экземпляр Playwright (Page, Context), Nodriver Tab или Selenium WebDriver.	required
impersonate	str	Профиль маскировки браузера.	DEFAULT_IMPERSONATE_PROFILE
**kwargs	Any	Дополнительные параметры для TLSAsyncClient.	{}

Returns:

Type	Description
Self	Экземпляр TLSAsyncClient.

get(url, **kwargs) async

Выполняет асинхронный GET запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

patch(url, **kwargs) async

Выполняет асинхронный PATCH запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

post(url, **kwargs) async

Выполняет асинхронный POST запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

put(url, **kwargs) async

Выполняет асинхронный PUT запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

request(method, url, **kwargs) async

Выполняет асинхронный HTTP-запрос.

Parameters:

Name	Type	Description	Default
method	str	HTTP метод (GET, POST, etc.).	required
url	str	Целевой URL.	required
**kwargs	Any	Параметры запроса (headers, params, data, json, timeout).	{}

Returns:

Type	Description
HttpResponse	Унифицированный объект ответа HttpResponse.

TLSSession

Синхронный HTTP-клиент с поддержкой TLS/HTTP2 Client Impersonation (curl-cffi).

__init__(impersonate=DEFAULT_IMPERSONATE_PROFILE, proxy=None, proxy_pool=None, fallback_to_standard=False, timeout=30.0, **kwargs)

Инициализирует TLSSession.

Parameters:

Name	Type	Description	Default
impersonate	str	Профиль маскировки браузера (напр. 'chrome120', 'safari17_0').	DEFAULT_IMPERSONATE_PROFILE
proxy	ProxyConfig | str | None	Прокси-сервер (ProxyConfig или строка).	None
proxy_pool	ProxyPool | None	Пул прокси chutils.	None
fallback_to_standard	bool	Флаг автоматического отката на HttpClient при отсутствии curl-cffi.	False
timeout	float	Таймаут запросов в секундах.	30.0
**kwargs	Any	Дополнительные параметры конфигурации.	{}

Raises:

Type	Description
OptionalDependencyError	Если curl-cffi отсутствует и fallback_to_standard=False.

close()

Закрывает базовую сессию.

delete(url, **kwargs)

Выполняет DELETE запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

from_browser_session(target, impersonate=DEFAULT_IMPERSONATE_PROFILE, **kwargs) classmethod

Создает сессию TLSSession, предзаполненную cookies и User-Agent из браузера.

Parameters:

Name	Type	Description	Default
target	Any	Экземпляр Selenium WebDriver.	required
impersonate	str	Профиль маскировки браузера.	DEFAULT_IMPERSONATE_PROFILE
**kwargs	Any	Дополнительные параметры для TLSSession.	{}

Returns:

Type	Description
Self	Экземпляр TLSSession.

get(url, **kwargs)

Выполняет GET запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

patch(url, **kwargs)

Выполняет PATCH запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

post(url, **kwargs)

Выполняет POST запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

put(url, **kwargs)

Выполняет PUT запрос.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required
**kwargs	Any	Дополнительные параметры запроса.	{}

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

request(method, url, **kwargs)

Выполняет синхронный HTTP-запрос.

Parameters:

Name	Type	Description	Default
method	str	HTTP метод (GET, POST, etc.).	required
url	str	Целевой URL.	required
**kwargs	Any	Параметры запроса (headers, params, data, json, timeout).	{}

Returns:

Type	Description
HttpResponse	Унифицированный объект ответа HttpResponse.

UrllibFallbackClient

Синхронный HTTP-клиент на базе urllib.request.

Используется как fallback, когда httpx не доступен. Поддерживает интеграцию с ResiliencePolicy для retry, timeout и semaphore.

Parameters:

Name	Type	Description	Default
base_url	str	Базовый URL, который будет префиксом для всех запросов.	''
default_headers	dict[str, str] | None	Заголовки по умолчанию для всех запросов.	None
timeout	float | None	Таймаут подключения и чтения в секундах.	30.0
policy	ResiliencePolicy | None	Политика отказоустойчивости.	None
sensitive_headers	set[str] | None	Дополнительные заголовки для маскирования в логах.	None

Example

client = UrllibFallbackClient(
    base_url="https://api.example.com",
    default_headers={"Authorization": "Bearer token"},
    timeout=10.0,
)
response = client.get("/users/1")
response.raise_for_status()
data = response.json()

__enter__()

Поддержка контекстного менеджера.

Returns:

Type	Description
Self	Сам экземпляр клиента.

__exit__(*args)

Закрывает клиент при выходе из контекстного менеджера.

__init__(*, base_url='', default_headers=None, timeout=30.0, policy=None, sensitive_headers=None)

Инициализирует fallback HTTP-клиент.

Parameters:

Name	Type	Description	Default
base_url	str	Базовый URL для всех запросов.	''
default_headers	dict[str, str] | None	Заголовки, добавляемые к каждому запросу.	None
timeout	float | None	Таймаут в секундах (подключение + чтение).	30.0
policy	ResiliencePolicy | None	Политика отказоустойчивости (retry, semaphore и т.д.).	None
sensitive_headers	set[str] | None	Дополнительные имена заголовков для маскирования.	None

close()

Закрывает клиент (no-op для urllib-клиента, для совместимости API).

delete(path, *, headers=None, timeout=None)

Выполняет DELETE-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

get(path, *, headers=None, timeout=None)

Выполняет GET-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

patch(path, *, headers=None, json_data=None, data=None, timeout=None)

Выполняет PATCH-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела запроса.	None
data	bytes | str | None	Сырое тело запроса.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

post(path, *, headers=None, json_data=None, data=None, timeout=None)

Выполняет POST-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела запроса.	None
data	bytes | str | None	Сырое тело запроса.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

put(path, *, headers=None, json_data=None, data=None, timeout=None)

Выполняет PUT-запрос.

Parameters:

Name	Type	Description	Default
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки.	None
json_data	object | None	Данные для JSON-тела запроса.	None
data	bytes | str | None	Сырое тело запроса.	None
timeout	float | None	Таймаут запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

request(method, path, *, headers=None, json_data=None, data=None, timeout=None)

Выполняет HTTP-запрос с заданным методом.

Parameters:

Name	Type	Description	Default
method	str	HTTP-метод (GET, POST, PUT, DELETE, PATCH).	required
path	str	Путь или абсолютный URL.	required
headers	dict[str, str] | None	Дополнительные заголовки запроса.	None
json_data	object | None	Данные для сериализации в JSON-тело запроса.	None
data	bytes | str | None	Сырое тело запроса (bytes или str).	None
timeout	float | None	Таймаут для этого конкретного запроса.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

Raises:

Type	Description
HttpClientError	При сетевой ошибке.
ValueError	Если переданы одновременно json_data и data.

WebSocketClient

Синхронный клиент-обертка для WebSockets.

connect()

Устанавливает синхронное соединение по WebSocket.

recv()

Принимает текстовое или бинарное сообщение из WebSocket.

Returns:

Type	Description
str | bytes	Принятое сообщение.

send(message)

Отправляет текстовое или бинарное сообщение через WebSocket.

Parameters:

Name	Type	Description	Default
message	str | bytes	Сообщение для отправки.	required

create_curl_async_session(impersonate, proxy=None, **kwargs)

Создает асинхронную сессию curl_cffi с заданным профилем impersonate.

Parameters:

Name	Type	Description	Default
impersonate	str	Имя профиля браузера (например, 'chrome120').	required
proxy	str | None	URL прокси-сервера.	None
**kwargs	Any	Дополнительные параметры для AsyncSession.	{}

Returns:

Type	Description
Any	Экземпляр curl_cffi.requests.AsyncSession.

create_curl_session(impersonate, proxy=None, **kwargs)

Создает синхронную сессию curl_cffi с заданным профилем impersonate.

Parameters:

Name	Type	Description	Default
impersonate	str	Имя профиля браузера (например, 'chrome120').	required
proxy	str | None	URL прокси-сервера.	None
**kwargs	Any	Дополнительные параметры для Session.	{}

Returns:

Type	Description
Any	Экземпляр curl_cffi.requests.Session.

create_http_span(method, url, tracer_name='chutils.http')

Создаёт OTEL-спан для исходящего HTTP-запроса.

Если OpenTelemetry не установлен, возвращает None.

Parameters:

Name	Type	Description	Default
method	str	HTTP-метод (GET, POST и т.д.).	required
url	str	Полный URL запроса.	required
tracer_name	str	Имя трейсера (используется для группировки спанов).	'chutils.http'

Returns:

Type	Description
object | None	Контекстный менеджер спана или None, если OTEL недоступен.

Example

from chutils.http.tracing import create_http_span

span = create_http_span("GET", "https://api.example.com/users")
if span is not None:
    with span:
        response = requests.get(url)

delete(url, *, headers=None, timeout=None, policy=None)

Выполняет DELETE-запрос.

Parameters:

Name	Type	Description	Default
url	str	Абсолютный URL запроса.	required
headers	dict[str, str] | None	Дополнительные HTTP-заголовки.	None
timeout	float | None	Таймаут запроса в секундах.	None
policy	ResiliencePolicy | None	Политика отказоустойчивости.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

get(url, *, headers=None, timeout=None, policy=None)

Выполняет GET-запрос.

Создаёт временный HttpClient, выполняет запрос и возвращает ответ.

Parameters:

Name	Type	Description	Default
url	str	Абсолютный URL запроса.	required
headers	dict[str, str] | None	Дополнительные HTTP-заголовки.	None
timeout	float | None	Таймаут запроса в секундах.	None
policy	ResiliencePolicy | None	Политика отказоустойчивости (retry, timeout, semaphore).	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse с телом, заголовками и статус-кодом ответа.

Example

from chutils import http

resp = http.get("https://httpbin.org/get", timeout=5.0)
resp.raise_for_status()
data = resp.json()

inject_trace_headers(headers)

Инжектирует W3C Trace Context заголовки в словарь заголовков запроса.

Если OpenTelemetry не установлен или трассировка не настроена, возвращает заголовки без изменений.

Инжектируемые заголовки: - traceparent: идентификаторы trace и span (формат W3C). - tracestate: дополнительное состояние вендора (опционально).

Parameters:

Name	Type	Description	Default
headers	dict[str, str]	Исходный словарь HTTP-заголовков запроса.	required

Returns:

Type	Description
dict[str, str]	Обновлённый словарь с добавленными заголовками трассировки
dict[str, str]	(или оригинальный, если OTEL недоступен).

Example

from chutils.http.tracing import inject_trace_headers

headers = {"Authorization": "Bearer token"}
headers = inject_trace_headers(headers)
# headers теперь содержит "traceparent" если OTEL активен

patch(url, *, headers=None, json_data=None, data=None, timeout=None, policy=None)

Выполняет PATCH-запрос.

Parameters:

Name	Type	Description	Default
url	str	Абсолютный URL запроса.	required
headers	dict[str, str] | None	Дополнительные HTTP-заголовки.	None
json_data	object | None	Данные для JSON-тела запроса.	None
data	bytes | str | None	Сырое тело запроса.	None
timeout	float | None	Таймаут запроса в секундах.	None
policy	ResiliencePolicy | None	Политика отказоустойчивости.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

post(url, *, headers=None, json_data=None, data=None, timeout=None, policy=None)

Выполняет POST-запрос.

Parameters:

Name	Type	Description	Default
url	str	Абсолютный URL запроса.	required
headers	dict[str, str] | None	Дополнительные HTTP-заголовки.	None
json_data	object | None	Данные для сериализации в JSON-тело запроса.	None
data	bytes | str | None	Сырое тело запроса (bytes или str).	None
timeout	float | None	Таймаут запроса в секундах.	None
policy	ResiliencePolicy | None	Политика отказоустойчивости.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

Example

resp = http.post(
    "https://api.example.com/users",
    json_data={"name": "Alice", "email": "alice@example.com"},
)
resp.raise_for_status()

put(url, *, headers=None, json_data=None, data=None, timeout=None, policy=None)

Выполняет PUT-запрос.

Parameters:

Name	Type	Description	Default
url	str	Абсолютный URL запроса.	required
headers	dict[str, str] | None	Дополнительные HTTP-заголовки.	None
json_data	object | None	Данные для JSON-тела запроса.	None
data	bytes | str | None	Сырое тело запроса.	None
timeout	float | None	Таймаут запроса в секундах.	None
policy	ResiliencePolicy | None	Политика отказоустойчивости.	None

Returns:

Type	Description
HttpResponse	Объект HttpResponse.

options: members:

• HttpClient
• AsyncHttpClient
• TLSSession
• TLSAsyncClient
• create_curl_session
• create_curl_async_session
• HttpResponse
• ResiliencePolicy
• UrllibFallbackClient
• AsyncEventStreamClient
• EventStreamClient
• AsyncWebSocketClient
• WebSocketClient
• ServerSentEvent
• get
• post
• put
• delete
• patch

Модуль scraping.fingerprint (Синтезатор цифровой личности)

chutils.scraping.fingerprint

Подсистема комбинаторного синтеза цифровой личности браузера (Fingerprint Synthesizer).

AudioFingerprint

Bases: BaseModel

Параметры аудиоподсистемы и микрошум дискретизации ЦАП.

FingerprintProfile

Bases: BaseModel

Полный синтезированный профиль цифровой личности браузера.

apply_to_page(page) async

Применяет параметры отпечатка к странице Playwright Page.

Parameters:

Name	Type	Description	Default
page	Any	Страница Playwright (Page).	required

apply_to_tab(tab) async

Применяет параметры отпечатка к вкладке nodriver Tab.

Parameters:

Name	Type	Description	Default
tab	Any	Вкладка nodriver (Tab).	required

from_file(path) classmethod

Загружает профиль из сохраненного JSON файла.

Parameters:

Name	Type	Description	Default
path	str | Path	Путь к файлу профиля.	required

Returns:

Type	Description
FingerprintProfile	Восстановленный экземпляр FingerprintProfile.

save_to_file(path)

Сохраняет профиль в JSON файл на диске.

Parameters:

Name	Type	Description	Default
path	str | Path	Путь к целевому файлу.	required

to_antidetect_config(stealth_minimal=True)

Конвертирует профиль в AntidetectConfig для браузерных движков.

Parameters:

Name	Type	Description	Default
stealth_minimal	bool	Если True, не накладывать синтетический шум на Canvas.	True

Returns:

Type	Description
AntidetectConfig	Экземпляр AntidetectConfig с параметрами профиля.

to_dict()

Возвращает профиль в виде словаря.

Returns:

Type	Description
dict[str, Any]	Словарь со всеми полями профиля.

to_json(indent=2)

Сериализует профиль в строку JSON.

Parameters:

Name	Type	Description	Default
indent	int	Размер отступа для форматирования.	2

Returns:

Type	Description
str	Строка профиля в формате JSON.

FingerprintSynthesizer

Интеллектуальный синтезатор цифровой личности браузера с поддержкой процедурного и байесовского режимов.

__init__(mode='auto', os_target='windows', locale='ru-RU')

Инициализирует синтезатор.

Parameters:

Name	Type	Description	Default
mode	Literal['auto', 'procedural', 'browserforge', 'fpgen']	Режим работы ('auto', 'procedural', 'browserforge', 'fpgen'). В режиме 'auto' при наличии browserforge используется он (включая детерминированную генерацию по сиду), иначе используется процедурный генератор.	'auto'
os_target	str	Целевая операционная система ('windows', 'macos', 'linux').	'windows'
locale	str	Локаль системы для подбора периферийных устройств.	'ru-RU'

create_from_browserforge(browser='chrome', os_target='windows', seed=None) classmethod

Быстрый хелпер создания отпечатка через библиотеку browserforge.

Parameters:

Name	Type	Description	Default
browser	str	Тип эмулируемого браузера ('chrome', 'firefox', 'safari').	'chrome'
os_target	str	Целевая ОС ('windows', 'macos', 'linux').	'windows'
seed	int | str | None	Опциональный сид для воспроизводимой детерминированной генерации.	None

Returns:

Type	Description
FingerprintProfile	Экземпляр FingerprintProfile, созданный обученной байесовской сетью.

create_procedural(seed=None, os_target='windows', locale='ru-RU') classmethod

Быстрый хелпер создания чисто процедурного отпечатка.

Parameters:

Name	Type	Description	Default
seed	int | str | None	Опциональный сид для повторяемой генерации отпечатка.	None
os_target	str	Имя целевой ОС ('windows', 'macos', 'linux').	'windows'
locale	str	Локаль системы для подбора периферии.	'ru-RU'

Returns:

Type	Description
FingerprintProfile	Экземпляр FingerprintProfile с физически валидным отпечатком.

get_or_create(seed, storage_dir)

Загружает сохраненный профиль по сиду с диска либо синтезирует и сохраняет новый.

Parameters:

Name	Type	Description	Default
seed	int | str	Уникальный идентификатор (сид) профиля.	required
storage_dir	str | Path	Директория для хранения файлов профилей.	required

Returns:

Type	Description
FingerprintProfile	Экземпляр FingerprintProfile.

is_browserforge_available() staticmethod

Проверяет, установлена ли библиотека browserforge.

Returns:

Type	Description
bool	True, если библиотека найдена и доступна для импорта, иначе False.

is_fpgen_available() staticmethod

Проверяет, установлена ли библиотека fpgen.

Returns:

Type	Description
bool	True, если библиотека найдена и доступна для импорта, иначе False.

synthesize(seed=None)

Синтезирует отпечаток цифровой личности.

Parameters:

Name	Type	Description	Default
seed	int | str | None	Сид профиля для детерминированной генерации.	None

Returns:

Type	Description
FingerprintProfile	Экземпляр FingerprintProfile с физически согласованными характеристиками.

HardwareFingerprint

Bases: BaseModel

Аппаратные ресурсы процессора и оперативной памяти.

MediaDeviceItem

Bases: BaseModel

Элемент списка медиа-устройств (микрофон, динамики, камера).

ScreenFingerprint

Bases: BaseModel

Геометрия и характеристики дисплея.

WebGLFingerprint

Bases: BaseModel

Параметры графического стека WebGL.

options: members: - FingerprintSynthesizer - FingerprintProfile - WebGLFingerprint - ScreenFingerprint - HardwareFingerprint - AudioFingerprint - MediaDeviceItem - BrowserForgeProvider

Модуль scraping.humanize (Имитация поведения и антидетект)

chutils.scraping.humanize

AntidetectConfig

Bases: BaseModel

Конфигурация параметров маскировки браузера (антидетект).

apply_to_nodriver(tab) async

Применяет данную конфигурацию антидетекта к вкладке nodriver Tab.

Parameters:

Name	Type	Description	Default
tab	Any	Экземпляр вкладки nodriver Tab.	required

apply_to_playwright(target) async

Применяет данную конфигурацию антидетекта к Playwright Page или BrowserContext.

Parameters:

Name	Type	Description	Default
target	Any	Экземпляр Playwright BrowserContext или Page.	required

apply_to_selenium(driver)

Применяет данную конфигурацию антидетекта к Selenium WebDriver.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required

from_browserforge(seed=None, *, browser='chrome', os='windows', stealth_minimal=True) classmethod

Генерирует отпечаток через байесовскую сеть browserforge (при наличии пакета).

Parameters:

Name	Type	Description	Default
seed	int | str | None	Опциональный сид для воспроизводимой детерминированной генерации.	None
browser	str	Эмулируемый браузер ('chrome').	'chrome'
os	str	Целевая ОС ('windows').	'windows'
stealth_minimal	bool	Режим маскировки.	True

Returns:

Type	Description
AntidetectConfig	Экземпляр AntidetectConfig.

from_fingerprint(profile, *, stealth_minimal=True) classmethod

Создает AntidetectConfig на основе объекта FingerprintProfile.

Parameters:

Name	Type	Description	Default
profile	FingerprintProfile | Any	Экземпляр FingerprintProfile.	required
stealth_minimal	bool	Если True, не накладывать синтетический шум на Canvas.	True

Returns:

Type	Description
AntidetectConfig	Сконфигурированный экземпляр AntidetectConfig.

from_procedural(seed=None, *, stealth_minimal=True, os_target='windows', locale='ru-RU') classmethod

Синтезирует отпечаток через встроенный процедурный генератор.

Parameters:

Name	Type	Description	Default
seed	int | str | None	Опциональный сид.	None
stealth_minimal	bool	Режим маскировки.	True
os_target	str	Целевая ОС.	'windows'
locale	str	Локаль.	'ru-RU'

Returns:

Type	Description
AntidetectConfig	Экземпляр AntidetectConfig.

from_seed(seed, *, stealth_minimal=True, os_target='windows', locale='ru-RU') classmethod

Синтезирует детерминированную цифровую личность по сиду и возвращает AntidetectConfig.

Один и тот же сид всегда дает абсолютно идентичный и физически согласованный отпечаток (видеокарта, процессор, память, геометрия экрана, панель задач).

Parameters:

Name	Type	Description	Default
seed	int | str	Сид профиля или имя учетной записи.	required
stealth_minimal	bool	Если True, сохраняет чистый отпечаток без искажения Canvas.	True
os_target	str	Целевая ОС ('windows').	'windows'
locale	str	Локаль ('ru-RU', 'en-US').	'ru-RU'

Returns:

Type	Description
AntidetectConfig	Экземпляр AntidetectConfig.

get_behavioral_profile()

Возвращает детерминированный биометрический профиль моторики на основе session_seed.

Returns:

Type	Description
Any	Экземпляр BehavioralProfile.

get_init_script()

Генерирует JavaScript-скрипт антидетекта на основе настроек конфигурации.

Returns:

Type	Description
str	Строка исполняемого JavaScript-кода для инъекции в браузер.

preset_aggressive(*, webgl_vendor=DEFAULT_WEBGL_VENDOR, webgl_renderer=DEFAULT_WEBGL_RENDERER, hardware_concurrency=DEFAULT_HARDWARE_CONCURRENCY, device_memory=DEFAULT_DEVICE_MEMORY, session_seed=1337, client_hints=None, user_agent=None) classmethod

Агрессивный пресет с рандомизацией Canvas/WebGL/Audio (для Playwright/Selenium в headless).

Parameters:

Name	Type	Description	Default
webgl_vendor	str	Эмулируемый производитель WebGL.	DEFAULT_WEBGL_VENDOR
webgl_renderer	str	Эмулируемая видеокарта WebGL.	DEFAULT_WEBGL_RENDERER
hardware_concurrency	int	Эмулируемое количество ядер CPU.	DEFAULT_HARDWARE_CONCURRENCY
device_memory	int	Эмулируемый объем оперативной памяти в ГБ.	DEFAULT_DEVICE_MEMORY
session_seed	str | int	Сид для рандомизации шума Canvas/Audio.	1337
client_hints	dict[str, Any] | None	Дополнительные параметры Client Hints.	None
user_agent	str | None	Опциональная строка User-Agent.	None

Returns:

Type	Description
AntidetectConfig	Экземпляр AntidetectConfig с агрессивной рандомизацией.

preset_minimal(*, session_seed=1337, user_agent=None) classmethod

Минимальный пресет: отключен шум, только базовая защита от утечек и скрытие webdriver.

Parameters:

Name	Type	Description	Default
session_seed	str | int	Сид для инициализации сессии.	1337
user_agent	str | None	Опциональная строка User-Agent.	None

Returns:

Type	Description
AntidetectConfig	Экземпляр AntidetectConfig с минимальной модификацией.

preset_stealth_nodriver(*, session_seed=1337, client_hints=None, user_agent=None) classmethod

Рекомендуемый пресет для nodriver: zero-footprint (без синтетического шума Canvas/WebGL).

Parameters:

Name	Type	Description	Default
session_seed	str | int	Сид для детерминированного генератора псевдослучайных чисел.	1337
client_hints	dict[str, Any] | None	Опциональный словарь с параметрами Client Hints.	None
user_agent	str | None	Опциональная строка User-Agent.	None

Returns:

Type	Description
AntidetectConfig	Экземпляр AntidetectConfig с конфигурацией zero-footprint.

BehavioralProfile

Bases: BaseModel

Конфигурация биометрического профиля моторики (скорость, задержки, опечатки, движение мыши).

error_rate property

Алиас для typo_rate.

wpm property

Алиас для speed_wpm.

async_click(page, selector=None, x=None, y=None, start=None, button='left') async

Выполняет клик по элементу или координатам с биометрией удержания кнопки мыши.

Parameters:

Name	Type	Description	Default
page	Any	Объект страницы Playwright Page или вкладки nodriver Tab.	required
selector	str | None	Селектор целевого элемента (опционально).	None
x	int | None	Конечная координата X клика.	None
y	int | None	Конечная координата Y клика.	None
start	tuple[int, int] | None	Начальные координаты курсора.	None
button	str	Кнопка мыши ('left', 'right', 'middle').	'left'

async_type_text(page, selector, text, paste_threshold=None) async

Вводит текст через Playwright / nodriver с биометрическими параметрами профиля.

Parameters:

Name	Type	Description	Default
page	Any	Объект страницы Playwright Page или вкладки nodriver Tab.	required
selector	str	CSS/XPath селектор поля ввода.	required
text	str	Текст для ввода.	required
paste_threshold	int | None	Порог адаптивной вставки через буфер (если None, берется из профиля).	None

click(driver, selector=None, x=None, y=None, start=None, algorithm='windmouse')

Синхронно выполняет клик через Selenium с биометрией удержания кнопки мыши.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required
selector	str | None	Селектор целевого элемента.	None
x	int | None	Координата X клика.	None
y	int | None	Координата Y клика.	None
start	tuple[int, int] | None	Начальные координаты мыши.	None
algorithm	str	Алгоритм перемещения ('windmouse' или 'bezier').	'windmouse'

create_typo_generator()

Создает генератор опечаток клавиатуры, настроенный под параметры профиля.

Returns:

Type	Description
KeyboardTypoGenerator	Экземпляр KeyboardTypoGenerator.

create_wind_mouse()

Создает генератор траекторий мыши WindMouse, настроенный под параметры профиля.

Returns:

Type	Description
WindMouseGenerator	Экземпляр WindMouseGenerator.

from_seed(seed) classmethod

Создает детерминированный биометрический профиль моторики на основе сида.

Один и тот же сид всегда порождает абсолютно идентичные биометрические характеристики (скорость ввода, опечатки, физику мыши, интервалы удержания), что позволяет зафиксировать уникальный почерк конкретного аккаунта или браузерного профиля.

Parameters:

Name	Type	Description	Default
seed	int | str	Числовой или строковый сид сессии/аккаунта.	required

Returns:

Type	Description
BehavioralProfile	Экземпляр BehavioralProfile с реалистичными биометрическими характеристиками.

type_text(driver, selector, text, paste_threshold=None)

Синхронно вводит текст через Selenium с биометрическими параметрами профиля.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required
selector	str	CSS-селектор поля ввода.	required
text	str	Текст для ввода.	required
paste_threshold	int | None	Порог адаптивной вставки через буфер (если None, берется из профиля).	None

BezierCurveGenerator

Генератор траекторий перемещения на основе кривых Безье.

generate(start, end, steps=30, deviation=0.2)

Генерирует сглаженную траекторию от start к end.

Parameters:

Name	Type	Description	Default
start	tuple[int, int]	Начальная координата (x, y).	required
end	tuple[int, int]	Конечная координата (x, y).	required
steps	int	Количество шагов (точек) в траектории.	30
deviation	float	Максимальное отклонение контрольных точек от прямой линии.	0.2

Returns:

Type	Description
list[tuple[int, int]]	Список координат точек траектории движения.

JitterDelayGenerator

Генератор реалистичных задержек.

__init__(strategy='lognormal', jitter=0.15)

Инициализирует генератор задержек.

Parameters:

Name	Type	Description	Default
strategy	str	Стратегия ('lognormal' или 'normal').	'lognormal'
jitter	float	Коэффициент разброса (джиттер).	0.15

generate(base_delay)

Возвращает сгенерированную задержку на основе базовой.

Parameters:

Name	Type	Description	Default
base_delay	float	Базовая величина задержки (в секундах).	required

Returns:

Type	Description
float	Полученное случайное значение задержки с учетом джиттера.

KeyboardTypoGenerator

Генератор последовательностей ввода символов с реалистичными опечатками.

__init__(layout_error_rate=0.0, delayed_fix_rate=0.0)

Инициализирует генератор опечаток.

Parameters:

Name	Type	Description	Default
layout_error_rate	float	Вероятность ошибки переключения раскладки в начале ввода (0.0 - 1.0).	0.0
delayed_fix_rate	float	Вероятность отложенного исправления опечатки навигацией стрелками (0.0 - 1.0).	0.0

generate_sequence(text, error_rate=0.05, layout_error_rate=None, delayed_fix_rate=None)

Генерирует последовательность нажатий клавиш для ввода текста.

Включает случайные опечатки, их обнаружение и исправление через Backspace. При ненулевой layout_error_rate в самом начале ввода может произойти реалистичная ошибка раскладки (например, ввод нескольких символов латиницей вместо кириллицы с последующим полным стиранием и повторным вводом на правильном языке). При ненулевой delayed_fix_rate моделируется более сложная опечатка: пользователь допускает ошибку, по инерции допечатывает несколько символов/слов, а затем возвращается клавишами стрелок назад (ArrowLeft), исправляет опечатку и прыгает в конец строки (End).

Parameters:

Name	Type	Description	Default
text	str	Исходный текст.	required
error_rate	float	Вероятность совершения ошибки на каждом символе.	0.05
layout_error_rate	float | None	Вероятность ошибки раскладки в начале ввода. Если None, используется значение из конструктора (по умолчанию 0.0).	None
delayed_fix_rate	float | None	Вероятность отложенного исправления опечатки. Если None, используется значение из конструктора (по умолчанию 0.0).	None

Returns:

Type	Description
list[TypoAction]	Список действий TypoAction, имитирующий последовательный ввод текста человеком.

ProfileWarmer

Класс для асинхронного прогрева браузерных профилей (Playwright, nodriver).

Обеспечивает естественный цифровой след путем посещения сайтов, скроллинга, имитации мыши и переходов по внутренним ссылкам.

__init__(browser_or_tab)

Инициализирует ProfileWarmer.

Parameters:

Name	Type	Description	Default
browser_or_tab	Any	Объект страницы Playwright Page или вкладки nodriver Tab.	required

save_profile(filepath, password=None, metadata=None) async

Экспортирует сессию после прогрева и сохраняет её в .chprofile файл через ProfileManager.

Parameters:

Name	Type	Description	Default
filepath	str | Path	Путь к сохраняемому файлу (.chprofile).	required
password	str | None	Опциональный пароль для шифрования данных профиля.	None
metadata	dict[str, str] | None	Пользовательские метаданные.	None

Returns:

Type	Description
Any	Экземпляр BrowserProfile.

warm_up(sites=None, sites_count=3, duration_per_site=(10.0, 30.0), click_random_links=True) async

Запускает процесс прогрева профиля.

Parameters:

Name	Type	Description	Default
sites	list[str] | None	Список URL-адресов трастовых сайтов для прогрева. Если None, используется встроенный список.	None
sites_count	int	Количество посещаемых сайтов.	3
duration_per_site	tuple[float, float]	Диапазон времени пребывания на одном сайте (мин, макс в секундах).	(10.0, 30.0)
click_random_links	bool	Флаг перехода по случайным внутренним ссылкам.	True

warm_up_search(queries=None, category=None, queries_count=2, search_engine='google', click_result=True, surf_result_duration=(5.0, 15.0)) async

Симулирует органический поиск и серфинг по результатам выдачи.

Parameters:

Name	Type	Description	Default
queries	list[str] | None	Список поисковых запросов. Если None, выбираются случайные запросы из банка.	None
category	str | None	Категория запросов ('tech', 'news', 'science', 'lifestyle'), если queries is None.	None
queries_count	int	Количество запросов для поиска.	2
search_engine	str	Поисковая система ('google' или 'yandex').	'google'
click_result	bool	Переходить ли по органической ссылке из выдачи.	True
surf_result_duration	tuple[float, float]	Время пребывания на целевом сайте после перехода (мин, макс в секундах).	(5.0, 15.0)

SyncProfileWarmer

Класс для синхронного прогрева браузерных профилей (Selenium).

__init__(driver)

Инициализирует SyncProfileWarmer.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required

save_profile(filepath, password=None, metadata=None)

Синхронно экспортирует сессию Selenium и сохраняет в .chprofile файл через ProfileManager.

Parameters:

Name	Type	Description	Default
filepath	str | Path	Путь к сохраняемому файлу (.chprofile).	required
password	str | None	Опциональный пароль для шифрования.	None
metadata	dict[str, str] | None	Пользовательские метаданные.	None

Returns:

Type	Description
Any	Экземпляр BrowserProfile.

warm_up(sites=None, sites_count=3, duration_per_site=(10.0, 30.0), click_random_links=True)

Запускает процесс прогрева профиля (синхронно).

Parameters:

Name	Type	Description	Default
sites	list[str] | None	Список URL-адресов трастовых сайтов для прогрева. Если None, используется встроенный список.	None
sites_count	int	Количество посещаемых сайтов.	3
duration_per_site	tuple[float, float]	Диапазон времени пребывания на одном сайте (мин, макс в секундах).	(10.0, 30.0)
click_random_links	bool	Флаг перехода по случайным внутренним ссылкам.	True

warm_up_search(queries=None, category=None, queries_count=2, search_engine='google', click_result=True, surf_result_duration=(5.0, 15.0))

Синхронно симулирует органический поиск и серфинг по результатам выдачи Selenium.

Parameters:

Name	Type	Description	Default
queries	list[str] | None	Список поисковых запросов. Если None, выбираются случайные запросы из банка.	None
category	str | None	Категория запросов ('tech', 'news', 'science', 'lifestyle'), если queries is None.	None
queries_count	int	Количество запросов для поиска.	2
search_engine	str	Поисковая система ('google' или 'yandex').	'google'
click_result	bool	Переходить ли по органической ссылке из выдачи.	True
surf_result_duration	tuple[float, float]	Время пребывания на целевом сайте после перехода (мин, макс в секундах).	(5.0, 15.0)

WindMouseGenerator

Генератор траекторий перемещения мыши на основе физической модели WindMouse (гравитация, ветер, инерция).

__init__(gravity=9.0, wind=3.0, min_wait=0.002, max_wait=0.005, max_step=15.0, target_area=8.0)

Инициализирует генератор WindMouse.

Parameters:

Name	Type	Description	Default
gravity	float	Сила притяжения курсора к целевой точке.	9.0
wind	float	Величина случайного отклонения (ветра/мышечных микроколебаний).	3.0
min_wait	float	Минимальная пауза между смещениями (в секундах).	0.002
max_wait	float	Максимальная пауза между смещениями (в секундах).	0.005
max_step	float	Максимальное расстояние одного шага (скорость).	15.0
target_area	float	Радиус целевой зоны, при входе в которую уменьшается влияние ветра и падает скорость.	8.0

generate(start, end, gravity=None, wind=None, min_wait=None, max_wait=None, max_step=None, target_area=None, *, with_delays=True)

generate(
    start: tuple[int, int],
    end: tuple[int, int],
    gravity: float | None = None,
    wind: float | None = None,
    min_wait: float | None = None,
    max_wait: float | None = None,
    max_step: float | None = None,
    target_area: float | None = None,
    *,
    with_delays: Literal[True] = ...,
) -> list[tuple[int, int, float]]

generate(
    start: tuple[int, int],
    end: tuple[int, int],
    gravity: float | None = None,
    wind: float | None = None,
    min_wait: float | None = None,
    max_wait: float | None = None,
    max_step: float | None = None,
    target_area: float | None = None,
    *,
    with_delays: Literal[False],
) -> list[tuple[int, int]]

generate(
    start: tuple[int, int],
    end: tuple[int, int],
    gravity: float | None = None,
    wind: float | None = None,
    min_wait: float | None = None,
    max_wait: float | None = None,
    max_step: float | None = None,
    target_area: float | None = None,
    *,
    with_delays: bool,
) -> list[tuple[int, int, float]] | list[tuple[int, int]]

Генерирует последовательность точек от start к end.

Parameters:

Name	Type	Description	Default
start	tuple[int, int]	Начальные координаты (x, y).	required
end	tuple[int, int]	Конечные координаты (x, y).	required
gravity	float | None	Переопределение силы гравитации.	None
wind	float | None	Переопределение силы ветра.	None
min_wait	float | None	Переопределение минимальной задержки шага.	None
max_wait	float | None	Переопределение максимальной задержки шага.	None
max_step	float | None	Переопределение максимального размера шага.	None
target_area	float | None	Переопределение радиуса целевой зоны.	None
with_delays	bool	Если True, возвращает кортежи (x, y, delay). Если False, возвращает (x, y).	True

Returns:

Type	Description
list[tuple[int, int, float]] | list[tuple[int, int]]	Список точек пути с задержками или без них.

generate_points(start, end, gravity=None, wind=None, max_step=None, target_area=None)

Генерирует последовательность координат (x, y) без задержек.

Parameters:

Name	Type	Description	Default
start	tuple[int, int]	Начальные координаты (x, y).	required
end	tuple[int, int]	Конечные координаты (x, y).	required
gravity	float | None	Переопределение силы гравитации.	None
wind	float | None	Переопределение силы ветра.	None
max_step	float | None	Переопределение максимального размера шага.	None
target_area	float | None	Переопределение радиуса целевой зоны.	None

Returns:

Type	Description
list[tuple[int, int]]	Список координат (x, y).

apply_antidetect_nodriver(tab, *, config=None, webgl_vendor=DEFAULT_WEBGL_VENDOR, webgl_renderer=DEFAULT_WEBGL_RENDERER, hardware_concurrency=DEFAULT_HARDWARE_CONCURRENCY, device_memory=DEFAULT_DEVICE_MEMORY, stealth_minimal=True, session_seed=1337, client_hints=None, user_agent=None) async

Применяет JS-инъекции анти-детекта к вкладке (Tab) nodriver.

По умолчанию stealth_minimal=True для сохранения естественного отпечатка реального Chromium и предотвращения детекта искусственного шума Canvas/WebGL.

Parameters:

Name	Type	Description	Default
tab	Any	Объект вкладки nodriver Tab.	required
config	AntidetectConfig | None	Экземпляр AntidetectConfig (если указан, параметры берутся из него).	None
webgl_vendor	str	Подменяемый производитель WebGL.	DEFAULT_WEBGL_VENDOR
webgl_renderer	str	Подменяемая видеокарта WebGL.	DEFAULT_WEBGL_RENDERER
hardware_concurrency	int	Эмулируемое количество ядер процессора.	DEFAULT_HARDWARE_CONCURRENCY
device_memory	int	Эмулируемый объем оперативной памяти в ГБ.	DEFAULT_DEVICE_MEMORY
stealth_minimal	bool	Если True, не накладывать синтетический шум на Canvas и не подменять WebGL, сохраняя естественный отпечаток установленного браузера Google Chrome (True по умолчанию).	True
session_seed	str | int	Сид для детерминированного шума Canvas.	1337
client_hints	dict[str, Any] | None	Дополнительные параметры Client Hints (navigator.userAgentData).	None
user_agent	str | None	Пользовательская строка User-Agent для переопределения через CDP.	None

apply_antidetect_playwright(context, *, config=None, webgl_vendor=DEFAULT_WEBGL_VENDOR, webgl_renderer=DEFAULT_WEBGL_RENDERER, hardware_concurrency=DEFAULT_HARDWARE_CONCURRENCY, device_memory=DEFAULT_DEVICE_MEMORY, stealth_minimal=False, session_seed=1337, client_hints=None, user_agent=None) async

Применяет JS-инъекции анти-детекта к контексту Playwright.

Parameters:

Name	Type	Description	Default
context	Any	Объект контекста Playwright BrowserContext.	required
config	AntidetectConfig | None	Экземпляр AntidetectConfig (если указан, параметры берутся из него).	None
webgl_vendor	str	Подменяемый производитель WebGL.	DEFAULT_WEBGL_VENDOR
webgl_renderer	str	Подменяемая видеокарта WebGL.	DEFAULT_WEBGL_RENDERER
hardware_concurrency	int	Эмулируемое количество ядер процессора.	DEFAULT_HARDWARE_CONCURRENCY
device_memory	int	Эмулируемый объем оперативной памяти в ГБ.	DEFAULT_DEVICE_MEMORY
stealth_minimal	bool	Если True, не накладывать синтетический шум на Canvas и не подменять WebGL.	False
session_seed	str | int	Сид для детерминированного шума Canvas.	1337
client_hints	dict[str, Any] | None	Дополнительные параметры Client Hints (navigator.userAgentData).	None
user_agent	str | None	Пользовательская строка User-Agent.	None

apply_antidetect_selenium(driver, *, config=None, webgl_vendor=DEFAULT_WEBGL_VENDOR, webgl_renderer=DEFAULT_WEBGL_RENDERER, hardware_concurrency=DEFAULT_HARDWARE_CONCURRENCY, device_memory=DEFAULT_DEVICE_MEMORY, stealth_minimal=False, session_seed=1337, client_hints=None, user_agent=None)

Применяет JS-инъекции анти-детекта к сессии Selenium.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required
config	AntidetectConfig | None	Экземпляр AntidetectConfig (если указан, параметры берутся из него).	None
webgl_vendor	str	Подменяемый производитель WebGL.	DEFAULT_WEBGL_VENDOR
webgl_renderer	str	Подменяемая видеокарта WebGL.	DEFAULT_WEBGL_RENDERER
hardware_concurrency	int	Эмулируемое количество ядер процессора.	DEFAULT_HARDWARE_CONCURRENCY
device_memory	int	Эмулируемый объем оперативной памяти в ГБ.	DEFAULT_DEVICE_MEMORY
stealth_minimal	bool	Если True, не накладывать синтетический шум на Canvas и не подменять WebGL.	False
session_seed	str | int	Сид для детерминированного шума Canvas.	1337
client_hints	dict[str, Any] | None	Дополнительные параметры Client Hints (navigator.userAgentData).	None
user_agent	str | None	Пользовательская строка User-Agent.	None

async_click(page, selector=None, x=None, y=None, start=None, algorithm='windmouse', button='left', hold_time=(0.05, 0.12), timeout=None) async

Имитирует реалистичный клик мышью (с плавным наведением, микропаузами и удержанием кнопки).

Parameters:

Name	Type	Description	Default
page	Any	Объект страницы Playwright Page или вкладки nodriver Tab.	required
selector	str | None	Селектор целевого элемента (если x, y не заданы).	None
x	int | None	Конечная координата X.	None
y	int | None	Конечная координата Y.	None
start	tuple[int, int] | None	Начальные координаты курсора.	None
algorithm	str	Алгоритм движения ('windmouse' или 'bezier').	'windmouse'
button	str	Кнопка мыши ('left', 'right', 'middle').	'left'
hold_time	tuple[float, float]	Диапазон задержки удержания кнопки мыши (в секундах).	(0.05, 0.12)
timeout	float | None	Таймаут выполнения операции в секундах.	None

async_human_sleep(min_seconds, max_seconds) async

Асинхронно задерживает выполнение на случайное время, имитируя поведение человека.

Parameters:

Name	Type	Description	Default
min_seconds	float	Минимальное время задержки (в секундах).	required
max_seconds	float	Максимальное время задержки (в секундах).	required

async_move_mouse(page, x, y, start=None, steps=30, delay_between_steps=0.01, algorithm='bezier', *, timeout=None) async

Имитирует плавное перемещение мыши Playwright или nodriver.

Parameters:

Name	Type	Description	Default
page	Any	Объект страницы Playwright Page или вкладки nodriver Tab.	required
x	int	Конечная координата X.	required
y	int	Конечная координата Y.	required
start	tuple[int, int] | None	Начальные координаты X, Y. Если не задано, используется (0, 0).	None
steps	int	Количество промежуточных шагов движения (для алгоритма 'bezier').	30
delay_between_steps	float	Задержка между шагами в секундах (для алгоритма 'bezier').	0.01
algorithm	str	Алгоритм генерации траектории ('bezier' или 'windmouse').	'bezier'
timeout	float | None	Максимальное время ожидания операции (в секундах).	None

async_scroll_to(page, x, y, selector=None, steps=10, delay_between_steps=0.01, *, timeout=None) async

Имитирует плавный скроллинг Playwright или nodriver.

Parameters:

Name	Type	Description	Default
page	Any	Объект страницы Playwright Page или вкладки nodriver Tab.	required
x	int	Конечная горизонтальная позиция скролла.	required
y	int	Конечная вертикальная позиция скролла.	required
selector	str | None	Необязательный селектор элемента для скролла.	None
steps	int	Количество промежуточных шагов.	10
delay_between_steps	float	Задержка между шагами в секундах.	0.01
timeout	float | None	Максимальное время ожидания операции (в секундах).	None

async_type_text(page, selector, text, error_rate=0.05, speed_wpm=40.0, key_hold_time=(0.04, 0.09), layout_error_rate=0.0, delayed_fix_rate=0.0, paste_threshold=None, paste_delay_before=(0.4, 1.0), paste_delay_after=(0.3, 0.8), timeout=None) async

Имитирует ввод текста с опечатками Playwright или nodriver.

Поддерживает адаптивный ввод: если длина текста превышает paste_threshold, текст вставляется целиком (имитируя вставку из буфера обмена Ctrl+V / Paste) с естественными паузами обдумывания до и после вставки.

Parameters:

Name	Type	Description	Default
page	Any	Объект страницы Playwright Page или вкладки nodriver Tab.	required
selector	str	Селектор поля ввода.	required
text	str	Текст для ввода.	required
error_rate	float	Вероятность совершения опечатки (0.0 - 1.0).	0.05
speed_wpm	float	Скорость ввода в словах в минуту (WPM).	40.0
key_hold_time	tuple[float, float]	Диапазон задержки удержания клавиши (keyDown -> keyUp) в секундах.	(0.04, 0.09)
layout_error_rate	float	Вероятность ошибки переключения раскладки в начале ввода (0.0 - 1.0).	0.0
delayed_fix_rate	float	Вероятность отложенного исправления опечатки навигацией стрелками (0.0 - 1.0).	0.0
paste_threshold	int | None	Порог длины текста для вставки через буфер обмена. Если None, ввод всегда посимвольный.	None
paste_delay_before	tuple[float, float]	Диапазон паузы обдумывания перед вставкой из буфера (в секундах).	(0.4, 1.0)
paste_delay_after	tuple[float, float]	Диапазон паузы проверки после вставки из буфера (в секундах).	(0.3, 0.8)
timeout	float | None	Таймаут выполнения операции в секундах.	None

click(driver, selector=None, x=None, y=None, start=None, algorithm='windmouse', hold_time=(0.05, 0.12))

Имитирует реалистичный клик мышью Selenium.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required
selector	str | None	CSS-селектор целевого элемента (если x, y не заданы).	None
x	int | None	Конечная координата X.	None
y	int | None	Конечная координата Y.	None
start	tuple[int, int] | None	Начальные координаты курсора.	None
algorithm	str	Алгоритм движения ('windmouse' или 'bezier').	'windmouse'
hold_time	tuple[float, float]	Диапазон задержки удержания кнопки мыши (в секундах).	(0.05, 0.12)

detect_cf_turnstile(tab) async

Обнаруживает присутствие и координаты виджета Cloudflare Turnstile.

Parameters:

Name	Type	Description	Default
tab	Any	Объект вкладки nodriver Tab или Playwright Page.	required

Returns:

Type	Description
dict[str, Any] | None	Словарь с параметрами виджета ('found', 'solved', 'x', 'y', 'width', 'height', 'interactive')
dict[str, Any] | None	либо None, если Turnstile не найден.

get_browser_launch_args(*, no_sandbox=False)

Возвращает расширенный набор аргументов запуска браузера для скрытия автоматизации.

Предотвращает появление инфобаров, системных всплывающих окон Chromium о падениях и некорректном завершении сессий.

Note

Флаг --no-sandbox по умолчанию отключен (False), так как отключение песочницы является первичным триггером для многих систем антифрода (Cloudflare, Google Cloud Armor) и снижает безопасность. Если запуск производится внутри изолированного Docker-контейнера без прав root/SYS_ADMIN, передайте no_sandbox=True.

Флаги --disable-blink-features=AutomationControlled, --use-fake-ui-for-media-stream и подобные намеренно исключены, так как в современных версиях Chromium они вызывают системный инфобар о неподдерживаемых флагах или детектируются антибот-системами. Скрытие navigator.webdriver выполняется через CDP-инъекцию скрипта антидетекта.

Parameters:

Name	Type	Description	Default
no_sandbox	bool	Если True, добавляет флаг --no-sandbox (рекомендуется только для root Docker-контейнеров).	False

Returns:

Type	Description
list[str]	Список аргументов командной строки запуска браузера.

get_client_hints(user_agent=None)

Генерирует словарь согласованных Client Hints (navigator.userAgentData) на основе User-Agent.

Parameters:

Name	Type	Description	Default
user_agent	str | None	Строка User-Agent. Если None, используется стандартный Chrome на Windows.	None

Returns:

Type	Description
dict[str, Any]	Словарь с параметрами Client Hints: platform, mobile, brands.

get_random_search_queries(count=3, category=None)

Возвращает список случайных реалистичных поисковых запросов.

Parameters:

Name	Type	Description	Default
count	int	Количество запрашиваемых поисковых запросов.	3
category	str | None	Необязательная категория ('tech', 'news', 'science', 'lifestyle').	None

Returns:

Type	Description
list[str]	Список строк с поисковыми запросами.

get_search_engine_config(engine='google')

Возвращает конфигурацию для органического поиска в указанной поисковой системе.

Parameters:

Name	Type	Description	Default
engine	str	Имя поисковой системы ('google' или 'yandex').	'google'

Returns:

Type	Description
dict[str, str]	Словарь с параметрами (base_url, search_url, input_selector, submit_selector, organic_selector).

human_sleep(min_seconds, max_seconds)

Синхронно задерживает выполнение на случайное время, имитируя поведение человека.

Parameters:

Name	Type	Description	Default
min_seconds	float	Минимальное время задержки (в секундах).	required
max_seconds	float	Максимальное время задержки (в секундах).	required

is_cf_turnstile_solved(tab) async

Проверяет, решен ли челендж Cloudflare Turnstile в сессии.

Parameters:

Name	Type	Description	Default
tab	Any	Объект вкладки nodriver Tab или Playwright Page.	required

Returns:

Type	Description
bool	True, если в DOM присутствует токен ответа или установлена cookie cf_clearance.

is_organic_url(url, engine='google')

Проверяет, является ли URL органической внешней ссылкой из поисковой выдачи, исключая рекламу, внутренние сервисы поисковика и трекинговые редиректы.

Parameters:

Name	Type	Description	Default
url	str	Проверяемый URL.	required
engine	str	Имя поисковой системы ('google' или 'yandex').	'google'

Returns:

Type	Description
bool	True, если ссылка является валидной органической внешней ссылкой, иначе False.

move_mouse(driver, x, y, start=None, steps=30, delay_between_steps=0.01, algorithm='bezier')

Имитирует плавное перемещение мыши Selenium.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required
x	int	Конечная координата X.	required
y	int	Конечная координата Y.	required
start	tuple[int, int] | None	Начальные координаты X, Y. Если не задано, используется (0, 0).	None
steps	int	Количество промежуточных шагов (для алгоритма 'bezier').	30
delay_between_steps	float	Задержка между шагами в секундах (для алгоритма 'bezier').	0.01
algorithm	str	Алгоритм генерации траектории ('bezier' или 'windmouse').	'bezier'

scroll_to(driver, x, y, selector=None, steps=10, delay_between_steps=0.01)

Имитирует плавный скроллинг Selenium.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required
x	int	Конечная горизонтальная позиция скролла.	required
y	int	Конечная вертикальная позиция скролла.	required
selector	str | None	Необязательный селектор элемента для скролла.	None
steps	int	Количество промежуточных шагов.	10
delay_between_steps	float	Задержка между шагами в секундах.	0.01

solve_cf_turnstile(tab, *, timeout=15.0, check_interval=0.5, click_delay=(0.5, 1.2), click_offset=None, natural_hover=True, raise_on_failure=False) async

Автоматически обнаруживает и решает капчу Cloudflare Turnstile.

Находит интерактивную область чекбокса, выполняет реалистичное наведение курсора мыши по кривой Безье/WindMouse и клик, после чего ожидает получения токена валидации.

Parameters:

Name	Type	Description	Default
tab	Any	Объект вкладки nodriver Tab или Playwright Page.	required
timeout	float	Максимальное время ожидания решения капчи в секундах.	15.0
check_interval	float	Интервал проверки состояния капчи в секундах.	0.5
click_delay	tuple[float, float]	Задержка перед кликом после наведения (min, max).	(0.5, 1.2)
click_offset	tuple[float, float] | None	Пользовательские смещения (offset_x, offset_y) относительно левого верхнего угла виджета. Если None, рассчитываются адаптивно.	None
natural_hover	bool	Если True, моделирует естественный старт движения курсора из случайной точки экрана.	True
raise_on_failure	bool	Если True, при таймауте выбрасывает RuntimeError.	False

Returns:

Type	Description
bool	True, если капча успешно решена, иначе False.

Raises:

Type	Description
RuntimeError	Если raise_on_failure=True и капча не была решена за время таймаута.

type_text(driver, selector, text, error_rate=0.05, speed_wpm=40.0, layout_error_rate=0.0, delayed_fix_rate=0.0, paste_threshold=None, paste_delay_before=(0.4, 1.0), paste_delay_after=(0.3, 0.8))

Имитирует ввод текста с опечатками Selenium.

Поддерживает адаптивный ввод: если длина текста превышает paste_threshold, текст вставляется целиком (Ctrl+V / Paste) с естественными паузами обдумывания.

Parameters:

Name	Type	Description	Default
driver	Any	Экземпляр Selenium WebDriver.	required
selector	str	CSS-селектор поля ввода.	required
text	str	Текст для ввода.	required
error_rate	float	Вероятность совершения опечатки (0.0 - 1.0).	0.05
speed_wpm	float	Скорость ввода в словах в минуту (WPM).	40.0
layout_error_rate	float	Вероятность ошибки переключения раскладки в начале ввода (0.0 - 1.0).	0.0
delayed_fix_rate	float	Вероятность отложенного исправления опечатки навигацией стрелками (0.0 - 1.0).	0.0
paste_threshold	int | None	Порог длины текста для вставки через буфер обмена. Если None, ввод всегда посимвольный.	None
paste_delay_before	tuple[float, float]	Диапазон паузы обдумывания перед вставкой из буфера (в секундах).	(0.4, 1.0)
paste_delay_after	tuple[float, float]	Диапазон паузы проверки после вставки из буфера (в секундах).	(0.3, 0.8)

options: members: - AntidetectConfig - BehavioralProfile - WindMouseGenerator - BezierCurveGenerator - JitterDelayGenerator - KeyboardTypoGenerator - apply_antidetect_nodriver - apply_antidetect_playwright - apply_antidetect_selenium - solve_cf_turnstile - detect_cf_turnstile - is_cf_turnstile_solved - async_move_mouse - async_click - async_type_text - async_scroll_to - async_human_sleep - move_mouse - click - type_text - scroll_to - human_sleep

Модуль telegram

chutils.telegram

AccessListManager

Менеджер белых и черных списков пользователей Telegram.

__init__(storage_path=None, allowed_ids=None, allowed_usernames=None, blocked_ids=None, blocked_usernames=None)

Инициализирует AccessListManager.

Parameters:

Name	Type	Description	Default
storage_path	str | Path | None	Опциональный путь к JSON-файлу для автосохранения списков.	None
allowed_ids	list[int] | None	Начальный белый список Telegram ID.	None
allowed_usernames	list[str] | None	Начальный белый список юзернеймов.	None
blocked_ids	list[int] | None	Начальный черный список Telegram ID.	None
blocked_usernames	list[str] | None	Начальный черный список юзернеймов.	None

allow_user(user_id_or_username)

Добавляет пользователя в белый список и убирает из черного.

Parameters:

Name	Type	Description	Default
user_id_or_username	int | str	ID пользователя Telegram или его юзернейм.	required

block_user(user_id_or_username)

Добавляет пользователя в черный список и убирает из белого.

Parameters:

Name	Type	Description	Default
user_id_or_username	int | str	ID пользователя Telegram или его юзернейм.	required

is_user_allowed(user_id=None, username=None)

Проверяет разрешения для пользователя.

Parameters:

Name	Type	Description	Default
user_id	int | None	Telegram ID пользователя.	None
username	str | None	Username пользователя.	None

Returns:

Type	Description
bool	True, если пользователь имеет доступ, иначе False.

load()

Загружает списки из JSON-файла.

remove_user(user_id_or_username)

Удаляет пользователя из белого и черного списков.

Parameters:

Name	Type	Description	Default
user_id_or_username	int | str	ID пользователя Telegram или его юзернейм.	required

save()

Атомарно сохраняет списки в JSON-файл.

AdminFilter

Bases: BaseFilter

Фильтр проверки прав администратора для aiogram 3.x.

Пример использования

@router.message(AdminFilter(admin_ids=[12345678])) async def admin_cmd(message: Message): await message.answer("Привет, админ!")

__call__(event, **kwargs) async

Проверяет, отправлено ли событие (Message/CallbackQuery) администратором.

Parameters:

Name	Type	Description	Default
event	Any	Объект Telegram Update / Message / CallbackQuery из aiogram.	required
**kwargs	Any	Дополнительные контекстные данные.	{}

Returns:

Type	Description
bool	True, если пользователь является администратором.

HealthCheckAlertBridge

Мост отправки Telegram-уведомлений при изменении статусов здоровья chutils.diagnostics.

on_health_check(service_name, status, details=None)

Обрабатывает событие проверки здоровья и отправляет алерт при проблемах.

Parameters:

Name	Type	Description	Default
service_name	str	Имя сервиса/компонента.	required
status	str	Статус (HEALTHY, DEGRADED, UNHEALTHY).	required
details	dict[str, Any] | None	Подробности ошибки или метрики.	None

Returns:

Type	Description
bool	True, если алерт был отправлен, иначе False.

PaginatorKeyboard

Управляющий класс пагинации динамических Inline-клавиатур.

total_pages property

Возвращает общее количество страниц.

__init__(items, per_page=5, callback_prefix='page')

Инициализирует PaginatorKeyboard.

Parameters:

Name	Type	Description	Default
items	Sequence[Any]	Полный список элементов.	required
per_page	int	Количество элементов на странице (по умолчанию 5).	5
callback_prefix	str	Префикс callback_data для навигации.	'page'

build_keyboard(page=1, item_button_factory=None, footer_buttons=None, buttons_per_row=1, as_aiogram=False)

Строит готовую клавиатуру со срезом элементов и пагинационной панелью.

Parameters:

Name	Type	Description	Default
page	int	Номер запрашиваемой страницы.	1
item_button_factory	Any	Опциональная функция приведения элемента к ButtonSpec.	None
footer_buttons	Sequence[ButtonSpec] | None	Дополнительные кнопки под панелью пагинации.	None
buttons_per_row	int	Ряды элементов страницы.	1
as_aiogram	bool	Возвращать ли aiogram InlineKeyboardMarkup.	False

Returns:

Type	Description
Any	Готовая клавиатура.

get_page_items(page=1)

Возвращает срез элементов для указанной страницы (1-indexed).

Parameters:

Name	Type	Description	Default
page	int	Номер страницы (1..total_pages).	1

Returns:

Type	Description
list[Any]	Список элементов текущей страницы.

SecretUserFilter

Bases: BaseFilter

Фильтр белых и черных списков пользователей для aiogram 3.x.

__call__(event, **kwargs) async

Проверяет разрешения пользователя на основе списков.

Parameters:

Name	Type	Description	Default
event	Any	Входящее событие Telegram (Message, CallbackQuery).	required
**kwargs	Any	Контекстные данные.	{}

Returns:

Type	Description
bool	True, если доступ разрешен.

TelegramLogHandler

Bases: Handler

Handler стандартного модуля logging для отправки критических логов в Telegram.

add_flapping_filter(patterns, threshold=3, failure_timeout=60.0)

Добавляет фильтр подавления кратковременных транзиентных ошибок (флаппинга).

Сообщения об ошибках, совпадающие с patterns, будут отсекаться до тех пор, пока количество последовательных сбоев не достигнет threshold или время сбоя не превысит failure_timeout.

Parameters:

Name	Type	Description	Default
patterns	str | Pattern[str] | Sequence[str | Pattern[str]]	Шаблоны ошибок (подстрока, регулярное выражение или список таковых).	required
threshold	int	Порог последовательных ошибок до отправки алерта в Telegram.	3
failure_timeout	float	Таймаут сбоя в секундах до отправки алерта.	60.0

Returns:

Type	Description
TelegramLogHandler	Текущий экземпляр обработчика.

emit(record)

Отправляет отформатированную запись лога в Telegram.

Parameters:

Name	Type	Description	Default
record	LogRecord	Запись лога logging.LogRecord.	required

TelegramLoggingMiddleware

Bases: BaseMiddleware

Middleware контекстного логирования и измерений времени выполнения для aiogram 3.x.

__call__(handler, event, data) async

Обрабатывает события и логирует контекст в цепочке Middleware.

Parameters:

Name	Type	Description	Default
handler	Callable[[Any, dict[str, Any]], Any]	Следующий хэндлер в цепочке.	required
event	Any	Входящее событие Telegram.	required
data	dict[str, Any]	Контекстные данные события.	required

Returns:

Type	Description
Any	Результат выполнения хэндлера.

TelegramRateLimiter

Движок ограничений вызовов (Rate Limiter) для Telegram-ботов.

__init__(rate=1, per=1.0)

Инициализирует TelegramRateLimiter.

Parameters:

Name	Type	Description	Default
rate	int	Максимальное количество допустимых вызовов.	1
per	float	Период времени в секундах.	1.0

check_rate_limit(key)

Проверяет превышение лимита вызовов для ключа.

Parameters:

Name	Type	Description	Default
key	str	Уникальный идентификатор сущности (user_id / chat_id).	required

Returns:

Type	Description
tuple[bool, float]	Кортеж (is_limited, wait_sec), где is_limited - флаг превышения, wait_sec - секунд до разблокировки.

TelegramThrottlingMiddleware

Bases: BaseMiddleware

Middleware отслеживания и предотвращения спама (Throttling) для aiogram 3.x.

__call__(handler, event, data) async

Обрабатывает входящее событие в цепочке Middleware.

Parameters:

Name	Type	Description	Default
handler	Callable[[Any, dict[str, Any]], Any]	Следующий хэндлер в цепочке.	required
event	Any	Входящее событие Telegram.	required
data	dict[str, Any]	Контекстные данные события.	required

Returns:

Type	Description
Any	Результат выполнения хэндлера.

trace_telegram_update

Контекстный менеджер и декоратор трейсинга и логирования Telegram-апдейтов.

__call__(func)

Оборачивает функцию декоратором трейсинга.

Parameters:

Name	Type	Description	Default
func	F	Целевая функция.	required

Returns:

Type	Description
F	Обернутая функция.

__init__(event=None, logger_instance=None)

Инициализирует trace_telegram_update.

Parameters:

Name	Type	Description	Default
event	Any	Входящее событие/апдейт Telegram.	None
logger_instance	Any	Опциональный кастомный логгер.	None

admin_only(admin_ids=None, admin_usernames=None, is_admin_func=None, refusal_text='⛔ Доступ запрещен: требуется статус администратора', silent=False, raise_on_denied=False)

Декоратор для ограничения доступа к синхронным и асинхронным хэндлерам Telegram-ботов.

Parameters:

Name	Type	Description	Default
admin_ids	list[int] | None	Разрешенные Telegram ID.	None
admin_usernames	list[str] | None	Разрешенные юзернеймы.	None
is_admin_func	Callable[[int | None, str | None], bool] | None	Кастомный предикат проверки.	None
refusal_text	str | None	Текст сообщения при отказе в доступе.	'⛔ Доступ запрещен: требуется статус администратора'
silent	bool	Если True, тихо игнорировать неавторизованные запросы.	False
raise_on_denied	bool	Если True, выбрасывать TelegramAccessDeniedError.	False

Returns:

Type	Description
Callable[[F], F]	Обернутый хэндлер.

allowed_only(manager=None, allowed_ids=None, allowed_usernames=None, blocked_ids=None, blocked_usernames=None, refusal_text='⛔ У вас нет доступа к этой функции', silent=False, raise_on_denied=False)

Декоратор ограничения доступа по белым и черным спискам.

Parameters:

Name	Type	Description	Default
manager	AccessListManager | None	Готовый экземпляр AccessListManager.	None
allowed_ids	list[int] | None	Белый список Telegram ID.	None
allowed_usernames	list[str] | None	Белый список юзернеймов.	None
blocked_ids	list[int] | None	Черный список Telegram ID.	None
blocked_usernames	list[str] | None	Черный список юзернеймов.	None
refusal_text	str | None	Сообщение об отказе.	'⛔ У вас нет доступа к этой функции'
silent	bool	Если True, отбрасывать запросы без вывода ответа.	False
raise_on_denied	bool	Если True, выбрасывать TelegramAccessDeniedError.	False

Returns:

Type	Description
Callable[[F], F]	Обернутая функция.

build_inline_keyboard(buttons, buttons_per_row=2, as_aiogram=False)

Создает сетку Inline-клавиатуры Telegram из списка кнопок.

Parameters:

Name	Type	Description	Default
buttons	Sequence[ButtonSpec]	Список спецификаций кнопок (кортежи или словари).	required
buttons_per_row	int	Количество кнопок в одном ряду (по умолчанию 2).	2
as_aiogram	bool	Если True, возвращает aiogram InlineKeyboardMarkup (при наличии aiogram).	False

Returns:

Type	Description
Any	Словарь вида {'inline_keyboard': [...]} или aiogram InlineKeyboardMarkup.

download_user_file(bot, file_id, target_dir, custom_filename=None, allow_unsafe_path=False, max_size_bytes=None) async

Безопасно выкачивает файл из Telegram по file_id в указанную директорию target_dir.

Parameters:

Name	Type	Description	Default
bot	Any	Экземпляр бота (aiogram.Bot или аналогичный с методом get_file/download_file) или bot_token (str).	required
file_id	str	Уникальный идентификатор файла в Telegram API.	required
target_dir	str | Path	Целевая папка для сохранения.	required
custom_filename	str | None	Желаемое имя файла. Если не указано, используется имя из Telegram или file_id.	None
allow_unsafe_path	bool	Если True, отключает строгую проверку Path Traversal (записывается предупреждение).	False
max_size_bytes	int | None	Максимальный допустимый размер файла в байтах.	None

Returns:

Type	Description
Path	Абсолютный путь (Path) к сохраненному файлу.

Raises:

Type	Description
PathTraversalError	При попытке выхода за границы target_dir (когда allow_unsafe_path=False).
ChutilsException	При превышении max_size_bytes или ошибке загрузки.

escape_html(text)

Экранирует специальные символы в тексте для парс-режима HTML в Telegram.

Parameters:

Name	Type	Description	Default
text	str	Исходный текст.	required

Returns:

Type	Description
str	Экранированный HTML текст.

escape_markdown(text, version=2)

Экранирует специальные символы в тексте для парс-режима Markdown в Telegram.

Parameters:

Name	Type	Description	Default
text	str	Исходный текст.	required
version	int	Версия синтаксиса Markdown (1 или 2, по умолчанию: 2).	2

Returns:

Type	Description
str	Экранированный текст.

is_admin(user_id=None, username=None, admin_ids=None, admin_usernames=None, is_admin_func=None)

Проверяет, является ли пользователь администратором.

Если явные списки admin_ids / admin_usernames не заданы, считывает их из конфигурации chutils (секция 'Telegram', ключи 'admin_ids' / 'admin_usernames').

Parameters:

Name	Type	Description	Default
user_id	int | None	Telegram ID пользователя.	None
username	str | None	Telegram username пользователя.	None
admin_ids	list[int] | None	Список разрешенных Telegram ID администраторов.	None
admin_usernames	list[str] | None	Список разрешенных username администраторов.	None
is_admin_func	Callable[[int | None, str | None], bool] | None	Кастомный предикат проверки.	None

Returns:

Type	Description
bool	True, если пользователь является администратором, иначе False.

send_alert(title, message, bot_token=None, chat_id=None, level='ERROR')

Отправляет кастомное алерты-уведомление администраторам в Telegram.

Parameters:

Name	Type	Description	Default
title	str	Заголовок алерта.	required
message	str	Текст сообщения.	required
bot_token	str | None	Опциональный токен бота.	None
chat_id	int | str | None	Опциональный ID чата администратора.	None
level	str	Уровень алерта (INFO, WARNING, ERROR, CRITICAL).	'ERROR'

Returns:

Type	Description
bool	True при успешной отправке, иначе False.

send_telegram_file(bot, chat_id, file_path, caption=None, parse_mode=None, allow_unsafe_path=False, base_dir=None) async

Безопасно отправляет файл или папку (с авто-упаковкой в ZIP) в Telegram.

Parameters:

Name	Type	Description	Default
bot	Any	Экземпляр бота (aiogram.Bot) или raw bot_token (str).	required
chat_id	int | str	Идентификатор чата или получателя.	required
file_path	str | Path	Путь к отправляемому файлу или директории.	required
caption	str | None	Опциональная подпись к файлу (автоматически обрезается под 1024 символа).	None
parse_mode	str | None	Режим разметки подписи ('HTML', 'MarkdownV2', etc.).	None
allow_unsafe_path	bool	Если True, отключает проверку Path Traversal.	False
base_dir	str | Path | None	Базовая директория для проверки выхода за границы.	None

Returns:

Type	Description
Any	Объект отправленного сообщения Telegram API.

Raises:

Type	Description
PathTraversalError	Если файл находится за пределами base_dir.
ChutilsException	При превышении лимита 50 МБ или ошибках отправки.

smart_truncate(text, max_length=4096, suffix='...')

Безопасно обрезает текст до max_length с закрытием кодовых блоков (```).

Parameters:

Name	Type	Description	Default
text	str	Исходный текст сообщения.	required
max_length	int	Максимальная допустимая длина (по умолчанию 4096).	4096
suffix	str	Суффикс для обрезанного сообщения.	'...'

Returns:

Type	Description
str	Обрезанный валидный текст.

split_message(text, max_length=4096, mode='line')

Разбивает длинный текст на список валидных сообщений не превышающих max_length.

Parameters:

Name	Type	Description	Default
text	str	Исходный длинный текст.	required
max_length	int	Максимальный размер одного сообщения (по умолчанию: 4096).	4096
mode	Literal['paragraph', 'line', 'word', 'char']	Стратегия разбиения: - 'paragraph': сплит по абзацам (\n\n) - 'line': сплит по строкам (\n, по умолчанию) - 'word': сплит по словам (пробелам) - 'char': жесткий сплит посимвольно	'line'

Returns:

Type	Description
list[str]	Список чанков текста.

tg_rate_limit(rate=1, per=1.0, scope='user_id', warning_text='⏱ Пожалуйста, подождите {wait_sec} сек. перед повторной отправкой.', silent=False, raise_on_limit=False)

Декоратор ограничения частоты запросов для Telegram-ботов.

Parameters:

Name	Type	Description	Default
rate	int	Количество разрешенных запросов.	1
per	float	Временное окно в секундах.	1.0
scope	str	Область ограничения: 'user_id', 'chat_id' или 'user_and_chat'.	'user_id'
warning_text	str | None	Шаблон предупреждения. Поддерживает форматирование {wait_sec}.	'⏱ Пожалуйста, подождите {wait_sec} сек. перед повторной отправкой.'
silent	bool	Если True, отбрасывать запросы без вывода предупреждения.	False
raise_on_limit	bool	Если True, выбрасывать RateLimitExceededError при флуде.	False

Returns:

Type	Description
Callable[[F], F]	Обернутая функция-хэндлер.

options: members: - TelegramLogHandler - download_user_file - send_telegram_file - build_inline_keyboard - PaginatorKeyboard - HealthCheckAlertBridge

Модуль logger

chutils.logger

Модуль для настройки логирования.

Этот пакет разделен на модули для соблюдения SRP: - core: Основной класс логгера и setup_logger. - masking: Фильтрация секретов. - formatters: Форматирование (Text, JSON). - handlers: Обработчики файлов (ротация, сжатие).

options: members: - setup_logger - setup_logger_from_config - ChutilsLogger - SafeTimedRotatingFileHandler - SafeRotatingFileHandler - CompressingRotatingFileHandler - CompressingTimedRotatingFileHandler

Модуль scraping.testing (Интерактивная разметка DOM, автотестирование и моки)

chutils.scraping.testing

Модуль инструментов автотестирования скраперов и парсеров (chutils.scraping.testing).

CORE_DOM_HELPERS_JS = '\nfunction isElementVisible(el) {\n if (!el || !(el instanceof Element)) return false;\n try {\n if (el.offsetParent === null && el.offsetWidth === 0 && el.offsetHeight === 0) {\n return false;\n }\n const style = window.getComputedStyle(el);\n if (style.display === \'none\' || style.visibility === \'hidden\' || parseFloat(style.opacity || \'1\') < 0.05) {\n return false;\n }\n const rect = el.getBoundingClientRect();\n if (rect.width <= 0 || rect.height <= 0) {\n return false;\n }\n return true;\n } catch (e) {\n return false;\n }\n}\n\nfunction queryAllSafe(sel) {\n try {\n return Array.from(document.querySelectorAll(sel));\n } catch (err) {\n const containsMatch = sel.match(/^(.*?):contains\\([\'"](.*?)[\'"]\\)(.*)$/);\n if (containsMatch) {\n const [, base, text] = containsMatch;\n const candidates = Array.from(document.querySelectorAll(base || \'*\'));\n return candidates.filter(el => (el.textContent || \'\').includes(text));\n }\n const hasTextMatch = sel.match(/^(.*?):has-text\\([\'"](.*?)[\'"]\\)(.*)$/);\n if (hasTextMatch) {\n const [, base, text] = hasTextMatch;\n const candidates = Array.from(document.querySelectorAll(base || \'*\'));\n return candidates.filter(el => (el.textContent || \'\').includes(text));\n }\n throw err;\n }\n}\n\nfunction getViewportInfo() {\n const w = window.innerWidth;\n const h = window.innerHeight;\n let bp = \'compact\';\n if (w > 1440) bp = \'desktop_wide\';\n else if (w <= 1024) bp = \'mobile\';\n return {\n width: w,\n height: h,\n device_pixel_ratio: window.devicePixelRatio || 1,\n breakpoint: bp\n };\n}\n\nfunction getCssSelector(el) {\n if (!(el instanceof Element)) return \'\';\n if (el.id && !el.id.match(/^[:\\d]|\\s/)) {\n const idSel = \'#\' + CSS.escape(el.id);\n if (document.querySelectorAll(idSel).length === 1) return idSel;\n }\n\n const ariaLabel = el.getAttribute(\'aria-label\');\n if (ariaLabel && ariaLabel.trim()) {\n const sel = `${el.tagName.toLowerCase()}[aria-label="${CSS.escape(ariaLabel.trim())}"]`;\n if (document.querySelectorAll(sel).length === 1) return sel;\n }\n\n for (const attr of [\'data-testid\', \'data-test-id\', \'data-test\', \'data-cy\', \'role\', \'name\', \'placeholder\']) {\n const val = el.getAttribute(attr);\n if (val) {\n const sel = `${el.tagName.toLowerCase()}[${attr}="${CSS.escape(val)}"]`;\n if (document.querySelectorAll(sel).length === 1) return sel;\n }\n }\n\n const tag = el.tagName.toLowerCase();\n if (tag.includes(\'-\')) {\n if (document.querySelectorAll(tag).length === 1) return tag;\n }\n\n const path = [];\n let cur = el;\n while (cur && cur.nodeType === Node.ELEMENT_NODE && cur !== document.body) {\n let selector = cur.tagName.toLowerCase();\n if (cur.className && typeof cur.className === \'string\') {\n const classes = cur.className.trim().split(/\\s+/)\n .filter(c => c && !c.startsWith(\'ng-\') && !c.includes(\':\') && !c.match(/^\\d/));\n if (classes.length > 0) {\n selector += \'.\' + classes.slice(0, 2).map(c => CSS.escape(c)).join(\'.\');\n }\n }\n path.unshift(selector);\n try {\n const fullSel = path.join(\' > \');\n if (document.querySelectorAll(fullSel).length === 1) return fullSel;\n } catch (e) {}\n if (path.length >= 3) break;\n cur = cur.parentElement;\n }\n\n return path.join(\' > \') || el.tagName.toLowerCase();\n}\n\nfunction getAlternativeSelectors(el) {\n if (!(el instanceof Element)) return [];\n const alts = [];\n const tag = el.tagName.toLowerCase();\n const aria = el.getAttribute(\'aria-label\');\n if (aria) alts.push(`${tag}[aria-label*="${CSS.escape(aria)}" i]`);\n const role = el.getAttribute(\'role\');\n if (role) alts.push(`${tag}[role="${CSS.escape(role)}"]`);\n if (el.className && typeof el.className === \'string\') {\n const cls = el.className.trim().split(/\\s+/).find(c => !c.startsWith(\'ng-\'));\n if (cls) alts.push(`${tag}.${CSS.escape(cls)}`);\n }\n if (el.parentElement) {\n const ptag = el.parentElement.tagName.toLowerCase();\n alts.push(`${ptag} ${tag}`);\n }\n return [...new Set(alts)].slice(0, 4);\n}\n\nfunction checkDuplicates(selector) {\n try {\n const matches = document.querySelectorAll(selector);\n return {\n count: matches.length,\n has_duplicates: matches.length > 1\n };\n } catch (e) {\n return { count: 1, has_duplicates: false };\n }\n}\n\nfunction getContainerScope(el, customScopes) {\n if (!(el instanceof Element)) return null;\n const defaultScopes = [\n \'dialog\',\n \'[role="dialog"]\',\n \'[role="alertdialog"]\',\n \'[role="menu"]\',\n \'.modal\',\n \'.cdk-overlay-pane\',\n \'mat-dialog-container\',\n \'.mat-mdc-menu-panel\',\n \'.mat-mdc-select-panel\'\n ];\n const scopes = (customScopes && customScopes.length > 0) ? customScopes : defaultScopes;\n for (const scopeSel of scopes) {\n try {\n const container = el.closest(scopeSel);\n if (container) {\n return scopeSel;\n }\n } catch (e) {}\n }\n return null;\n}\n' module-attribute

Универсальные вспомогательные функции JavaScript для работы с DOM.

DOMActionRecorderHUD = DOMActionRecorder module-attribute

Алиас для DOMActionRecorder.

PAGE_META_SCRIPT = '\nJSON.stringify((() => {\n return {\n url: window.location.href,\n title: document.title,\n ready_state: document.readyState\n };\n})())\n' module-attribute

JS-скрипт получения базовых метаданных страницы (URL, title, readyState).

POLL_RECORDED_ACTIONS_SCRIPT = "\nJSON.stringify((() => {\n let vp = null;\n try {\n const w = window.innerWidth;\n const h = window.innerHeight;\n let bp = 'compact';\n if (w > 1440) bp = 'desktop_wide';\n else if (w <= 1024) bp = 'mobile';\n vp = {\n width: w,\n height: h,\n device_pixel_ratio: window.devicePixelRatio || 1,\n breakpoint: bp\n };\n } catch (e) {}\n\n return {\n finished: Boolean(window.__chutilsRecordFinished),\n actions_count: (window.__chutilsRecordedActions || []).length,\n actions: window.__chutilsRecordedActions || [],\n checklist: window.__chutilsChecklist || [],\n page_url: window.location.href,\n page_title: document.title,\n session_viewport: vp\n };\n})())\n" module-attribute

JS-скрипт опроса текущего состояния записи действий.

DOMActionRecorder

Интерактивный регистратор действий пользователя в браузере с плавающим HUD.

Позволяет визуально размечать шаги сценариев на живых веб-страницах, проверять селекторы, отслеживать мутации DOM и формировать подробные структурированные отчеты для нейроагентов и тестов.

__init__(checklist_items=None, widget_title='Запись действий DOM', container_selectors=None, custom_matcher_js=None)

Инициализация регистратора.

Parameters:

Name	Type	Description	Default
checklist_items	Sequence[dict[str, Any] | RecordedChecklistItem] | None	Список пунктов чеклиста с id, label, hints.	None
widget_title	str	Заголовок, отображаемый в шапке HUD-виджета.	'Запись действий DOM'
container_selectors	list[str] | None	Дополнительные селекторы модальных окон/панелей.	None
custom_matcher_js	str | None	Кастомный JS-код функции сопоставления с чеклистом.	None

build_report(raw_data, session_name='default', target_name='web')

Преобразует сырые данные из браузера в типизированный отчет DOMActionSessionReport.

Parameters:

Name	Type	Description	Default
raw_data	dict[str, Any]	Сырой словарь, возвращенный методом poll().	required
session_name	str	Название сессии или имя профиля браузера.	'default'
target_name	str	Название целевой веб-системы или сайта.	'web'

Returns:

Type	Description
DOMActionSessionReport	Структурированный Pydantic-объект отчета.

export_report(report, json_path, md_path=None)

Экспортирует структурированный отчет в JSON и Markdown.

Parameters:

Name	Type	Description	Default
report	DOMActionSessionReport	Объект отчета DOMActionSessionReport.	required
json_path	Path	Путь к целевому файлу JSON.	required
md_path	Path | None	Путь к целевому файлу Markdown (по умолчанию .md рядом с JSON).	None

Returns:

Type	Description
tuple[Path, Path | None]	Кортеж (путь к JSON, путь к Markdown).

generate_markdown_report(report)

Формирует подробный Markdown-отчет для чтения разработчиками и LLM-агентами.

Parameters:

Name	Type	Description	Default
report	DOMActionSessionReport	Объект отчета DOMActionSessionReport.	required

Returns:

Type	Description
str	Строка в формате Markdown.

inject(tab) async

Внедряет перехватчик действий и плавающий HUD в страницу браузера.

Parameters:

Name	Type	Description	Default
tab	Any	Объект вкладки браузера (nodriver Tab, Playwright Page или аналогичный с асинхронным методом evaluate).	required

Returns:

Type	Description
bool	True, если скрипт успешно выполнен.

is_finished(tab) async

Проверяет, нажал ли пользователь кнопку завершения в HUD виджете.

Parameters:

Name	Type	Description	Default
tab	Any	Вкладка браузера.	required

Returns:

Type	Description
bool	True, если сессия завершена.

poll(tab) async

Опрашивает текущий лог действий и состояние HUD из браузера.

Parameters:

Name	Type	Description	Default
tab	Any	Вкладка браузера с методом evaluate.	required

Returns:

Type	Description
dict[str, Any]	Словарь с зафиксированными действиями, состоянием чеклиста и вьюпорта.

wait_for_finish(tab, poll_interval=0.5, timeout=None, on_action=None, session_name='default', target_name='web') async

Асинхронно ожидает нажатия кнопки завершения в HUD виджете браузера.

Parameters:

Name	Type	Description	Default
tab	Any	Вкладка браузера.	required
poll_interval	float	Интервал опроса в секундах.	0.5
timeout	float | None	Максимальное время ожидания в секундах (None для неограниченного).	None
on_action	Callable[[RecordedAction], None] | None	Опциональный колбэк при фиксации нового действия.	None
session_name	str	Имя сессии для итогового отчета.	'default'
target_name	str	Имя цели для итогового отчета.	'web'

Returns:

Type	Description
DOMActionSessionReport	Итоговый объект отчета DOMActionSessionReport.

Raises:

Type	Description
TimeoutError	При истечении таймаута до завершения пользователем.

DOMActionSessionReport

Bases: BaseModel

Итоговый структурированный отчет интерактивной сессии записи действий.

Attributes:

Name	Type	Description
timestamp	str	Временная метка сессии ISO 8601.
session_name	str	Имя профиля или сессии.
target_name	str	Имя целевого сайта или провайдера.
page_url	str	URL целевой страницы.
page_title	str	Заголовок веб-страницы.
total_actions	int	Общее число зафиксированных действий.
session_viewport	ViewportInfo | None	Разрешение вьюпорта браузера.
actions	list[RecordedAction]	Список зафиксированных действий.
checklist	list[RecordedChecklistItem]	Список пунктов чеклиста с результатами.
discovered_selectors	dict[str, list[str]]	Словарь обнаруженных селекторов по категориям.
summary_markdown	str	Итоговый сгенерированный Markdown-отчет.

DOMMutationDiff

Bases: BaseModel

Структурированная дельта мутаций DOM после действия пользователя.

Attributes:

Name	Type	Description
spawned_containers	list[str]	Селекторы появившихся контейнеров (оверлеи, диалоги, панели).
appeared_elements	list[str]	Селекторы новых интерактивных элементов внутри контейнера.
attribute_changes	list[str]	Измененные классы и aria-* атрибуты.

LiveBrowserSession

Контекстный менеджер изолированной сессии реального браузера.

Создает временный каталог профиля (user_data_dir), регистрирует запущенные процессы браузера и гарантирует их принудительное уничтожение при выходе или аварийном завершении приложения через chutils.lifecycle.

is_active property

Возвращает флаг активности текущей сессии.

__aenter__() async

Вход в асинхронный контекстный менеджер.

__aexit__(exc_type, exc_val, exc_tb) async

Выход из асинхронного контекстного менеджера.

__enter__()

Вход в контекстный менеджер.

__exit__(exc_type, exc_val, exc_tb)

Выход из контекстного менеджера.

__init__(browser_name='chromium', user_data_dir=None, auto_cleanup_dir=True, keep_profile_on_failure=False)

Инициализирует сессию живого браузера.

Parameters:

Name	Type	Description	Default
browser_name	str	Название браузера (например, "chromium", "chrome", "firefox").	'chromium'
user_data_dir	Path | str | None	Пользовательский путь к каталогу профиля. Если None, создается временный каталог с префиксом chutils_live_browser_.	None
auto_cleanup_dir	bool	Автоматически удалять каталог профиля при очистке.	True
keep_profile_on_failure	bool	Не удалять профиль при возникновении исключения в контекстном менеджере (для отладки упавших тестов).	False

cleanup()

Принудительно останавливает все отслеживаемые процессы и удаляет профиль.

track_process(process_or_pid)

Регистрирует процесс браузера для отслеживания и гарантированного teardown.

Parameters:

Name	Type	Description	Default
process_or_pid	Any	Объект процесса (subprocess.Popen, nodriver Browser, playwright process) или числовой PID.	required

LocalTestServer

Локальный тестовый HTTP-сервер песочницы для отдачи HTML/JSON браузерам в тестах.

is_running property

Проверяет, запущен ли сервер.

port property

Возвращает актуальный порт работающего сервера.

__aenter__() async

Вход в асинхронный контекстный менеджер.

__aexit__(exc_type, exc_val, exc_tb) async

Выход из асинхронного контекстного менеджера.

__enter__()

Вход в синхронный контекстный менеджер.

__exit__(exc_type, exc_val, exc_tb)

Выход из синхронного контекстного менеджера.

__init__(host='127.0.0.1', port=0)

Инициализирует сервер.

Parameters:

Name	Type	Description	Default
host	str	Хост прослушивания (по умолчанию 127.0.0.1).	'127.0.0.1'
port	int	Порт (0 для авто-выбора свободного порта ОС).	0

fetch(path_or_url, method='GET', headers=None, data=None)

Выполняет прямой HTTP-запрос к серверу в обход системных прокси.

Parameters:

Name	Type	Description	Default
path_or_url	str	Путь маршрута (например, '/page') или полный URL.	required
method	str	Метод HTTP (GET, POST и т.д.).	'GET'
headers	Mapping[str, str] | None	Опциональные HTTP-заголовки.	None
data	bytes | None	Опциональное тело запроса в байтах.	None

Returns:

Type	Description
TestResponse	Экземпляр TestResponse с кодом, заголовками и телом ответа.

serve_html(path, html, content_type='text/html; charset=utf-8')

Регистрирует HTML-маршрут.

Parameters:

Name	Type	Description	Default
path	str	Путь URL (например, '/index').	required
html	str	HTML-содержимое.	required
content_type	str	Заголовок Content-Type.	'text/html; charset=utf-8'

Returns:

Type	Description
str	Абсолютный URL зарегистрированного маршрута.

serve_json(path, data)

Регистрирует маршрут, отдающий JSON данные.

Parameters:

Name	Type	Description	Default
path	str	Путь URL.	required
data	object	Данные для сериализации в JSON.	required

Returns:

Type	Description
str	Абсолютный URL зарегистрированного маршрута.

start()

Запускает HTTP-сервер в фоновом потоке.

Returns:

Type	Description
Self	Экземпляр сервера.

stop()

Останавливает сервер и фоновый поток.

url_for(path)

Формирует абсолютный URL для указанного относительного пути.

Parameters:

Name	Type	Description	Default
path	str	Путь маршрута (например, '/page').	required

Returns:

Type	Description
str	Полный HTTP URL на локальном сервере.

MockNodriverElement

Мок HTML-элемента в стиле nodriver.Element.

attrs property

Возвращает словарь атрибутов элемента.

tag property

Возвращает имя тега элемента.

text property

Возвращает текстовое содержимое элемента.

__init__(node)

Инициализирует мок элемента.

Parameters:

Name	Type	Description	Default
node	DOMNode	Внутренний узел DOMNode.	required

click() async

Имитирует клик по элементу (no-op).

select(selector) async

Находит первый дочерний элемент по CSS-селектору.

Parameters:

Name	Type	Description	Default
selector	str	CSS-селектор.	required

Returns:

Type	Description
MockNodriverElement | None	Экземпляр MockNodriverElement или None.

select_all(selector) async

Находит все дочерние элементы по CSS-селектору.

Parameters:

Name	Type	Description	Default
selector	str	CSS-селектор.	required

Returns:

Type	Description
list[MockNodriverElement]	Список найденных элементов MockNodriverElement.

send_keys(text) async

Имитирует ввод текста в элемент.

Parameters:

Name	Type	Description	Default
text	str	Вводимый текст.	required

MockNodriverTab

Мок вкладки браузера nodriver.Tab для автономного тестирования парсеров.

__init__(html, url='about:blank')

Инициализирует мок вкладки nodriver.

Parameters:

Name	Type	Description	Default
html	str	HTML-содержимое страницы.	required
url	str	URL страницы.	'about:blank'

evaluate(expression) async

Имитирует выполнение простого JavaScript выражения.

Parameters:

Name	Type	Description	Default
expression	str	Строка выражения (например, document.title).	required

Returns:

Type	Description
object	Результат выполнения выражения.

find(text) async

Находит наиболее специфичный элемент, содержащий указанный текст.

Parameters:

Name	Type	Description	Default
text	str	Искомая подстрока.	required

Returns:

Type	Description
MockNodriverElement | None	Найденный элемент MockNodriverElement или None.

get_content() async

Возвращает исходный HTML страницы.

Returns:

Type	Description
str	HTML-код страницы.

select(selector) async

Находит первый элемент по CSS-селектору.

Parameters:

Name	Type	Description	Default
selector	str	CSS-селектор.	required

Returns:

Type	Description
MockNodriverElement | None	Экземпляр MockNodriverElement или None.

select_all(selector) async

Находит все элементы по CSS-селектору.

Parameters:

Name	Type	Description	Default
selector	str	CSS-селектор.	required

Returns:

Type	Description
list[MockNodriverElement]	Список элементов MockNodriverElement.

sleep(seconds=0.0) async

Имитирует ожидание (no-op в тестах).

Parameters:

Name	Type	Description	Default
seconds	float	Количество секунд.	0.0

MockPlaywrightLocator

Мок Playwright Locator, инкапсулирующий один или несколько найденных узлов.

first property

Возвращает первый элемент выборки.

Returns:

Type	Description
MockPlaywrightLocator	MockPlaywrightLocator с первым узлом.

last property

Возвращает последний элемент выборки.

Returns:

Type	Description
MockPlaywrightLocator	MockPlaywrightLocator с последним узлом.

__init__(nodes)

Инициализирует локатор списком узлов.

Parameters:

Name	Type	Description	Default
nodes	list[DOMNode]	Список узлов DOMNode.	required

all() async

Возвращает список локаторов для каждого отдельного элемента.

Returns:

Type	Description
list[MockPlaywrightLocator]	Список MockPlaywrightLocator.

click() async

Имитирует клик (no-op).

count() async

Возвращает количество найденных элементов.

Returns:

Type	Description
int	Число элементов в выборке локатора.

fill(value) async

Имитирует заполнение поля значением.

Parameters:

Name	Type	Description	Default
value	str	Вводимое значение.	required

get_attribute(name) async

Возвращает значение атрибута первого элемента.

Parameters:

Name	Type	Description	Default
name	str	Имя атрибута.	required

Returns:

Type	Description
str | None	Значение атрибута или None.

inner_text() async

Возвращает видимый текст первого элемента.

Returns:

Type	Description
str	Текст элемента.

is_visible() async

Проверяет видимость элемента.

Returns:

Type	Description
bool	True, если элемент присутствует в DOM.

locator(selector)

Возвращает вложенный локатор относительно текущих узлов.

Parameters:

Name	Type	Description	Default
selector	str	CSS-селектор.	required

Returns:

Type	Description
MockPlaywrightLocator	Экземпляр MockPlaywrightLocator.

nth(index)

Возвращает n-й элемент выборки.

Parameters:

Name	Type	Description	Default
index	int	Индекс элемента (0-based).	required

Returns:

Type	Description
MockPlaywrightLocator	MockPlaywrightLocator для n-го узла.

text_content() async

Возвращает текстовое содержимое элемента.

Returns:

Type	Description
str | None	Текст элемента или None.

MockPlaywrightPage

Мок объекта playwright.async_api.Page для автономного тестирования парсеров.

__init__(html, url='about:blank')

Инициализирует мок страницы Playwright.

Parameters:

Name	Type	Description	Default
html	str	HTML-содержимое страницы.	required
url	str	URL страницы.	'about:blank'

content() async

Возвращает HTML-код страницы.

Returns:

Type	Description
str	Исходный HTML.

evaluate(expression, arg=None) async

Имитирует выполнение простого JS выражения.

Parameters:

Name	Type	Description	Default
expression	str	Выражение JS.	required
arg	object	Опциональный аргумент.	None

Returns:

Type	Description
object	Результат выражения.

goto(url) async

Имитирует переход по URL.

Parameters:

Name	Type	Description	Default
url	str	Целевой адрес.	required

locator(selector)

Возвращает объект Locator по указанному селектору.

Parameters:

Name	Type	Description	Default
selector	str	CSS-селектор.	required

Returns:

Type	Description
MockPlaywrightLocator	Экземпляр MockPlaywrightLocator.

title() async

Возвращает заголовок страницы (title).

Returns:

Type	Description
str	Текст из тега title или пустая строка.

MockSeleniumDriver

Синхронный мок Selenium WebDriver для автономного тестирования.

page_source property

Возвращает исходный код страницы.

Returns:

Type	Description
str	HTML-код страницы.

title property

Возвращает заголовок страницы.

Returns:

Type	Description
str	Текст из тега title или пустая строка.

__init__(html, url='about:blank')

Инициализирует мок драйвера Selenium.

Parameters:

Name	Type	Description	Default
html	str	HTML-код страницы.	required
url	str	Начальный URL.	'about:blank'

execute_script(script, *args)

Имитирует выполнение скрипта.

Parameters:

Name	Type	Description	Default
script	str	Строка JavaScript.	required
args	object	Передаваемые аргументы.	()

Returns:

Type	Description
object	Результат выполнения.

find_element(by, value)

Находит первый элемент на странице.

Parameters:

Name	Type	Description	Default
by	str	Стратегия поиска (например, 'css selector', 'id').	required
value	str	Селектор.	required

Returns:

Type	Description
MockSeleniumElement	Найденный элемент MockSeleniumElement.

Raises:

Type	Description
ValueError	Если элемент не найден.

find_elements(by, value)

Находит все подходящие элементы на странице.

Parameters:

Name	Type	Description	Default
by	str	Стратегия поиска.	required
value	str	Селектор.	required

Returns:

Type	Description
list[MockSeleniumElement]	Список найденных элементов MockSeleniumElement.

get(url)

Имитирует переход по URL.

Parameters:

Name	Type	Description	Default
url	str	Целевой URL.	required

MockSeleniumElement

Мок веб-элемента Selenium WebElement.

tag_name property

Возвращает имя тега элемента.

Returns:

Type	Description
str	Имя тега.

text property

Возвращает видимый текст элемента.

Returns:

Type	Description
str	Текст элемента.

__init__(node)

Инициализирует мок элемента Selenium.

Parameters:

Name	Type	Description	Default
node	DOMNode	Внутренний узел DOMNode.	required

click()

Имитирует клик по элементу.

find_element(by, value)

Находит первый вложенный элемент по указанному селектору.

Parameters:

Name	Type	Description	Default
by	str	Стратегия поиска (css selector, id, xpath и т.д.).	required
value	str	Значение селектора.	required

Returns:

Type	Description
MockSeleniumElement	Экземпляр MockSeleniumElement.

Raises:

Type	Description
ValueError	Если элемент не найден.

find_elements(by, value)

Находит все вложенные элементы по указанному селектору.

Parameters:

Name	Type	Description	Default
by	str	Стратегия поиска.	required
value	str	Значение селектора.	required

Returns:

Type	Description
list[MockSeleniumElement]	Список MockSeleniumElement.

get_attribute(name)

Возвращает значение атрибута.

Parameters:

Name	Type	Description	Default
name	str	Имя атрибута.	required

Returns:

Type	Description
str | None	Значение атрибута или None.

is_displayed()

Проверяет отображение элемента.

Returns:

Type	Description
bool	True, если элемент присутствует.

send_keys(keys)

Имитирует ввод текста в элемент.

Parameters:

Name	Type	Description	Default
keys	str	Вводимый текст.	required

RecordedAction

Bases: BaseModel

Зафиксированное действие пользователя с элементом интерфейса.

Attributes:

Name	Type	Description
action_id	int	Порядковый номер действия в сессии.
event_type	str	Тип события браузера ("click", "input", "change", "keydown").
timestamp	str	Временная метка ISO 8601.
elapsed_seconds	float	Секунды с момента старта записи.
tag_name	str	Имя HTML-тега элемента.
element_id	str | None	Значение id элемента (если есть).
class_names	str | None	CSS-классы элемента.
aria_label	str | None	Значение aria-label атрибута.
role	str | None	ARIA-роль элемента.
text_snippet	str | None	Текстовое содержимое элемента (фрагмент).
value_snippet	str | None	Введенное строковое значение.
computed_selector	str	Основной сгенерированный селектор элемента.
alternative_selectors	list[str]	Список альтернативных селекторов.
xpath	str | None	XPath-путь к элементу (опционально).
outer_html	str | None	HTML-сниппет элемента.
parent_summary	str | None	Описание непосредственного родителя.
matched_checklist_id	str | None	Идентификатор пункта чеклиста, с которым сопоставлено действие.
mutations	list[str]	Список произошедших мутаций DOM.
viewport	ViewportInfo | None	Информация о вьюпорте на момент взаимодействия.
container_scope	str | None	Контекст родительского оверлея или модального окна.
scoped_selector	str | None	Составной селектор с учетом контейнера.
duplicate_count	int	Количество найденных совпадений в DOM.
has_duplicates	bool	Флаг наличия дубликатов селектора.
mutation_diff	DOMMutationDiff | None	Детализированный отчет мутаций.

RecordedChecklistItem

Bases: BaseModel

Элемент интерактивного чеклиста действий пользователя.

Attributes:

Name	Type	Description
id	str	Уникальный строковый идентификатор пункта.
label	str	Отображаемое название пункта в HUD.
description	str	Подробное описание выполняемого действия.
hints	list[str]	Список селекторов и визуальных ориентиров элемента.
completed	bool	Флаг завершения шага.
is_manual	bool	Флаг подтверждения пользователем вручную.
action_index	int | None	Номер связанного действия пользователя.
target_selector	str | None	Зафиксированный итоговый селектор элемента.

RecordedRequest dataclass

Запись входящего HTTP-запроса от браузера или клиента.

SnapshotRecorder

Менеджер сохранения и загрузки оффлайн-снапшотов HTML страниц.

__init__(snapshot_dir=None)

Инициализирует менеджер снапшотов.

Parameters:

Name	Type	Description	Default
snapshot_dir	Path | str | None	Каталог для хранения HTML файлов. По умолчанию 'tests/fixtures/snapshots'.	None

exists(name)

Проверяет, существует ли сохраненный снапшот.

Parameters:

Name	Type	Description	Default
name	str	Имя снапшота.	required

Returns:

Type	Description
bool	True, если файл снапшота существует, иначе False.

load(name)

Загружает содержимое сохраненного снапшота.

Parameters:

Name	Type	Description	Default
name	str	Имя снапшота.	required

Returns:

Type	Description
str	HTML содержимое сохраненной страницы.

Raises:

Type	Description
FileNotFoundError	Если файл снапшота не найден на диске.

save(name, html)

Сохраняет HTML-содержимое в файл снапшота.

Parameters:

Name	Type	Description	Default
name	str	Имя снапшота.	required
html	str	HTML разметка для сохранения.	required

Returns:

Type	Description
Path	Абсолютный путь к сохраненному файлу снапшота.

TestResponse dataclass

Ответ локального сервера на тестовый запрос клиента.

text property

Возвращает декодированное текстовое содержимое ответа.

json()

Десериализует JSON из тела ответа.

Returns:

Type	Description
Any	Десериализованные данные (словарь, список или примитив).

ViewportInfo

Bases: BaseModel

Параметры области просмотра браузера и адаптивный брейкпоинт.

Attributes:

Name	Type	Description
width	int	Ширина окна в пикселях.
height	int	Высота окна в пикселях.
device_pixel_ratio	float	Соотношение физических пикселей к CSS (DPR).
breakpoint	Literal['desktop_wide', 'compact', 'mobile'] | str	Адаптивный брейкпоинт ("desktop_wide", "compact", "mobile").

use_html_snapshot

Контекстный менеджер и декоратор для воспроизведения/записи снапшотов страниц.

__aenter__() async

Вход в асинхронный контекстный менеджер.

Returns:

Type	Description
Any	HTML разметка или инкапсулированный мок браузера.

__aexit__(exc_type, exc_val, exc_tb) async

Выход из асинхронного контекстного менеджера.

Parameters:

Name	Type	Description	Default
exc_type	type[BaseException] | None	Тип исключения.	required
exc_val	BaseException | None	Экземпляр исключения.	required
exc_tb	TracebackType | None	Трассировка стека.	required

__call__(fn)

Декорирует синхронную или асинхронную тестовую функцию.

Parameters:

Name	Type	Description	Default
fn	Callable[..., Any]	Целевая тестовая функция.	required

Returns:

Type	Description
Callable[..., Any]	Обернутая функция, принимающая объект страницы первым аргументом.

__enter__()

Вход в синхронный контекстный менеджер.

Returns:

Type	Description
Any	HTML разметка или инкапсулированный мок браузера.

__exit__(exc_type, exc_val, exc_tb)

Выход из контекстного менеджера.

Parameters:

Name	Type	Description	Default
exc_type	type[BaseException] | None	Тип исключения (если возникло).	required
exc_val	BaseException | None	Экземпляр исключения.	required
exc_tb	TracebackType | None	Трассировка стека.	required

__init__(name, snapshot_dir=None, as_mock='raw', fetcher=None, record=False)

Инициализирует контекстный менеджер/декоратор снапшота.

Parameters:

Name	Type	Description	Default
name	str	Идентификатор/имя файла снапшота.	required
snapshot_dir	Path | str | None	Каталог сохранения снапшотов.	None
as_mock	MockType	Формат возвращаемого объекта ('raw', 'nodriver', 'playwright', 'selenium').	'raw'
fetcher	FetcherType | None	Функция получения страницы при отсутствии снапшота или record=True.	None
record	bool	Принудительно выполнить fetcher и обновить снапшот на диске.	False

assert_extraction_complete(data, required_keys=None, allow_empty_strings=False)

Проверяет полноту и отсутствие пустых значений в распарсенных данных.

Parameters:

Name	Type	Description	Default
data	dict[str, Any] | list[dict[str, Any]]	Распарсенный словарь или список словарей.	required
required_keys	list[str] | None	Список обязательных ключей, которые должны присутствовать.	None
allow_empty_strings	bool	Разрешать ли пустые строки в качестве валидных значений.	False

Raises:

Type	Description
AssertionError	Если обнаружен отсутствующий ключ, значение None или пустая строка.

assert_schema_match(data, schema_cls)

Проверяет соответствие извлеченных данных Pydantic схеме или классу модели.

Parameters:

Name	Type	Description	Default
data	dict[str, Any] | list[dict[str, Any]]	Распарсенный словарь или список словарей.	required
schema_cls	type	Класс модели (например, Pydantic BaseModel или dataclass).	required

Raises:

Type	Description
AssertionError	Если данные не соответствуют сигнатуре схемы.

assert_valid_price(price, min_value=0.0, max_value=None)

Проверяет корректность и границы цены товара.

Parameters:

Name	Type	Description	Default
price	float | Decimal | str	Значение цены в виде числа, Decimal или форматированной строки ("1 499 ₽", "$19.99").	required
min_value	float	Минимально допустимое значение цены (по умолчанию 0.0).	0.0
max_value	float | None	Опциональное максимально допустимое значение цены.	None

Raises:

Type	Description
AssertionError	Если цена нераспознаваема или выходит за установленные границы.

assert_valid_url(url, allowed_schemes=('http', 'https'), require_netloc=True)

Проверяет корректность извлеченного URL адреса.

Parameters:

Name	Type	Description	Default
url	str	Строка URL для проверки.	required
allowed_schemes	tuple[str, ...]	Допустимые схемы протоколов (по умолчанию http, https).	('http', 'https')
require_netloc	bool	Требовать ли наличие доменного имени или сетевого хоста.	True

Raises:

Type	Description
AssertionError	Если URL невалиден, относителен или имеет недопустимую схему.

build_inject_recorder_hud_script(checklist=None, widget_title='Запись действий DOM', container_selectors=None, custom_matcher_js=None)

Генерирует JS-скрипт внедрения перехватчика действий и плавающего виджета-шпаргалки.

Parameters:

Name	Type	Description	Default
checklist	Sequence[dict[str, Any] | RecordedChecklistItem] | None	Список пунктов чеклиста с id, label, description, hints.	None
widget_title	str	Отображаемый заголовок в шапке HUD.	'Запись действий DOM'
container_selectors	list[str] | None	Дополнительные селекторы модальных окон/панелей.	None
custom_matcher_js	str | None	Пользовательский код функции сопоставления элемента с чеклистом: (el, evType) => string | null.	None

Returns:

Type	Description
str	Строка JavaScript для вызова в браузере через evaluate.

build_scan_selectors_script(groups)

Генерирует JS-скрипт для полного сканирования и диагностики групп селекторов.

Parameters:

Name	Type	Description	Default
groups	dict[str, list[str] | dict[str, Any]]	Конфигурация групп селекторов. Значением может быть список строк-селекторов или словарь со свойством "selectors".	required

Returns:

Type	Description
str	Исходный код JavaScript, возвращающий диагностику через JSON.stringify.

get_recorder_hud_ui_js()

Возвращает JavaScript код рендеринга и управления плавающим HUD виджетом.

Построен с соблюдением требований Trusted Types (без использования innerHTML).

Returns:

Type	Description
str	Строка JavaScript кода функций renderChecklist, updateHudDisplay и createHud.

options: members: - DOMActionRecorder - DOMActionRecorderHUD - DOMActionSessionReport - RecordedAction - RecordedChecklistItem - DOMMutationDiff - ViewportInfo - CORE_DOM_HELPERS_JS - PAGE_META_SCRIPT - POLL_RECORDED_ACTIONS_SCRIPT - build_inject_recorder_hud_script - build_scan_selectors_script - get_recorder_hud_ui_js - LiveBrowserSession - LocalTestServer - SnapshotRecorder - MockNodriverTab - MockPlaywrightPage - MockSeleniumDriver - assert_extraction_complete - assert_schema_match - assert_valid_price - assert_valid_url

Модуль scraping.proxy (Управление прокси и защищенное хранилище)

chutils.scraping.proxy

Модуль управления прокси-серверами и аутентификацией.

ProxySecretStorage = KeyringProxyStorage module-attribute

Алиас для KeyringProxyStorage.

AsyncProxyTunnel

Локальный асинхронный HTTP/CONNECT форвардер для авторизации в удаленных прокси.

Позволяет запускать Chromium или браузеры в headless-режимах без расширений, направляя трафик на локальный адрес 127.0.0.1:<port>. Туннель прозрачно перехватывает запросы и добавляет заголовок Proxy-Authorization в удаленный прокси.

host property

Возвращает локальный хост прослушивания.

is_running property

Проверяет, запущен ли локальный сервер туннеля.

local_url property

Возвращает локальный HTTP URL туннеля.

port property

Возвращает фактический локальный порт туннеля.

__aenter__() async

Вход в асинхронный контекстный менеджер (запускает туннель).

Returns:

Type	Description
Self	Экземпляр запущенного AsyncProxyTunnel.

__aexit__(exc_type, exc_val, exc_tb) async

Выход из асинхронного контекстного менеджера (останавливает туннель).

Parameters:

Name	Type	Description	Default
exc_type	type[BaseException] | None	Тип исключения.	required
exc_val	BaseException | None	Значение исключения.	required
exc_tb	TracebackType | None	Трассировка стека.	required

__init__(proxy, local_host='127.0.0.1', local_port=0)

Инициализирует туннель.

Parameters:

Name	Type	Description	Default
proxy	ProxyConfig | str	Удаленный прокси-сервер (ProxyConfig или строка).	required
local_host	str	Локальный адрес для прослушивания (по умолчанию 127.0.0.1).	'127.0.0.1'
local_port	int	Локальный порт для прослушивания (0 для выбора свободного порта).	0

start() async

Запускает локальный сервер прокси-туннеля.

Returns:

Type	Description
Self	Экземпляр туннеля.

stop() async

Останавливает локальный сервер туннеля и завершает активные соединения.

to_chrome_arg()

Возвращает флаг командной строки --proxy-server для запуска Chromium.

Returns:

Type	Description
str	Строка флага --proxy-server с локальным адресом туннеля.

to_proxy_config()

Возвращает конфигурацию локального прокси без авторизации.

Returns:

Type	Description
ProxyConfig	Экземпляр ProxyConfig для подключения к локальному туннелю.

ChromeProxyExtension

Генератор временного расширения Chrome для аутентификации прокси.

Решает проблему отсутствия встроенной поддержки аутентификации (user:password) при запуске Chromium через аргумент --proxy-server (например, в nodriver). Создает расширение Manifest v3 с перехватом chrome.webRequest.onAuthRequired.

path property

Возвращает путь к директории расширения (генерирует, если еще не создано).

Returns:

Type	Description
Path	Путь к директории расширения на диске.

__enter__()

Вход в контекстный менеджер (создает расширение).

Returns:

Type	Description
Self	Экземпляр ChromeProxyExtension с созданным расширением.

__exit__(exc_type, exc_val, exc_tb)

Выход из контекстного менеджера (удаляет временную директорию).

Parameters:

Name	Type	Description	Default
exc_type	type[BaseException] | None	Тип исключения.	required
exc_val	BaseException | None	Значение исключения.	required
exc_tb	TracebackType | None	Трассировка стека.	required

__init__(proxy, output_dir=None, register_lifecycle_cleanup=True)

Инициализирует генератор расширения.

Parameters:

Name	Type	Description	Default
proxy	ProxyConfig | str	Конфигурация прокси или строка формата прокси.	required
output_dir	Path | str | None	Опциональная директория для размещения расширения.	None
register_lifecycle_cleanup	bool	Автоматически регистрировать удаление директории в chutils.lifecycle.	True

cleanup()

Удаляет директорию расширения и отменяет регистрацию в lifecycle.

generate(output_dir=None)

Генерирует файлы manifest.json и background.js расширения.

Parameters:

Name	Type	Description	Default
output_dir	Path | str | None	Целевая папка для файлов расширения.	None

Returns:

Type	Description
Path	Путь к сгенерированной директории расширения.

get_chrome_args()

Возвращает CLI аргументы для запуска Chromium с данным расширением.

Returns:

Type	Description
list[str]	Список флагов командной строки (--load-extension, --disable-extensions-except).

FileCacheBackend

Bases: BaseCacheBackend[str]

Дисковый кэш строковых значений с поддержкой TTL и атомарной записью через chutils.fs.

__init__(file_path)

Инициализирует дисковый файловый кэш.

Parameters:

Name	Type	Description	Default
file_path	Path | str	Путь к целевому JSON-файлу на диске.	required

clear()

Полностью очищает кэш.

delete(key)

Удаляет ключ из кэша.

Parameters:

Name	Type	Description	Default
key	str	Удаляемый ключ.	required

exists(key)

Проверяет наличие непросроченного ключа в кэше.

Parameters:

Name	Type	Description	Default
key	str	Проверяемый ключ.	required

Returns:

Type	Description
bool	True, если ключ найден и не просрочен, иначе False.

get(key)

Возвращает значение из кэша с проверкой срока жизни.

Parameters:

Name	Type	Description	Default
key	str	Ключ для поиска.	required

Returns:

Type	Description
str | None	Строковое значение или None, если запись отсутствует или просрочена.

invalidate_tag(tag)

Инвалидирует все ключи с заданным тегом.

Parameters:

Name	Type	Description	Default
tag	str	Название тега для очистки.	required

set(key, value, ttl=None, tags=None)

Сохраняет значение в кэше с опциональным TTL.

Parameters:

Name	Type	Description	Default
key	str	Ключ для сохранения.	required
value	str	Сохраняемое строковое значение.	required
ttl	int | None	Время жизни записи в секундах.	None
tags	list[str] | None	Опциональный список тегов.	None

KeyringProxyStorage

Безопасное хранилище учетных данных прокси для именованных профилей браузера.

Обеспечивает разделение публичных метаданных профилей (сохраняемых на диск) и приватных паролей прокси. Учетные данные сохраняются в зашифрованном системном хранилище ОС (Windows Credential Manager, macOS Keychain, Linux Secret Service) через chutils.SecretManager, оставляя на диске только замаскированный URL.

__init__(service_name=None, key_prefix='proxy:', secret_manager=None)

Инициализирует защищенное хранилище прокси.

Parameters:

Name	Type	Description	Default
service_name	str | None	Имя сервиса для Keyring (по умолчанию "chutils_proxy_storage").	None
key_prefix	str	Префикс ключей в системном хранилище (по умолчанию "proxy:").	'proxy:'
secret_manager	SecretManager | None	Пользовательский экземпляр SecretManager (для DI или тестов).	None

delete_proxy(profile_name)

Удаляет сохраненный прокси профиля из Keyring.

Parameters:

Name	Type	Description	Default
profile_name	str	Имя профиля браузера.	required

Returns:

Type	Description
bool	True при успешном удалении.

get_masked_proxy(profile_name)

Получает безопасную замаскированную строку прокси для профиля.

Parameters:

Name	Type	Description	Default
profile_name	str	Имя профиля браузера.	required

Returns:

Type	Description
str | None	Замаскированный URL (например, 'http://user:***@host:port') или None.

get_proxy(profile_name)

Получает полный URL прокси с учетными данными для указанного профиля.

Parameters:

Name	Type	Description	Default
profile_name	str	Имя профиля браузера.	required

Returns:

Type	Description
str | None	Полная строка прокси (с паролем) или None, если прокси не привязан.

mask_proxy_url(proxy_url) staticmethod

Маскирует пароль в строке прокси для безопасного сохранения на диск или логирования.

Parameters:

Name	Type	Description	Default
proxy_url	str | None	Строка прокси (URL или параметры).	required

Returns:

Type	Description
str | None	Строка со скрытым паролем ('user:***@host:port') или исходное значение.

restore_proxy_url(profile_name, proxy_url)

Восстанавливает оригинальный URL с паролем, если передан замаскированный URL.

Если в переданном URL обнаружена маска '***', метод извлекает сохраненный пароль из Keyring для соответствующего профиля.

Parameters:

Name	Type	Description	Default
profile_name	str	Имя профиля браузера.	required
proxy_url	str | None	Исходная строка прокси (возможно, замаскированная).	required

Returns:

Type	Description
str | None	Полный URL прокси с оригинальным паролем или исходная строка.

sanitize_metadata_dict(profile_name, meta_dict, proxy_key='proxy', sync_to_keyring=True)

Санитизирует словарь метаданных профиля перед сохранением в JSON-файл на диске.

Если в словаре содержится открытый URL с паролем: 1. Полный URL сохраняется в системный Keyring (если sync_to_keyring=True). 2. В словаре пароль заменяется на безопасную маску '***'.

Parameters:

Name	Type	Description	Default
profile_name	str	Имя профиля.	required
meta_dict	dict[str, Any]	Исходный словарь метаданных.	required
proxy_key	str	Имя ключа прокси в словаре (по умолчанию 'proxy').	'proxy'
sync_to_keyring	bool	Сохранить оригинальный прокси в Keyring при наличии пароля.	True

Returns:

Type	Description
dict[str, Any]	Копия словаря с замаскированным прокси.

set_proxy(profile_name, proxy_url)

Сохраняет или удаляет прокси профиля в безопасном хранилище.

Parameters:

Name	Type	Description	Default
profile_name	str	Имя профиля браузера.	required
proxy_url	str | None	Строка прокси (URL или host:port:user:pass) или None для сброса.	required

Returns:

Type	Description
bool	True при успешном сохранении или удалении.

ProxyCandidate

Bases: BaseModel

Модель кандидата прокси с нормализованными компонентами.

url property

Возвращает нормализованный URL прокси.

to_proxy_config()

Преобразует кандидата в экземпляр ProxyConfig.

Returns:

Type	Description
ProxyConfig	Сконфигурированный объект ProxyConfig.

ProxyConfig

Bases: BaseModel

Конфигурация прокси-сервера с поддержкой аутентификации.

auth_str property

Возвращает строку аутентификации user:password или None.

basic_auth_header property

Возвращает значение заголовка Proxy-Authorization Basic или None.

has_auth property

Проверяет наличие учетных данных аутентификации.

masked_url property

Возвращает безопасный URL для логирования со скрытым паролем.

server_url property

Возвращает базовый URL прокси-сервера без учетных данных.

url property

Возвращает полный URL прокси с учетными данными, если они есть.

to_chrome_arg()

Возвращает CLI аргумент --proxy-server для Chromium.

Returns:

Type	Description
str	Строка флага командной строки для запуска Chromium.

to_playwright()

Преобразует конфигурацию в словарь параметров прокси для Playwright.

Returns:

Type	Description
dict[str, str]	Словарь с ключами server, username и password для playwright.

to_selenium()

Преобразует конфигурацию в словарь capabilities прокси для Selenium.

Returns:

Type	Description
dict[str, str]	Словарь параметров прокси для передачи в Selenium Capabilities.

to_string(format='url')

Форматирует прокси в строковое представление по заданному шаблону.

Parameters:

Name	Type	Description	Default
format	str	Шаблон формата ('url', 'host:port', 'host:port:user:pass', 'server').	'url'

Returns:

Type	Description
str	Строковое представление прокси.

ProxyHealthResult

Bases: BaseModel

Результат проверки работоспособности (Health Check) прокси-сервера.

ProxyPool

Потокобезопасный пул прокси-серверов с поддержкой ротации и автоматического failover.

__init__(proxies=None, strategy='round_robin', sticky_ttl=600.0, ban_timeout=300.0, max_fails=3)

Инициализирует пул прокси.

Parameters:

Name	Type	Description	Default
proxies	Sequence[ProxyConfig | str | dict[str, object]] | None	Начальный список прокси (объекты, строки или словари).	None
strategy	RotationStrategy	Стратегия ротации ('round_robin', 'random', 'sticky', 'failover').	'round_robin'
sticky_ttl	float	Время жизни привязки сессии/пользователя в секундах для sticky.	600.0
ban_timeout	float	Время временного исключения сбойного прокси из пула (в секундах).	300.0
max_fails	int	Максимальное количество ошибок до временного отключения прокси.	3

add(proxy)

Добавляет прокси в пул.

Parameters:

Name	Type	Description	Default
proxy	ProxyConfig | str | dict[str, object]	Конфигурация прокси (ProxyConfig, строка или dict).	required

get_all()

Возвращает список всех зарегистрированных прокси в пуле.

Returns:

Type	Description
list[ProxyConfig]	Список экземпляров ProxyConfig.

get_available()

Возвращает список только доступных (не забаненных) прокси.

Returns:

Type	Description
list[ProxyConfig]	Список доступных экземпляров ProxyConfig.

get_next(key=None)

Возвращает следующий прокси согласно выбранной стратегии.

Parameters:

Name	Type	Description	Default
key	str | None	Идентификатор сессии/пользователя для стратегии 'sticky'.	None

Returns:

Type	Description
ProxyConfig | None	Экземпляр ProxyConfig или None, если нет доступных прокси.

remove(proxy)

Удаляет прокси из пула.

Parameters:

Name	Type	Description	Default
proxy	ProxyConfig | str	Удаляемый прокси (ProxyConfig или строка).	required

Returns:

Type	Description
bool	True, если прокси был найден и удален, иначе False.

report_failure(proxy)

Фиксирует ошибку при обращении через прокси.

Parameters:

Name	Type	Description	Default
proxy	ProxyConfig | str	Прокси, на котором произошел сбой.	required

report_success(proxy)

Фиксирует успешный запрос через прокси, сбрасывая счетчик ошибок.

Parameters:

Name	Type	Description	Default
proxy	ProxyConfig | str	Успешно отработавший прокси.	required

reset_status()

Сбрасывает счетчики ошибок и разблокирует все временно отключенные прокси.

SmartProxyResolver

Умный резолвер и верификатор форматов прокси с активным зондированием и дисковым кэшированием.

__init__(cache_path=None, probe_timeout=2.5, target_url='http://www.google.com/generate_204')

Инициализирует резолвер прокси.

Parameters:

Name	Type	Description	Default
cache_path	Path | str | None	Путь к файлу кэша. Если не указан, используется .chutils/proxy_cache.json.	None
probe_timeout	float	Таймаут проверки соединения с кандидатом в секундах.	2.5
target_url	str	Целевой легковесный URL для тестового HTTP GET-запроса при проверке.	'http://www.google.com/generate_204'

check_health(candidate_url) async

Выполняет комплексный Health Check прокси с замером задержки (latency).

Parameters:

Name	Type	Description	Default
candidate_url	str	URL кандидата прокси для проверки.	required

Returns:

Type	Description
ProxyHealthResult	Экземпляр ProxyHealthResult со статусом доступности и задержкой в мс.

generate_candidates(raw_proxy)

Генерирует список кандидатов URL прокси в порядке приоритета проверки.

Поддерживает форматы: - host:port:user:pass (приоритет: http, затем socks5) - user:pass:host:port - user:pass@host:port - host:port@user:pass - host:port - http://..., socks5://... (выбранный протокол, затем альтернатива)

Parameters:

Name	Type	Description	Default
raw_proxy	str | None	Исходная строка прокси.	required

Returns:

Type	Description
list[str]	Список нормализованных URL-адресов кандидатов.

probe_proxy(candidate_url) async

Проверяет реальную сетевую доступность и валидность авторизации кандидата прокси.

Parameters:

Name	Type	Description	Default
candidate_url	str	URL кандидата прокси.	required

Returns:

Type	Description
bool	True, если прокси успешно ответил на рукопожатие или запрос, иначе False.

resolve(raw_proxy, force_check=False, default_fallback=True, force=False) async

Определяет корректный формат, проверяет доступность кандидатов и возвращает рабочий URL.

Parameters:

Name	Type	Description	Default
raw_proxy	str | None	Исходная строка прокси от пользователя.	required
force_check	bool	Игнорировать дисковый кэш и принудительно провести сетевой опрос.	False
default_fallback	bool	Возвращать лучший нормализованный URL при недоступности всех кандидатов.	True
force	bool	Синоним force_check для обратной совместимости.	False

Returns:

Type	Description
str | None	Нормализованный валидный URL прокси или None при пустом вводе.

resolve_config(raw_proxy, force_check=False, default_fallback=True, force=False) async

Резолвит прокси и возвращает структурированный объект ProxyConfig.

Parameters:

Name	Type	Description	Default
raw_proxy	str | None	Исходная строка прокси.	required
force_check	bool	Принудительно выполнить сетевую проверку без кэша.	False
default_fallback	bool	Использовать первый валидный кандидат при недоступности сети.	True
force	bool	Синоним force_check для обратной совместимости.	False

Returns:

Type	Description
ProxyConfig | None	Экземпляр ProxyConfig или None при пустом вводе.

resolve_config_sync(raw_proxy, force_check=False, default_fallback=True, force=False)

Синхронная обертка для асинхронного метода resolve_config.

Parameters:

Name	Type	Description	Default
raw_proxy	str | None	Исходная строка прокси.	required
force_check	bool	Принудительно выполнить опрос без учета кэша.	False
default_fallback	bool	Возвращать лучший кандидат при неудаче проверки.	True
force	bool	Синоним force_check для обратной совместимости.	False

Returns:

Type	Description
ProxyConfig | None	Экземпляр ProxyConfig или None.

resolve_sync(raw_proxy, force_check=False, default_fallback=True, force=False)

Синхронная обертка для асинхронного метода resolve.

Parameters:

Name	Type	Description	Default
raw_proxy	str | None	Исходная строка прокси.	required
force_check	bool	Принудительно выполнить опрос без учета кэша.	False
default_fallback	bool	Возвращать лучший кандидат при неудаче проверки.	True
force	bool	Синоним force_check для обратной совместимости.	False

Returns:

Type	Description
str | None	Рабочий URL прокси или None.

async_nodriver_proxy(proxy, mode='auto') async

Асинхронный контекстный менеджер прокси для nodriver.

Поддерживает режим авто-расширения (extension) или локального туннеля (tunnel).

Parameters:

Name	Type	Description	Default
proxy	ProxyConfig | str | dict[str, object]	Конфигурация прокси (ProxyConfig, строка или dict).	required
mode	Literal['auto', 'extension', 'tunnel']	Режим проксирования ('auto', 'extension', 'tunnel').	'auto'

Yields:

Type	Description
AsyncGenerator[list[str], None]	Список флагов командной строки для nodriver.

check_proxy(proxy, target_url='https://api.ipify.org?format=json', timeout=5.0)

Синхронно проверяет доступность прокси, замеряет RTT и определяет внешний IP.

Parameters:

Name	Type	Description	Default
proxy	ProxyConfig | str	Проверяемый прокси (ProxyConfig или строка).	required
target_url	str	URL проверочного эндпоинта.	'https://api.ipify.org?format=json'
timeout	float	Таймаут соединения в секундах.	5.0

Returns:

Type	Description
ProxyHealthResult	Экземпляр ProxyHealthResult с результатами проверки.

check_proxy_async(proxy, target_url='https://api.ipify.org?format=json', timeout=5.0) async

Асинхронно проверяет доступность прокси в отдельном потоке.

Parameters:

Name	Type	Description	Default
proxy	ProxyConfig | str	Проверяемый прокси.	required
target_url	str	URL проверочного эндпоинта.	'https://api.ipify.org?format=json'
timeout	float	Таймаут соединения в секундах.	5.0

Returns:

Type	Description
ProxyHealthResult	Экземпляр ProxyHealthResult с результатами проверки.

get_nodriver_proxy_args(proxy)

Возвращает список аргументов запуска браузера для nodriver.

Если прокси не требует авторизации, возвращает флаг --proxy-server. Если прокси требует авторизацию, генерирует Manifest v3 расширение через ChromeProxyExtension с авто-очисткой при завершении приложения.

Parameters:

Name	Type	Description	Default
proxy	ProxyConfig | str | dict[str, object]	Конфигурация прокси (ProxyConfig, строка или dict).	required

Returns:

Type	Description
list[str]	Список флагов командной строки для запуска Chromium.

get_playwright_proxy(proxy)

Формирует словарь параметров прокси для передачи в Playwright BrowserType.launch.

Parameters:

Name	Type	Description	Default
proxy	ProxyConfig | str | dict[str, object]	Конфигурация прокси (ProxyConfig, строка или dict).	required

Returns:

Type	Description
dict[str, str]	Словарь с параметрами server, username, password для Playwright.

get_selenium_proxy(proxy, options=None)

Формирует параметры прокси для Selenium или добавляет их в переданный объект Options.

Parameters:

Name	Type	Description	Default
proxy	ProxyConfig | str | dict[str, object]	Конфигурация прокси (ProxyConfig, строка или dict).	required
options	object | None	Опциональный экземпляр webdriver Options (например, ChromeOptions).	None

Returns:

Type	Description
dict[str, str] | None	Словарь capabilities прокси, если options не передан, иначе None.

nodriver_proxy(proxy)

Контекстный менеджер аргументов запуска nodriver с авто-очисткой расширения.

Parameters:

Name	Type	Description	Default
proxy	ProxyConfig | str | dict[str, object]	Конфигурация прокси (ProxyConfig, строка или dict).	required

Yields:

Type	Description
list[str]	Список флагов командной строки для nodriver.

parse_proxy(proxy, default_protocol='http')

Парсит строку, словарь или существующий объект в экземпляр ProxyConfig.

Поддерживает распространенные форматы: - URL: http://user:pass@host:port, socks5://host:port - Без схемы с @: user:pass@host:port - Колоночные: host:port, host:port:user:pass, user:pass:host:port

Parameters:

Name	Type	Description	Default
proxy	str | ProxyConfig | Mapping[str, object]	Строка прокси, словарь параметров или экземпляр ProxyConfig.	required
default_protocol	ProxyProtocol	Протокол по умолчанию, если схема не указана.	'http'

Returns:

Type	Description
ProxyConfig	Экземпляр ProxyConfig с валидированными полями.

Raises:

Type	Description
TypeError	Если передан неподдерживаемый тип данных.
ValueError	Если строку прокси не удалось распознать или порт некорректен.

options: members: - KeyringProxyStorage - ProxySecretStorage - ProxyConfig - ProxyPool - SmartProxyResolver - AsyncProxyTunnel - ChromeProxyExtension - parse_proxy - check_proxy - check_proxy_async - async_nodriver_proxy - nodriver_proxy - get_nodriver_proxy_args - get_playwright_proxy - get_selenium_proxy

Модуль scraping.profiles (Управление профилями браузеров и гигиена)

chutils.scraping.profiles

Инициализация пакета профилей браузеров.

BrowserProfile

Bases: BaseModel

Универсальная модель профиля браузера для экспорта/импорта.

CookieData

Bases: BaseModel

Данные Cookie записи.

HeaderData

Bases: BaseModel

Метаданные заголовков и браузера.

ProfileManager

Менеджер для универсального экспорта, конвертации и импорта браузерных профилей.

export_from_nodriver(tab) async staticmethod

Экспортировать профиль сессии из nodriver Tab.

Parameters:

Name	Type	Description	Default
tab	Any	Объект nodriver.Tab.	required

Returns:

Type	Description
BrowserProfile	Экземпляр BrowserProfile.

export_from_playwright(context) async staticmethod

Экспортировать профиль сессии из Playwright BrowserContext.

Parameters:

Name	Type	Description	Default
context	Any	Объект playwright.async_api.BrowserContext.	required

Returns:

Type	Description
BrowserProfile	Экземпляр BrowserProfile.

export_from_selenium(driver) staticmethod

Экспортировать профиль сессии из Selenium WebDriver.

Parameters:

Name	Type	Description	Default
driver	Any	Объект selenium.webdriver.	required

Returns:

Type	Description
BrowserProfile	Экземпляр BrowserProfile.

import_to_nodriver(tab, profile) async staticmethod

Импортировать профиль сессии в nodriver Tab.

Parameters:

Name	Type	Description	Default
tab	Any	Объект nodriver.Tab.	required
profile	BrowserProfile	Экземпляр BrowserProfile.	required

import_to_playwright(context, profile) async staticmethod

Импортировать профиль сессии в Playwright BrowserContext.

Parameters:

Name	Type	Description	Default
context	Any	Объект playwright.async_api.BrowserContext.	required
profile	BrowserProfile	Экземпляр BrowserProfile.	required

import_to_selenium(driver, profile) staticmethod

Импортировать профиль сессии в Selenium WebDriver.

Parameters:

Name	Type	Description	Default
driver	Any	Объект selenium.webdriver.	required
profile	BrowserProfile	Экземпляр BrowserProfile.	required

load(filepath, password=None) staticmethod

Загрузить профиль из .chprofile файла с опциональной расшифровкой.

Parameters:

Name	Type	Description	Default
filepath	str | Path	Путь к файлу .chprofile.	required
password	str | None	Пароль для расшифровки.	None

Returns:

Type	Description
BrowserProfile	Экземпляр BrowserProfile.

sanitize_profile(profile_path, *, reset_crash_flags=True, clear_sessions=True, profile_dir_name='Default', restore_on_startup=1) staticmethod

Очищает профиль Chromium от артефактов падений и сбрасывает флаги некорректного завершения.

Предотвращает появление инфобара "Восстановить страницы? Chromium завершился некорректно", меняющего геометрию viewport и детектируемого антифрод-системами.

Parameters:

Name	Type	Description	Default
profile_path	str | Path	Путь к корневой директории пользовательских данных (user_data_dir) или профиля.	required
reset_crash_flags	bool	Сбросить exit_type в "Normal" и exited_cleanly в True в Preferences.	True
clear_sessions	bool	Очистить Sessions/Session_ и Tabs_.	True
profile_dir_name	str	Имя поддиректории профиля (по умолчанию "Default").	'Default'
restore_on_startup	int	Значение restore_on_startup (1 = открывать новую вкладку).	1

Returns:

Type	Description
bool	True, если очистка выполнена успешно; False в случае ошибки.

save(profile, filepath, password=None) staticmethod

Сохранить профиль в .chprofile файл с опциональным шифрованием.

Parameters:

Name	Type	Description	Default
profile	BrowserProfile	Экземпляр BrowserProfile.	required
filepath	str | Path	Путь к сохраняемому файлу.	required
password	str | None	Пароль для шифрования.	None

Returns:

Type	Description
Path	Path к сохраненному файлу.

save_profile_after_warmup(browser_obj, filepath, password=None, metadata=None, driver_type=None) async classmethod

Экспортирует состояние сессии после прогрева и сохраняет в .chprofile файл.

Поддерживает Playwright (BrowserContext или Page), nodriver (Tab) и Selenium WebDriver.

Parameters:

Name	Type	Description	Default
browser_obj	Any	Сессия (Playwright BrowserContext/Page, nodriver Tab или Selenium WebDriver).	required
filepath	str | Path	Путь к сохраняемому файлу (.chprofile).	required
password	str | None	Опциональный пароль для шифрования данных профиля.	None
metadata	dict[str, str] | None	Дополнительные метаданные для сохранения в профиле.	None
driver_type	str | None	Необязательный тип драйвера ('playwright', 'nodriver', 'selenium'). Если None, определяется автоматически.	None

Returns:

Type	Description
BrowserProfile	Экземпляр сохраненного BrowserProfile.

StorageData

Bases: BaseModel

Данные хранилищ браузера (LocalStorage, SessionStorage, IndexedDB).

is_profile_locked(profile_dir)

Проверяет, заблокирован ли каталог профиля другим запущенным процессом Chromium.

Сканирует файлы блокировок Chrome: lockfile, SingletonLock и проверяет доступ к эксклюзивной базе Default/Web Data.

Parameters:

Name	Type	Description	Default
profile_dir	str | Path	Путь к директории профиля Chrome.	required

Returns:

Type	Description
bool	True, если каталог профиля заблокирован или используется другим процессом.

load_profile_from_file(filepath, password=None)

Загрузить и распарсить модель BrowserProfile из архива .chprofile.

Parameters:

Name	Type	Description	Default
filepath	str | Path	Путь к файлу .chprofile.	required
password	str | None	Необязательный пароль расшифровки.	None

Returns:

Type	Description
BrowserProfile	Экземпляр BrowserProfile.

sanitize_profile(profile_path, *, reset_crash_flags=True, clear_sessions=True, profile_dir_name='Default', restore_on_startup=1)

Очищает профиль Chromium от артефактов падений и сбрасывает флаги некорректного завершения.

Предотвращает появление инфобара и модального диалога "Восстановить страницы? Chromium завершился некорректно", который искажает геометрию окна (viewport), перехватывает фокус, сдвигает координаты кликов и детектируется антифрод-системами как признак автоматизации.

Parameters:

Name	Type	Description	Default
profile_path	str | Path	Путь к корневой директории пользовательских данных Chromium (user_data_dir) или непосредственно к каталогу профиля (например, Default).	required
reset_crash_flags	bool	Сбросить флаги exit_type в "Normal" и exited_cleanly в True в файле Preferences и Local State.	True
clear_sessions	bool	Очистить директории и файлы сохраненных сессий и вкладок (Default/Sessions, Session_, Tabs_).	True
profile_dir_name	str	Имя поддиректории профиля Chromium (по умолчанию "Default").	'Default'
restore_on_startup	int	Значение session.restore_on_startup (1 = открывать новую вкладку).	1

Returns:

Type	Description
bool	True, если очистка выполнена успешно или директория валидна; False в случае ошибки.

sanitize_profile_crash_state(profile_dir)

Сбрасывает флаги аварийного закрытия Chromium, предотвращая модальное окно 'Восстановить страницы'.

Алиас для sanitize_profile(profile_dir, reset_crash_flags=True, clear_sessions=True).

Parameters:

Name	Type	Description	Default
profile_dir	str | Path	Путь к директории профиля пользователя Chrome.	required

Returns:

Type	Description
bool	True, если очистка выполнена успешно.

save_profile_to_file(profile, filepath, password=None)

Сохранить модель BrowserProfile в zip-архив .chprofile.

Parameters:

Name	Type	Description	Default
profile	BrowserProfile	Экземпляр модели BrowserProfile.	required
filepath	str | Path	Путь к сохраняемому файлу (.chprofile).	required
password	str | None	Необязательный пароль для Fernet-шифрования.	None

Returns:

Type	Description
Path	Path к сохраненному файлу.

options: members: - ProfileManager - ProfileHygieneService - sanitize_profile_crash_state - sanitize_profile - is_profile_locked - clean_profile_cache