Справочник API

В этом разделе находится документация, автоматически сгенерированная из исходного кода chutils.

Пакет 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")

ChutilsLogger

Bases: Logger

Кастомный класс логгера, расширяющий стандартный logging.Logger.

Добавляет поддержку пользовательских уровней логирования (devdebug и mediumdebug), обеспечивая при этом корректную работу статических анализаторов и автодополнения в IDE.

Иерархия уровней

• DEVDEBUG (9): Максимально подробный вывод для глубокой отладки. Предназначен для вывода дампов переменных, внутренних состояний и т.д.
• DEBUG (10): Стандартный отладочный уровень.
• MEDIUMDEBUG (15): Промежуточный уровень между DEBUG и INFO. Полезен для менее критичной, но более подробной, чем INFO, информации.
• INFO (20): Стандартный информационный уровень.

Note

Не создавайте экземпляр напрямую. Используйте setup_logger().

Example

logger: ChutilsLogger = setup_logger()
logger.devdebug("Максимально подробное сообщение")

devdebug(message, *args, **kws)

Логирует сообщение с уровнем DEVDEBUG (9).

Parameters:

Name	Type	Description	Default
message	str	Сообщение для логирования.	required
*args	Any	Аргументы форматирования.	()
**kws	Any	Ключевые слова для логгера.	{}

mediumdebug(message, *args, **kws)

Логирует сообщение с уровнем MEDIUMDEBUG (15).

Parameters:

Name	Type	Description	Default
message	str	Сообщение для логирования.	required
*args	Any	Аргументы форматирования.	()
**kws	Any	Ключевые слова для логгера.	{}

SafeTimedRotatingFileHandler

Bases: TimedRotatingFileHandler

Надежный обработчик ротации логов, адаптированный для Windows.

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

doRollover()

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

SecretManager

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

Приоритет получения секрета: 1. Системное хранилище (keyring). 2. Переменные из .env файла в корне проекта. 3. Переменные окружения ОС.

Attributes:

Name	Type	Description
service_name	str	Полное имя сервиса для keyring.
disable_keyring	bool	Флаг отключения работы с keyring.

__init__(service_name=None, prefix=None)

Инициализирует менеджер и лениво загружает переменные из .env файла.

Порядок определения service_name: 1. Значение, переданное в конструктор (если оно не пустое). 2. Значение из конфигурационного файла (секция Secrets, ключ service_name). 3. Абсолютный путь к корню проекта (для гарантированной уникальности).

Parameters:

Name	Type	Description	Default
service_name	Optional[str]	Опциональное уникальное имя для вашего приложения.	None
prefix	Optional[str]	Опциональный префикс для service_name. Если не указан, будет взят из конфига (ключ prefix) или использован "Chutils_".	None

Raises:

Type	Description
ValueError	Если не удалось определить service_name.

adelete_secret(key) async

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

Parameters:

Name	Type	Description	Default
key	str	Ключ секрета.	required

Returns:

Type	Description
bool	True, если секрет был удален или уже не существовал.
bool	False, если произошла ошибка при удалении.

aget_secret(key) async

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

Parameters:

Name	Type	Description	Default
key	str	Ключ секрета.	required

Returns:

Type	Description
Optional[str]	Значение секрета или None.

asave_secret(key, value) async

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

Parameters:

Name	Type	Description	Default
key	str	Ключ секрета.	required
value	str	Секретное значение.	required

Returns:

Type	Description
bool	True, если секрет успешно сохранен в keyring.
bool	False, если произошла ошибка.

delete_secret(key)

Удаляет пару ключ-значение из системного хранилища (keyring). Эта функция не влияет на переменные окружения или .env файлы.

Parameters:

Name	Type	Description	Default
key	str	Ключ секрета.	required

Returns:

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

get_secret(key)

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

Поиск происходит в следующем порядке: 1. Системное хранилище (keyring). 2. Переменные из .env файла / переменные окружения.

Parameters:

Name	Type	Description	Default
key	str	Ключ секрета.	required

Returns:

Type	Description
Optional[str]	Значение секрета или None, если ключ не найден.

save_secret(key, value)

Сохраняет пару ключ-значение в системном хранилище (keyring). Эта функция не влияет на переменные окружения или .env файлы.

