chutils 2.0.0

No project description provided

chutils

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

Проблема

Каждый раз, начиная новый проект, приходится решать одни и те же задачи:

• Как удобно читать настройки из файла конфигурации?
• Как настроить логирование, чтобы сообщения писались и в консоль, и в файл с ежедневной ротацией?
• Как безопасно хранить API-ключи и пароли, не записывая их в код или в файлы конфигурации?
• Как сделать так, чтобы все это работало без жестко прописанных путей сразу после установки?

chutils решает эти проблемы.

Ключевые возможности

• ✨ Ноль конфигурации: Библиотека автоматически находит корень вашего проекта и файл конфигурации (config.yml или config.ini).
• ⚙️ Гибкая конфигурация: Поддержка YAML и INI форматов. Простые функции для получения типизированных данных.
• ✍️ Продвинутый логгер: Функция setup_logger() "из коробки" настраивает логирование в консоль и в ротируемые файлы. Возвращает кастомный логгер с дополнительными уровнями отладки (devdebug, mediumdebug).
• 🔒 Безопасное хранилище секретов: Модуль secret_manager предоставляет простой интерфейс для сохранения и получения секретов через системное хранилище ключей (Keyring).
• 🚀 Готовность к работе: Просто установите и используйте.

Установка

poetry add chutils

Или с помощью pip:

pip install chutils

Для разработки клонируйте репозиторий и установите его в режиме редактирования:

git clone https://github.com/Chu4hel/chutils.git
cd chutils
pip install -e .

Быстрый старт

1. Создайте в корне вашего проекта файл config.yml.

   Структура проекта:

   my_awesome_app/
   ├── main.py
   └── config.yml
   

   Содержимое config.yml:

   API:
     base_url: https://api.example.com
   
   Database:
     host: localhost
     port: 5432
     user: my_user
   

2. Используйте chutils в вашем коде main.py:

   # main.py
   from chutils import get_config_value, setup_logger, SecretManager, ChutilsLogger
   
   # 1. Настраиваем логгер. Он автоматически прочитает настройки из конфига.
   logger: ChutilsLogger = setup_logger()
   
   # 2. Инициализируем менеджер секретов для нашего приложения.
   secrets = SecretManager("my_awesome_app")
   
   def setup_credentials():
       """Функция для первоначального сохранения пароля."""
       db_user = get_config_value("Database", "user")
       if not secrets.get_secret(f"{db_user}_password"):
           logger.info("Пароль для БД не найден. Сохраняем новый пароль...")
           secrets.save_secret(f"{db_user}_password", "MySuperSecretDbPassword123!")
           logger.info("Пароль для БД сохранен в системном хранилище.")
   
   def connect_to_db():
       # 3. Легко получаем значения из конфига и секреты из хранилища.
       db_host = get_config_value("Database", "host")
       db_user = get_config_value("Database", "user")
       db_password = secrets.get_secret(f"{db_user}_password")
   
       if not db_password:
           logger.error("Не удалось получить пароль для БД!")
           return
   
       logger.info(f"Подключаемся к базе данных по адресу {db_host} от имени {db_user}...")
       # ... логика подключения ...
       logger.info("Успешно подключились!")
   
   def main():
       logger.info("Приложение запущено.")
       setup_credentials()
       connect_to_db()
       logger.info("Приложение завершило работу.")
   
   if __name__ == "__main__":
       main()
   

3. Запустите ваш скрипт. Вы увидите логи в консоли, а в проекте появится папка logs с файлом лога. Пароль от БД будет надежно сохранен в системном хранилище.

API и Использование

Работа с конфигурацией (chutils.config)

• get_config_value(section, key, fallback=""): Получить значение.
• get_config_int(section, key, fallback=0): Получить целое число.
• get_config_boolean(section, key, fallback=False): Получить булево значение.
• get_config_list(section, key, fallback=[]): Получить список.
• get_config_section(section): Получить всю секцию как словарь.
• save_config_value(section, key, value): Сохранить значение. Важно: работает только для .ini файлов для сохранения комментариев.

Настройка логирования (chutils.logger)

• setup_logger(name='app_logger', log_level_str=''): Настраивает и возвращает экземпляр ChutilsLogger.
• logger.mediumdebug("message"): Логирование с уровнем 15.
• logger.devdebug("message"): Логирование с уровнем 9.

Управление секретами (chutils.secret_manager)

• SecretManager(service_name): Создает менеджер, изолированный по имени сервиса.
• secrets.save_secret(key, value): Сохраняет секрет.
• secrets.get_secret(key): Получает секрет.
• secrets.delete_secret(key): Удаляет секрет.

Ручная инициализация (chutils.init)

В 99% случаев вам это не понадобится. Но если автоматика не справилась, вы можете один раз указать путь к проекту вручную:

import chutils

chutils.init(base_dir="/path/to/my/project/root")

Пример файла config.yml

chutils использует секцию Logging для настройки логгера.

API:
  token: your_secret_token_here

Database:
  host: localhost

Logging:
  # Уровни: DEVDEBUG, DEBUG, MEDIUMDEBUG, INFO, WARNING, ERROR, CRITICAL
  log_level: DEBUG
  # Имя файла для логов
  log_file_name: my_app.log
  # Сколько дней хранить файлы логов
  log_backup_count: 7

Лицензия

Проект распространяется под лицензией MIT.