chutils 2.0.0__tar.gz → 2.1.0__tar.gz

{chutils-2.0.0 → chutils-2.1.0}/PKG-INFO

@@ -1,8 +1,9 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: chutils
-Version: 2.0.0
-Summary: 
+Version: 2.1.0
+Summary: Набор простых и удобных утилит для Python, который избавляет от рутины при работе с конфигурацией и логированием в новых проектах.
 License: MIT
+License-File: LICENSE
 Author: Sergo
 Author-email: sergeiivanov636@gmail.com
 Requires-Python: >=3.9
@@ -13,16 +14,21 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: keyring (>=25.6.0,<26.0.0)
 Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
 Description-Content-Type: text/markdown
 
-# chutils
+# chutils: Рутина — в прошлом!
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![PyPI version](https://badge.fury.io/py/chutils.svg)](https://badge.fury.io/py/chutils)
 
-Набор простых и удобных утилит для Python, который избавляет от рутины при работе с конфигурацией, логированием и
-секретами в новых проектах.
+**chutils** — это набор простых утилит для Python, который избавляет от повторяющейся настройки конфигурации,
+логирования и секретов в ваших проектах.
+
+Начните новый проект и сразу сфокусируйтесь на главном, а не на рутине.
 
 ## Проблема
 
@@ -30,15 +36,15 @@ Description-Content-Type: text/markdown
 
 - Как удобно читать настройки из файла конфигурации?
 - Как настроить логирование, чтобы сообщения писались и в консоль, и в файл с ежедневной ротацией?
-- Как безопасно хранить API-ключи и пароли, не записывая их в код или в файлы конфигурации?
-- Как сделать так, чтобы все это работало без жестко прописанных путей сразу после установки?
+- Как безопасно хранить API-ключи, не прописывая их в коде?
+- Как сделать, чтобы всё это работало "из коробки", без прописывания путей?
 
-**chutils** решает эти проблемы.
+**chutils** предлагает готовые решения для всех этих проблем.
 
 ## Ключевые возможности
 
-- **✨ Ноль конфигурации:** Библиотека **автоматически** находит корень вашего проекта и файл конфигурации (`config.yml`
-  или `config.ini`).
+- **✨ Ноль конфигурации:** Библиотека **автоматически** находит корень вашего проекта и файл `config.yml` или
+  `config.ini`.
 - **⚙️ Гибкая конфигурация:** Поддержка `YAML` и `INI` форматов. Простые функции для получения типизированных данных.
 - **✍️ Продвинутый логгер:** Функция `setup_logger()` "из коробки" настраивает логирование в консоль и в ротируемые
   файлы. Возвращает кастомный логгер с дополнительными уровнями отладки (`devdebug`, `mediumdebug`).
@@ -66,18 +72,101 @@ cd chutils
 pip install -e .
 ```
 
+## Примеры использования
+
+В папке [`/examples`](./examples/) вы найдете готовые к запуску скрипты, демонстрирующие ключевые возможности
+библиотеки. Каждый пример сфокусирован на одной конкретной задаче.
+
 ## Быстрый старт
 
-1. Создайте в корне вашего проекта файл `config.yml`.
+### 1. Работа с конфигурацией
+
+1. Создайте файл `config.yml` в корне вашего проекта:
 
-   **Структура проекта:**
+   ```yaml
+   # config.yml
+   Database:
+     host: localhost
+     port: 5432
+     user: my_user
    ```
-   my_awesome_app/
-   ├── main.py
-   └── config.yml
+
+2. Получайте значения в вашем коде:
+
+   ```python
+   # main.py
+   from chutils import get_config_value, get_config_int
+
+   db_host = get_config_value("Database", "host", fallback="127.0.0.1")
+   db_port = get_config_int("Database", "port", fallback=5433)
+
+   print(f"Подключаемся к БД по адресу: {db_host}:{db_port}")
+   # Вывод: Подключаемся к БД по адресу: localhost:5432
    ```
+   `chutils` автоматически найдет `config.yml` и прочитает из него данные.
+
+### 2. Настройка логирования
+
+1. Добавьте секцию `Logging` в ваш `config.yml` (опционально):
 
-   **Содержимое `config.yml`:**
+   ```yaml
+   # config.yml
+   Logging:
+     log_level: DEBUG
+     log_file_name: my_app.log
+   ```
+
+2. Используйте логгер:
+
+   ```python
+   # main.py
+   from chutils import setup_logger, ChutilsLogger
+
+   # Настраиваем логгер. Он сам прочитает настройки из конфига.
+   logger: ChutilsLogger = setup_logger()
+
+   logger.info("Приложение запущено.")
+   logger.debug("Это отладочное сообщение.")
+   # Вывод в консоли и запись в файл logs/my_app.log
+   ```
+   Папка `logs` будет создана автоматически.
+
+### 3. Управление секретами
+
+1. Инициализируйте `SecretManager` и сохраните ваш секрет. **Это нужно сделать один раз.**
+
+   ```python
+   # setup_secrets.py
+   from chutils import SecretManager
+
+   secrets = SecretManager("my_awesome_app")
+   secrets.save_secret("db_password", "MySuperSecretDbPassword123!")
+   print("Пароль от БД сохранен в системном хранилище!")
+   ```
+
+2. Получайте секрет в основном коде, не "светя" им:
+
+   ```python
+   # main.py
+   from chutils import SecretManager, get_config_value
+
+   secrets = SecretManager("my_awesome_app")
+   db_user = get_config_value("Database", "user")
+
+   # Получаем пароль из безопасного хранилища
+   db_password = secrets.get_secret("db_password")
+
+   if db_password:
+       print(f"Получен пароль для пользователя {db_user}.")
+   else:
+       print("Пароль не найден!")
+   ```
+
+## Комплексный пример
+
+Этот пример показывает, как все компоненты `chutils` работают вместе.
+
+1. **Файл `config.yml`:**
    ```yaml
    API:
      base_url: https://api.example.com
@@ -86,10 +175,12 @@ pip install -e .
      host: localhost
      port: 5432
      user: my_user
-   ```
 
-2. Используйте `chutils` в вашем коде `main.py`:
+   Logging:
+     log_level: INFO
+   ```
 
+2. **Код `main.py`:**
    ```python
    # main.py
    from chutils import get_config_value, setup_logger, SecretManager, ChutilsLogger
@@ -101,15 +192,17 @@ pip install -e .
    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!")
+       password_key = f"{db_user}_password"
+
+       if not secrets.get_secret(password_key):
+           logger.info("Пароль для БД не найден. Сохраняем новый...")
+           secrets.save_secret(password_key, "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")
@@ -118,7 +211,7 @@ pip install -e .
            logger.error("Не удалось получить пароль для БД!")
            return
 
-       logger.info(f"Подключаемся к базе данных по адресу {db_host} от имени {db_user}...")
+       logger.info(f"Подключаемся к {db_host} от имени {db_user}...")
        # ... логика подключения ...
        logger.info("Успешно подключились!")
 
@@ -132,10 +225,7 @@ pip install -e .
        main()
    ```
 
-3. Запустите ваш скрипт. Вы увидите логи в консоли, а в проекте появится папка `logs` с файлом лога. Пароль от БД будет
-   надежно сохранен в системном хранилище.
-
-## API и Использование
+## API
 
 ### Работа с конфигурацией (`chutils.config`)
 
@@ -144,8 +234,8 @@ pip install -e .
 - `get_config_boolean(section, key, fallback=False)`: Получить булево значение.
 - `get_config_list(section, key, fallback=[])`: Получить список.
 - `get_config_section(section)`: Получить всю секцию как словарь.
-- `save_config_value(section, key, value)`: Сохранить значение. **Важно: работает только для `.ini` файлов** для
-  сохранения комментариев.
+- `save_config_value(section, key, value)`: Сохранить значение. Работает для `.yml` и `.ini`.
+  **Важно**: при сохранении в `.yml` комментарии и форматирование будут утеряны. При сохранении в `.ini` - сохраняются.
 
 ### Настройка логирования (`chutils.logger`)
 
@@ -163,7 +253,7 @@ pip install -e .
 ### Ручная инициализация (`chutils.init`)
 
 В 99% случаев вам это **не понадобится**. Но если автоматика не справилась, вы можете один раз указать путь к проекту
-вручную:
+вручную в самом начале работы приложения:
 
 ```python
 import chutils
@@ -171,26 +261,7 @@ import chutils
 chutils.init(base_dir="/path/to/my/project/root")
 ```
 
-### Пример файла `config.yml`
-
-`chutils` использует секцию `Logging` для настройки логгера.
-
-```yaml
-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.
+

{chutils-2.0.0 → chutils-2.1.0}/README.md

@@ -1,9 +1,13 @@
-# chutils
+# chutils: Рутина — в прошлом!
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![PyPI version](https://badge.fury.io/py/chutils.svg)](https://badge.fury.io/py/chutils)
 
-Набор простых и удобных утилит для Python, который избавляет от рутины при работе с конфигурацией, логированием и
-секретами в новых проектах.
+**chutils** — это набор простых утилит для Python, который избавляет от повторяющейся настройки конфигурации,
+логирования и секретов в ваших проектах.
+
+Начните новый проект и сразу сфокусируйтесь на главном, а не на рутине.
 
 ## Проблема
 
@@ -11,15 +15,15 @@
 
 - Как удобно читать настройки из файла конфигурации?
 - Как настроить логирование, чтобы сообщения писались и в консоль, и в файл с ежедневной ротацией?
-- Как безопасно хранить API-ключи и пароли, не записывая их в код или в файлы конфигурации?
-- Как сделать так, чтобы все это работало без жестко прописанных путей сразу после установки?
+- Как безопасно хранить API-ключи, не прописывая их в коде?
+- Как сделать, чтобы всё это работало "из коробки", без прописывания путей?
 
-**chutils** решает эти проблемы.
+**chutils** предлагает готовые решения для всех этих проблем.
 
 ## Ключевые возможности
 
-- **✨ Ноль конфигурации:** Библиотека **автоматически** находит корень вашего проекта и файл конфигурации (`config.yml`
-  или `config.ini`).
+- **✨ Ноль конфигурации:** Библиотека **автоматически** находит корень вашего проекта и файл `config.yml` или
+  `config.ini`.
 - **⚙️ Гибкая конфигурация:** Поддержка `YAML` и `INI` форматов. Простые функции для получения типизированных данных.
 - **✍️ Продвинутый логгер:** Функция `setup_logger()` "из коробки" настраивает логирование в консоль и в ротируемые
   файлы. Возвращает кастомный логгер с дополнительными уровнями отладки (`devdebug`, `mediumdebug`).
@@ -47,18 +51,101 @@ cd chutils
 pip install -e .
 ```
 
+## Примеры использования
+
+В папке [`/examples`](./examples/) вы найдете готовые к запуску скрипты, демонстрирующие ключевые возможности
+библиотеки. Каждый пример сфокусирован на одной конкретной задаче.
+
 ## Быстрый старт
 
-1. Создайте в корне вашего проекта файл `config.yml`.
+### 1. Работа с конфигурацией
+
+1. Создайте файл `config.yml` в корне вашего проекта:
+
+   ```yaml
+   # config.yml
+   Database:
+     host: localhost
+     port: 5432
+     user: my_user
+   ```
+
+2. Получайте значения в вашем коде:
+
+   ```python
+   # main.py
+   from chutils import get_config_value, get_config_int
+
+   db_host = get_config_value("Database", "host", fallback="127.0.0.1")
+   db_port = get_config_int("Database", "port", fallback=5433)
+
+   print(f"Подключаемся к БД по адресу: {db_host}:{db_port}")
+   # Вывод: Подключаемся к БД по адресу: localhost:5432
+   ```
+   `chutils` автоматически найдет `config.yml` и прочитает из него данные.
+
+### 2. Настройка логирования
+
+1. Добавьте секцию `Logging` в ваш `config.yml` (опционально):
+
+   ```yaml
+   # config.yml
+   Logging:
+     log_level: DEBUG
+     log_file_name: my_app.log
+   ```
+
+2. Используйте логгер:
+
+   ```python
+   # main.py
+   from chutils import setup_logger, ChutilsLogger
+
+   # Настраиваем логгер. Он сам прочитает настройки из конфига.
+   logger: ChutilsLogger = setup_logger()
+
+   logger.info("Приложение запущено.")
+   logger.debug("Это отладочное сообщение.")
+   # Вывод в консоли и запись в файл logs/my_app.log
+   ```
+   Папка `logs` будет создана автоматически.
+
+### 3. Управление секретами
+
+1. Инициализируйте `SecretManager` и сохраните ваш секрет. **Это нужно сделать один раз.**
+
+   ```python
+   # setup_secrets.py
+   from chutils import SecretManager
 
-   **Структура проекта:**
+   secrets = SecretManager("my_awesome_app")
+   secrets.save_secret("db_password", "MySuperSecretDbPassword123!")
+   print("Пароль от БД сохранен в системном хранилище!")
    ```
-   my_awesome_app/
-   ├── main.py
-   └── config.yml
+
+2. Получайте секрет в основном коде, не "светя" им:
+
+   ```python
+   # main.py
+   from chutils import SecretManager, get_config_value
+
+   secrets = SecretManager("my_awesome_app")
+   db_user = get_config_value("Database", "user")
+
+   # Получаем пароль из безопасного хранилища
+   db_password = secrets.get_secret("db_password")
+
+   if db_password:
+       print(f"Получен пароль для пользователя {db_user}.")
+   else:
+       print("Пароль не найден!")
    ```
 
-   **Содержимое `config.yml`:**
+## Комплексный пример
+
+Этот пример показывает, как все компоненты `chutils` работают вместе.
+
+1. **Файл `config.yml`:**
    ```yaml
    API:
      base_url: https://api.example.com
@@ -67,10 +154,12 @@ pip install -e .
      host: localhost
      port: 5432
      user: my_user
-   ```
 
-2. Используйте `chutils` в вашем коде `main.py`:
+   Logging:
+     log_level: INFO
+   ```
 
+2. **Код `main.py`:**
    ```python
    # main.py
    from chutils import get_config_value, setup_logger, SecretManager, ChutilsLogger
@@ -82,15 +171,17 @@ pip install -e .
    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!")
+       password_key = f"{db_user}_password"
+
+       if not secrets.get_secret(password_key):
+           logger.info("Пароль для БД не найден. Сохраняем новый...")
+           secrets.save_secret(password_key, "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")
@@ -99,7 +190,7 @@ pip install -e .
            logger.error("Не удалось получить пароль для БД!")
            return
 
-       logger.info(f"Подключаемся к базе данных по адресу {db_host} от имени {db_user}...")
+       logger.info(f"Подключаемся к {db_host} от имени {db_user}...")
        # ... логика подключения ...
        logger.info("Успешно подключились!")
 
@@ -113,10 +204,7 @@ pip install -e .
        main()
    ```
 
-3. Запустите ваш скрипт. Вы увидите логи в консоли, а в проекте появится папка `logs` с файлом лога. Пароль от БД будет
-   надежно сохранен в системном хранилище.
-
-## API и Использование
+## API
 
 ### Работа с конфигурацией (`chutils.config`)
 
@@ -125,8 +213,8 @@ pip install -e .
 - `get_config_boolean(section, key, fallback=False)`: Получить булево значение.
 - `get_config_list(section, key, fallback=[])`: Получить список.
 - `get_config_section(section)`: Получить всю секцию как словарь.
-- `save_config_value(section, key, value)`: Сохранить значение. **Важно: работает только для `.ini` файлов** для
-  сохранения комментариев.
+- `save_config_value(section, key, value)`: Сохранить значение. Работает для `.yml` и `.ini`.
+  **Важно**: при сохранении в `.yml` комментарии и форматирование будут утеряны. При сохранении в `.ini` - сохраняются.
 
 ### Настройка логирования (`chutils.logger`)
 
@@ -144,7 +232,7 @@ pip install -e .
 ### Ручная инициализация (`chutils.init`)
 
 В 99% случаев вам это **не понадобится**. Но если автоматика не справилась, вы можете один раз указать путь к проекту
-вручную:
+вручную в самом начале работы приложения:
 
 ```python
 import chutils
@@ -152,26 +240,6 @@ import chutils
 chutils.init(base_dir="/path/to/my/project/root")
 ```
 
-### Пример файла `config.yml`
-
-`chutils` использует секцию `Logging` для настройки логгера.
-
-```yaml
-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.
+Проект распространяется под лицензией MIT.

chutils-2.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[tool.poetry]
+name = "chutils"
+version = "2.1.0"
+description = "Набор простых и удобных утилит для Python, который избавляет от рутины при работе с конфигурацией и логированием в новых проектах."
+authors = ["Sergo <sergeiivanov636@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+packages = [{ include = "chutils", from = "src" }]
+
+[tool.poetry.dependencies]
+python = ">=3.9"
+keyring = "^25.6.0"
+pyyaml = "^6.0.3"
+
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.4.2"
+pytest-mock = "^3.15.1"
+pyfakefs = "^5.10.0"
+mkdocs = "^1.6.1"
+mkdocs-material = "^9.6.22"
+mkdocstrings = {extras = ["python"], version = "^0.30.1"}
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+pythonpath = [
+    "src"
+]