Parameters:

Name	Type	Description	Default
key	str	Ключ секрета.	required
value	str	Секретное значение.	required

Returns:

Type	Description
bool	True, если секрет успешно сохранен в keyring.
bool	False, если произошла ошибка.

update_secret(key, value)

Обновляет значение для существующего ключа в системном хранилище (keyring). Это псевдоним для save_secret.

Parameters:

Name	Type	Description	Default
key	str	Ключ секрета.	required
value	str	Новое значение.	required

Returns:

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

aget_config() async

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

Returns:

Type	Description
Dict	Словарь конфигурации.

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

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

Parameters:

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

Returns:

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

get_config()

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

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

Returns:

Name	Type	Description
_config_object	Dict	Словарь со всей конфигурацией проекта. Если файлы не найдены, возвращается пустой словарь.

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

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

Распознает '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	Optional[Dict]	Опциональный, предварительно загруженный словарь конфигурации.	None

Returns:

Type	Description
bool	True или False.

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

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

Parameters:

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

Returns:

Type	Description
float	Float или fallback.

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

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

Parameters:

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

Returns:

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

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

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

Parameters:

Name	Type	Description	Default
section	str	Имя секции.	required
key	str	Имя ключа.	required
fallback	Optional[List[Any]]	Значение по умолчанию, если ключ не найден.	None
config	Optional[Dict]	Опциональный, предварительно загруженный словарь конфигурации.	None

Returns:

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

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

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

get_config_section(section_name, fallback=None, config=None)

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

Parameters:

Name	Type	Description	Default
section_name	str	Имя секции.	required
fallback	Optional[Dict]	Значение по умолчанию, если секция не найдена.	None
config	Optional[Dict]	Опциональный, предварительно загруженный словарь конфигурации.	None

Returns:

Type	Description
Dict[str, Any]	Словарь с содержимым секции или fallback. Если fallback не указан,
Dict[str, Any]	возвращается пустой словарь.

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

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

Если значение не найдено или оно пустое, возвращает fallback. Для ключа disable_keyring в секции secrets проверяет переменную окружения.

Parameters:

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

Returns:

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

init(base_dir)

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

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

Parameters:

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

Raises:

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

log_function_details(func)

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

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

Parameters:

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

Returns:

Type	Description
	Обертка функции с логированием.

Example

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

add(2, 3)

setup_logger(name='app_logger', config_section_name=None, log_level=None, log_file_name=None, force_reconfigure=False, rotation_type=None, max_bytes=None, compress=None, backup_count=None, encoding=None, when=None, interval=None, utc=None, at_time=None, **kwargs)

Настраивает и возвращает экземпляр логгера.

Приоритет настроек: 0. Переменные окружения CH_LOG_NO_TIME и CH_LOG_NO_FILE имеют наивысший приоритет. 1. Явные аргументы, переданные в эту функцию. 2. Объединенные настройки из Logging.loggers.{name} (если есть) поверх Logging.default (если есть). 3. Для обратной совместимости: если Logging.default и Logging.loggers отсутствуют, используются прямые настройки из Logging (как в старом формате). 4. Значения по умолчанию, зашитые в коде.

Parameters:

Name	Type	Description	Default
name	str	Имя логгера. app_logger используется как стандартное имя.	'app_logger'
config_section_name	Optional[str]	Имя секции в конфиге (например, 'MyAuditLogger'). Если указана, настройки из этой секции переопределяют настройки из общей секции [Logging]. Если не указана, используется только общая секция [Logging].	None
log_level	Optional[LogLevel]	Уровень логирования (строка или LogLevel).	None
log_file_name	Optional[str]	Имя файла для логирования. Если не указано, имя берется из конфигурации ('Logging', 'log_file_name').	None
force_reconfigure	bool	Удалить существующие обработчики и настроить заново.	False
rotation_type	Optional[str]	Тип ротации ('time' или 'size').	None
max_bytes	Optional[int]	Макс. размер файла для ротации по 'size'.	None
compress	Optional[bool]	Сжимать ли ротированные логи в .gz.	None
backup_count	Optional[int]	Количество хранимых ротированных файлов.	None
encoding	Optional[str]	Кодировка файла (по умолчанию 'utf-8').	None
when	Optional[str]	Для 'time'. Тип интервала ('S', 'M', 'H', 'D', 'midnight', 'W0'-'W6').	None
interval	Optional[int]	Для 'time'. Длина интервала.	None
utc	Optional[bool]	Для 'time'. Использовать UTC время.	None
at_time	Optional[time]	Для 'time'. Время ротации (при when='midnight').	None
**kwargs	Any	Дополнительные параметры для FileHandler (например, delay=True, errors='ignore', mode='a').	{}

