Справочник 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")
init(base_dir)
Ручная инициализация пакета с указанием базовой директории проекта.
Эту функцию нужно вызывать только в том случае, если автоматическое определение корня проекта не сработало. Вызывать следует один раз в самом начале работы основного скрипта вашего приложения.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
base_dir
|
str
|
Абсолютный путь к корневой директории проекта. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
Если указанная директория не существует. |
Модуль config
chutils.config
Модуль для работы с конфигурацией.
Обеспечивает автоматический поиск файла config.yml, config.yaml или config.ini
в корне проекта и предоставляет удобные функции для чтения настроек.
find_project_root(start_path, markers)
Ищет корень проекта, двигаясь вверх по дереву каталогов.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
start_path
|
Path
|
Директория, с которой начинается поиск. |
required |
markers
|
List[str]
|
Список имен файлов или папок (маркеров), наличие которых в директории указывает на то, что это корень проекта. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Optional[Path]
|
Объект Path, представляющий корневую директорию проекта |
|
None |
Optional[Path]
|
Если корень не был найден. |
get_config()
Загружает конфигурацию из файла (YAML или INI) и возвращает ее как словарь. Результат кэшируется для последующих вызовов.
Returns:
| Name | Type | Description |
|---|---|---|
_config_object |
Dict
|
Словарь с загруженной конфигурацией. |
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
|
Булево значение из конфигурации или |
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
|
Дробное число из конфигурации или |
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
|
Целое число из конфигурации или |
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]
|
Список из конфигурации или |
List[Any]
|
возвращается пустой список. |
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]
|
Словарь с содержимым секции или |
Dict[str, Any]
|
возвращается пустой словарь. |
get_config_value(section, key, fallback='', config=None)
Получает значение из конфигурации.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
section
|
str
|
Имя секции. |
required |
key
|
str
|
Имя ключа. |
required |
fallback
|
Any
|
Значение по умолчанию, если ключ не найден. |
''
|
config
|
Optional[Dict]
|
Опциональный, предварительно загруженный словарь конфигурации. |
None
|
Returns:
| Type | Description |
|---|---|
Any
|
Значение из конфигурации или |
save_config_value(section, key, value, cfg_file=None)
Сохраняет одно значение в конфигурационном файле.
Warning
Важно: При сохранении в .yml комментарии и форматирование будут утеряны.
При сохранении в .ini - сохраняются.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
section
|
str
|
Имя секции. |
required |
key
|
str
|
Имя ключа в секции. |
required |
value
|
Any
|
Новое значение для ключа. |
required |
cfg_file
|
Optional[str]
|
Опциональный путь к файлу. Если не указан, будет использован автоматически найденный файл. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
True |
bool
|
Если значение было успешно обновлено и сохранено. |
False |
bool
|
Если файл не найден, или произошла ошибка. |
Модуль logger
chutils.logger
Модуль для настройки логирования.
Предоставляет унифицированную функцию setup_logger для создания и настройки логгеров, которые могут выводить сообщения в консоль и в файлы с автоматической ротацией. Директория для логов ('logs') создается автоматически в корне проекта.
ChutilsLogger
Bases: Logger
Кастомный класс логгера, который расширяет стандартный logging.Logger.
Добавляет поддержку пользовательских уровней логирования (devdebug и mediumdebug).
Обеспечивая при этом корректную работу статических анализаторов и автодополнения в IDE.
Note
Вам не нужно создавать экземпляр этого класса напрямую. Используйте
функцию setup_logger(), которая автоматически вернет объект этого типа.
Example
from chutils.logger import setup_logger, ChutilsLogger
# Используем наш класс для аннотации типа, чтобы IDE давала подсказки
logger: ChutilsLogger = setup_logger()
# Теперь IDE знает об этом методе и не будет показывать предупреждений
logger.mediumdebug("Это сообщение с автодополнением.")
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
|
Ключевые слова для |
{}
|
setup_logger(name='app_logger', log_level_str='')
Настраивает и возвращает логгер с нужным именем.
Функция идемпотентна: она предотвращает повторную настройку уже существующего логгера. Настройки (уровень, имя файла и т.д.) читаются из конфигурационного файла. По умолчанию добавляются обработчики для вывода в консоль и в файл с ежедневной ротацией.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Имя логгера. |
'app_logger'
|
log_level_str
|
str
|
Явное указание уровня логирования (например, 'DEBUG'). Если не задан, значение берется из конфигурационного файла, а если и там нет - используется 'INFO'. |
''
|
Returns:
| Type | Description |
|---|---|
ChutilsLogger
|
logging.Logger: Настроенный экземпляр ChutilsLogger. |
Модуль secret_manager
chutils.secret_manager
SecretManager
Универсальный менеджер для безопасного хранения и получения секретов с использованием системного хранилища (keyring).
Использует системное хранилище (keyring) для безопасного хранения данных.
Изолирует секреты разных приложений с помощью префикса и service_name.
Attributes:
| Name | Type | Description |
|---|---|---|
service_name |
str
|
Полное имя сервиса, используемое в keyring. |
__init__(service_name)
Инициализирует менеджер для конкретного сервиса (приложения).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
service_name
|
str
|
Уникальное имя для вашего приложения, например, 'my_super_app' или 'project_alpha_db'. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
Если |
delete_secret(key)
Удаляет пару ключ-значение из системного хранилища.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
Ключ секрета, который нужно удалить. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True, если секрет был удален или уже не существовал. |
bool
|
False, если произошла ошибка при удалении. |
get_secret(key)
Получает секретное значение по ключу из системного хранилища.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
Ключ, по которому нужно найти секрет. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
value |
str
|
Сохраненное значение |
None |
None
|
Если ключ не найден или произошла ошибка. |
save_secret(key, value)
Сохраняет пару ключ-значение в системном хранилище. Если ключ уже существует, его значение будет перезаписано.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
Ключ для секрета (например, 'db_password' или 'api_token'). |
required |
value
|
str
|
Секретное значение, которое нужно сохранить. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
True |
bool
|
Если секрет успешно сохранен. |
False |
bool
|
Если произошла ошибка. |
update_secret(key, value)
Обновляет значение для существующего ключа.
Это псевдоним для функции save_secret,
так как keyring по умолчанию перезаписывает значение при сохранении.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
Ключ для секрета (например, 'db_password' или 'api_token'). |
required |
value
|
str
|
Новое секретное значение. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
True |
bool
|
Если секрет успешно обновлен. |
False |
bool
|
В случае возникновения ошибки. |