Returns:

Type	Description
ChutilsLogger	Настроенный экземпляр ChutilsLogger.

options: members: [init]

Модуль config

chutils.config

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

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

aget_config() async

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

Returns:

Type	Description
Dict	Словарь конфигурации.

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

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

Parameters:

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

Returns:

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

find_project_root(start_path, markers)

Ищет корень проекта, двигаясь вверх по дереву каталогов.

Корень определяется по наличию одного из файлов-маркеров (например, .git или pyproject.toml).

Parameters:

Name	Type	Description	Default
start_path	Path	Директория, с которой начинается поиск.	required
markers	List[str]	Список имен файлов или папок (маркеров), наличие которых в директории указывает на то, что это корень проекта.	required

Returns:

Type	Description
Optional[Path]	Объект Path, представляющий корневую директорию проекта, или None, если корень не найден.

get_config()

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

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

Returns:

Name	Type	Description
_config_object	Dict	Словарь со всей конфигурацией проекта. Если файлы не найдены, возвращается пустой словарь.

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

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

Распознает '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	Optional[Dict]	Опциональный, предварительно загруженный словарь конфигурации.	None

Returns:

Type	Description
bool	True или False.

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

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

Parameters:

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

Returns:

Type	Description
float	Float или fallback.

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

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

Parameters:

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

Returns:

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

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

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

Parameters:

Name	Type	Description	Default
section	str	Имя секции.	required
key	str	Имя ключа.	required
fallback	Optional[List[Any]]	Значение по умолчанию, если ключ не найден.	None
config	Optional[Dict]	Опциональный, предварительно загруженный словарь конфигурации.	None

Returns:

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

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

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

get_config_section(section_name, fallback=None, config=None)

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

Parameters:

Name	Type	Description	Default
section_name	str	Имя секции.	required
fallback	Optional[Dict]	Значение по умолчанию, если секция не найдена.	None
config	Optional[Dict]	Опциональный, предварительно загруженный словарь конфигурации.	None

Returns:

Type	Description
Dict[str, Any]	Словарь с содержимым секции или fallback. Если fallback не указан,
Dict[str, Any]	возвращается пустой словарь.

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

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

Если значение не найдено или оно пустое, возвращает fallback. Для ключа disable_keyring в секции secrets проверяет переменную окружения.

Parameters:

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

Returns:

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

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

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

Warning

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

Parameters:

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

Returns:

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

options: members:

• get_config
• get_config_value
• get_config_int
• get_config_float
• get_config_boolean
• get_config_list
• get_config_section
• save_config_value

Переопределение конфигурации локальным файлом

Функция get_config() теперь автоматически ищет и загружает локальный файл конфигурации (например, config.local.yml или config.local.ini) в той же директории, что и основной файл (config.yml или config.ini). Значения из локального файла переопределяют соответствующие значения из основного файла.

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

Пример:

Если config.yml содержит:

# config.yml
Database:
  host: production_db.com
  port: 5432
App:
  debug: false

А config.local.yml содержит:

# config.local.yml
Database:
  host: localhost
App:
  debug: true
  developer_mode: true

Тогда get_config() вернет объединенную конфигурацию, где локальные настройки переопределяют основные:

{
    "Database": {
        "host": "localhost",  # Переопределено локальным файлом
        "port": 5432  # Взято из основного файла
    },
    "App": {
        "debug": True,  # Переопределено локальным файлом
        "developer_mode": True  # Добавлено из локального файла
    }
}

Важно: Убедитесь, что вы добавили config.local.yml (или config.local.ini) в ваш .gitignore, чтобы случайно не закоммитить локальные или чувствительные настройки.

Модуль logger

chutils.logger

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

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

ChutilsLogger

Bases: Logger

Кастомный класс логгера, расширяющий стандартный logging.Logger.

Добавляет поддержку пользовательских уровней логирования (devdebug и mediumdebug), обеспечивая при этом корректную работу статических анализаторов и автодополнения в IDE.

Иерархия уровней

• DEVDEBUG (9): Максимально подробный вывод для глубокой отладки. Предназначен для вывода дампов переменных, внутренних состояний и т.д.
• DEBUG (10): Стандартный отладочный уровень.
• MEDIUMDEBUG (15): Промежуточный уровень между DEBUG и INFO. Полезен для менее критичной, но более подробной, чем INFO, информации.
• INFO (20): Стандартный информационный уровень.

Note

Не создавайте экземпляр напрямую. Используйте setup_logger().

Example

logger: ChutilsLogger = setup_logger()
logger.devdebug("Максимально подробное сообщение")

devdebug(message, *args, **kws)

Логирует сообщение с уровнем DEVDEBUG (9).

Parameters:

Name	Type	Description	Default
message	str	Сообщение для логирования.	required
*args	Any	Аргументы форматирования.	()
**kws	Any	Ключевые слова для логгера.	{}

mediumdebug(message, *args, **kws)

Логирует сообщение с уровнем MEDIUMDEBUG (15).

Parameters:

Name	Type	Description	Default
message	str	Сообщение для логирования.	required
*args	Any	Аргументы форматирования.	()
**kws	Any	Ключевые слова для логгера.	{}

CompressingRotatingFileHandler

Bases: RotatingFileHandler

Обработчик ротации по размеру с поддержкой сжатия (gzip).

Обеспечивает корректную работу с цепочкой сжатых бэкапов.

doRollover()

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

Процесс: 1. Закрытие текущего потока. 2. Сдвиг существующих архивов (log.1.gz -> log.2.gz). 3. Переименование текущего лога в log.1. 4. Открытие нового файла для дальнейшей записи. 5. Сжатие переименованного файла в фоне.

CompressingTimedRotatingFileHandler

Bases: SafeTimedRotatingFileHandler

Обработчик ротации по времени с поддержкой сжатия (gzip).

doRollover()

Выполняет временную ротацию и сжимает полученные бэкапы.

LogLevel

Bases: str, Enum

Перечисление для поддерживаемых уровней логирования.

SafeTimedRotatingFileHandler

Bases: TimedRotatingFileHandler

Надежный обработчик ротации логов, адаптированный для Windows.

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

doRollover()

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

setup_logger(name='app_logger', config_section_name=None, log_level=None, log_file_name=None, force_reconfigure=False, rotation_type=None, max_bytes=None, compress=None, backup_count=None, encoding=None, when=None, interval=None, utc=None, at_time=None, **kwargs)

Настраивает и возвращает экземпляр логгера.

Приоритет настроек: 0. Переменные окружения CH_LOG_NO_TIME и CH_LOG_NO_FILE имеют наивысший приоритет. 1. Явные аргументы, переданные в эту функцию. 2. Объединенные настройки из Logging.loggers.{name} (если есть) поверх Logging.default (если есть). 3. Для обратной совместимости: если Logging.default и Logging.loggers отсутствуют, используются прямые настройки из Logging (как в старом формате). 4. Значения по умолчанию, зашитые в коде.

Parameters:

Name	Type	Description	Default
name	str	Имя логгера. app_logger используется как стандартное имя.	'app_logger'
config_section_name	Optional[str]	Имя секции в конфиге (например, 'MyAuditLogger'). Если указана, настройки из этой секции переопределяют настройки из общей секции [Logging]. Если не указана, используется только общая секция [Logging].	None
log_level	Optional[LogLevel]	Уровень логирования (строка или LogLevel).	None
log_file_name	Optional[str]	Имя файла для логирования. Если не указано, имя берется из конфигурации ('Logging', 'log_file_name').	None
force_reconfigure	bool	Удалить существующие обработчики и настроить заново.	False
rotation_type	Optional[str]	Тип ротации ('time' или 'size').	None
max_bytes	Optional[int]	Макс. размер файла для ротации по 'size'.	None
compress	Optional[bool]	Сжимать ли ротированные логи в .gz.	None
backup_count	Optional[int]	Количество хранимых ротированных файлов.	None
encoding	Optional[str]	Кодировка файла (по умолчанию 'utf-8').	None
when	Optional[str]	Для 'time'. Тип интервала ('S', 'M', 'H', 'D', 'midnight', 'W0'-'W6').	None
interval	Optional[int]	Для 'time'. Длина интервала.	None
utc	Optional[bool]	Для 'time'. Использовать UTC время.	None
at_time	Optional[time]	Для 'time'. Время ротации (при when='midnight').	None
**kwargs	Any	Дополнительные параметры для FileHandler (например, delay=True, errors='ignore', mode='a').	{}

Returns:

Type	Description
ChutilsLogger	Настроенный экземпляр ChutilsLogger.

options: members:

• setup_logger
• ChutilsLogger
• DEVDEBUG_LEVEL_NUM
• MEDIUMDEBUG_LEVEL_NUM

Расширенная настройка логгера: управление уровнем, ротацией и сжатием

Функция setup_logger предлагает гибкую настройку логгеров, включая управление уровнем логирования, ротацией файлов и их сжатием.

Ключевые особенности и изменения:

• Динамическое обновление уровня логирования: При каждом вызове setup_logger для существующего логгера его уровень логирования всегда обновляется до указанного или настроенного значения.
• Гибкий log_level: Параметр log_level теперь может принимать как объекты LogLevel (например, LogLevel.INFO), так и их строковое представление (например, "INFO", "DEBUG"). Это позволяет удобно задавать уровень как через код, так и через конфигурационные файлы.
• Идемпотентная настройка обработчиков: Обработчики логов (для консоли и файлов) настраиваются только при первом вызове для данного логгера. При последующих вызовах обработчики не пересоздаются, если только не указан флаг force_reconfigure=True. Это предотвращает дублирование обработчиков и обеспечивает эффективную работу.
• Расширенные опции ротации и сжатия: Поддерживаются различные типы ротации (по времени или по размеру), а также автоматическое сжатие ротированных файлов в .gz для экономии места. Эти параметры могут быть заданы как напрямую в вызове setup_logger, так и через конфигурационный файл config.yml в секции Logging.

Параметры ротации:

• rotation_type (строка): Определяет тип ротации.
  • 'time' (по умолчанию): Ротация происходит по времени (например, ежедневно).
  • 'size': Ротация происходит, когда файл лога достигает определенного размера.
• max_bytes (целое число): Максимальный размер файла лога в байтах. Используется только если rotation_type установлен в 'size'. При достижении этого размера файл будет ротирован. Значение 0 означает отсутствие лимита по размеру.
• compress (булево): Если True, ротированные файлы логов будут автоматически сжиматься в формат .gz. Это помогает экономить место на диске.
• backup_count (целое число): Количество ротированных файлов логов, которые будут храниться. Старые файлы, превышающие это количество, будут удаляться.

Гибкая настройка логгеров через конфигурацию: параметр config_section_name

Теперь setup_logger позволяет гибко управлять настройками разных логгеров через конфигурационный файл, используя параметр config_section_name.

Приоритет настроек:

1. Аргументы функции: Значения, переданные напрямую в setup_logger (например, log_level=...), имеют наивысший приоритет.
2. Секция, указанная в config_section_name: Если в setup_logger передан параметр config_section_name="MyLogger", то настройки будут искаться в секции [MyLogger] (например, [AuditLogger] или [EventLogger]).
3. Общая секция [Logging]: Если настройка не найдена в специфичной секции (или та не указана), поиск происходит в общей секции [Logging]. Она служит для задания настроек по умолчанию для всех логгеров.
4. Встроенные значения: Если настройка не найдена нигде, используется жестко заданное в коде значение (например, rotation_type='time').

Пример конфигурации (config.yml):

# config.yml

# Общая секция, задает настройки по умолчанию для всех логгеров
Logging:
  log_level: INFO
  rotation_type: time
  compress: true
  log_backup_count: 5

# Специфичная секция для логгера аудита
AuditLogger:
  log_level: DEBUG           # Переопределяет log_level из [Logging]
  log_file_name: "audit.log" # Задает уникальное имя файла
  log_backup_count: 30       # Переопределяет log_backup_count из [Logging]

# Специфичная секция для логгера событий
EventLogger:
  log_file_name: "events.log"
  rotation_type: size        # Переопределяет тип ротации
  max_bytes: 10485760        # 10 МБ

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

from chutils import setup_logger

# 1. Логгер с настройками по умолчанию из секции [Logging]
# Так как config_section_name не указан, используется только [Logging].
main_logger = setup_logger("main_app")
main_logger.info("Это сообщение от основного логгера.")  # Уровень INFO

# 2. Логгер аудита со специфичными настройками
# Явно указываем, что нужно прочитать секцию [AuditLogger]
audit_logger = setup_logger("audit", config_section_name="AuditLogger")
audit_logger.debug("Это отладочное сообщение для аудита.")  # Уровень DEBUG

# 3. Логгер событий со своими настройками
event_logger = setup_logger("events", config_section_name="EventLogger")
event_logger.info("Логгер событий использует ротацию по размеру.")  # Уровень INFO из [Logging]

# 4. Явное переопределение аргументом функции (высший приоритет)
# Уровень будет WARNING, несмотря на настройки в config.yml
important_logger = setup_logger("important", log_level="WARNING")

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

1. Ротация по размеру со сжатием:

Чтобы настроить логгер, который ротирует файлы при достижении 1 МБ и сжимает старые бэкапы, используйте:

from chutils import setup_logger

logger = setup_logger(
    "my_app_size_rotated",
    log_file_name="app_size.log",
    rotation_type='size',
    max_bytes=1048576,  # 1 МБ
    compress=True,
    backup_count=5
)
logger.info("Это сообщение будет записано в файл app_size.log, который будет ротироваться по размеру и сжиматься.")

2. Ежедневная ротация со сжатием (по умолчанию):

Для ежедневной ротации со сжатием (это поведение по умолчанию, если rotation_type не указан или равен 'time'):

from chutils import setup_logger

logger = setup_logger(
    "my_app_time_rotated",
    log_file_name="app_time.log",
    rotation_type='time',  # Можно опустить, так как это значение по умолчанию
    compress=True,
    backup_count=7
)
logger.info("Это сообщение будет записано в файл app_time.log, который будет ротироваться ежедневно и сжиматься.")

3. Настройка через config.yml:

Вы также можете управлять этими параметрами через ваш config.yml:

# config.yml
Logging:
  log_level: INFO
  log_file_name: app.log
  rotation_type: size      # Или 'time'
  max_bytes: 5242880       # 5 МБ, если rotation_type: size
  compress: true           # Сжимать ротированные файлы
  log_backup_count: 10     # Хранить 10 бэкапов

При такой конфигурации вызов setup_logger() без явных параметров автоматически применит эти настройки:

from chutils import setup_logger

logger = setup_logger("my_app")
logger.info("Настройки ротации и сжатия взяты из config.yml.")

Пример создания нескольких логгеров

Вы можете создавать разные логгеры для разных частей вашего приложения, передавая уникальное имя в setup_logger. Параметр log_file_name позволяет указать отдельный файл для каждого логгера, что помогает фильтровать и разделять логи.

# main.py
from chutils import setup_logger

# Основной логгер приложения будет писать в main_app.log
main_logger = setup_logger("main_app", log_file_name="main_app.log")
# Логгер для модуля, отвечающего за работу с базой данных, будет писать в database.log
db_logger = setup_logger("database", log_file_name="database.log")

main_logger.info("Приложение запущено.")
db_logger.debug("Инициализация подключения к БД...")

В лог-файлах вы увидите сообщения от соответствующих логгеров. Более подробный пример можно найти в файле ../examples/05_different_log_levels.py.

Модуль secret_manager

chutils.secret_manager

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

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

SecretManager

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

Приоритет получения секрета: 1. Системное хранилище (keyring). 2. Переменные из .env файла в корне проекта. 3. Переменные окружения ОС.

Attributes:

Name	Type	Description
service_name	str	Полное имя сервиса для keyring.
disable_keyring	bool	Флаг отключения работы с keyring.

__init__(service_name=None, prefix=None)

Инициализирует менеджер и лениво загружает переменные из .env файла.

Порядок определения service_name: 1. Значение, переданное в конструктор (если оно не пустое). 2. Значение из конфигурационного файла (секция Secrets, ключ service_name). 3. Абсолютный путь к корню проекта (для гарантированной уникальности).

Parameters:

Name	Type	Description	Default
service_name	Optional[str]	Опциональное уникальное имя для вашего приложения.	None
prefix	Optional[str]	Опциональный префикс для service_name. Если не указан, будет взят из конфига (ключ prefix) или использован "Chutils_".	None

Raises:

Type	Description
ValueError	Если не удалось определить service_name.

adelete_secret(key) async

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

Parameters:

Name	Type	Description	Default
key	str	Ключ секрета.	required

Returns:

Type	Description
bool	True, если секрет был удален или уже не существовал.
bool	False, если произошла ошибка при удалении.

aget_secret(key) async

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

Parameters:

Name	Type	Description	Default
key	str	Ключ секрета.	required

Returns:

Type	Description
Optional[str]	Значение секрета или None.

asave_secret(key, value) async

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

Parameters:

Name	Type	Description	Default
key	str	Ключ секрета.	required
value	str	Секретное значение.	required

Returns:

Type	Description
bool	True, если секрет успешно сохранен в keyring.
bool	False, если произошла ошибка.

delete_secret(key)

Удаляет пару ключ-значение из системного хранилища (keyring). Эта функция не влияет на переменные окружения или .env файлы.

Parameters:

Name	Type	Description	Default
key	str	Ключ секрета.	required

Returns:

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

get_secret(key)

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

Поиск происходит в следующем порядке: 1. Системное хранилище (keyring). 2. Переменные из .env файла / переменные окружения.

Parameters:

Name	Type	Description	Default
key	str	Ключ секрета.	required

Returns:

Type	Description
Optional[str]	Значение секрета или None, если ключ не найден.

save_secret(key, value)

Сохраняет пару ключ-значение в системном хранилище (keyring). Эта функция не влияет на переменные окружения или .env файлы.

Parameters:

Name	Type	Description	Default
key	str	Ключ секрета.	required
value	str	Секретное значение.	required

Returns:

Type	Description
bool	True, если секрет успешно сохранен в keyring.
bool	False, если произошла ошибка.

update_secret(key, value)

Обновляет значение для существующего ключа в системном хранилище (keyring). Это псевдоним для save_secret.

Parameters:

Name	Type	Description	Default
key	str	Ключ секрета.	required
value	str	Новое значение.	required

Returns:

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

Конфигурация SecretManager и предотвращение конфликтов

Для безопасной работы с keyring крайне важно, чтобы каждое приложение использовало уникальное имя сервиса ( service_name). Это предотвращает конфликты, когда два разных приложения могут случайно перезаписать секреты друг друга.

SecretManager определяет service_name по следующему приоритету:

1. Значение, переданное в конструктор: python from chutils import SecretManager # Явное указание имени сервиса (наивысший приоритет) secrets = SecretManager("my-super-unique-app-name")

2. Значение из конфигурационного файла: Если service_name не передан в конструктор (или передан пустым), SecretManager попытается найти его в вашем config.yml файле в секции Secrets. yaml # config.yml Secrets: service_name: my-super-unique-app-name prefix: "WebApp_" # Опционально, можно переопределить префикс В этом случае SecretManager можно инициализировать без аргументов: python from chutils import SecretManager # Имя будет взято из config.yml secrets = SecretManager()

3. Абсолютный путь к проекту (поведение по умолчанию): Если имя не найдено ни в конструкторе, ни в конфигурации, SecretManager автоматически использует абсолютный путь к корню вашего проекта в качестве service_name.

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

Префикс

Итоговое имя сервиса в keyring формируется как prefix + service_name. Префикс также можно настроить. Порядок приоритета для префикса:

1. Значение, переданное в конструктор.
2. Значение из config.yml (секция Secrets, ключ prefix).
3. Значение по умолчанию: "Chutils_".