chutils 2.0.0__tar.gz

chutils-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chu4hel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chutils-2.0.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.3
+Name: chutils
+Version: 2.0.0
+Summary: 
+License: MIT
+Author: Sergo
+Author-email: sergeiivanov636@gmail.com
+Requires-Python: >=3.9
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: keyring (>=25.6.0,<26.0.0)
+Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
+Description-Content-Type: text/markdown
+
+# 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/)
+
+Набор простых и удобных утилит для Python, который избавляет от рутины при работе с конфигурацией, логированием и
+секретами в новых проектах.
+
+## Проблема
+
+Каждый раз, начиная новый проект, приходится решать одни и те же задачи:
+
+- Как удобно читать настройки из файла конфигурации?
+- Как настроить логирование, чтобы сообщения писались и в консоль, и в файл с ежедневной ротацией?
+- Как безопасно хранить API-ключи и пароли, не записывая их в код или в файлы конфигурации?
+- Как сделать так, чтобы все это работало без жестко прописанных путей сразу после установки?
+
+**chutils** решает эти проблемы.
+
+## Ключевые возможности
+
+- **✨ Ноль конфигурации:** Библиотека **автоматически** находит корень вашего проекта и файл конфигурации (`config.yml`
+  или `config.ini`).
+- **⚙️ Гибкая конфигурация:** Поддержка `YAML` и `INI` форматов. Простые функции для получения типизированных данных.
+- **✍️ Продвинутый логгер:** Функция `setup_logger()` "из коробки" настраивает логирование в консоль и в ротируемые
+  файлы. Возвращает кастомный логгер с дополнительными уровнями отладки (`devdebug`, `mediumdebug`).
+- **🔒 Безопасное хранилище секретов:** Модуль `secret_manager` предоставляет простой интерфейс для сохранения и
+  получения секретов через системное хранилище ключей (Keyring).
+- **🚀 Готовность к работе:** Просто установите и используйте.
+
+## Установка
+
+```bash
+poetry add chutils
+```
+
+Или с помощью pip:
+
+```bash
+pip install chutils
+```
+
+Для разработки клонируйте репозиторий и установите его в режиме редактирования:
+
+```bash
+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`:**
+   ```yaml
+   API:
+     base_url: https://api.example.com
+
+   Database:
+     host: localhost
+     port: 5432
+     user: my_user
+   ```
+
+2. Используйте `chutils` в вашем коде `main.py`:
+
+   ```python
+   # 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% случаев вам это **не понадобится**. Но если автоматика не справилась, вы можете один раз указать путь к проекту
+вручную:
+
+```python
+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/README.md

@@ -0,0 +1,177 @@
+# 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/)
+
+Набор простых и удобных утилит для Python, который избавляет от рутины при работе с конфигурацией, логированием и
+секретами в новых проектах.
+
+## Проблема
+
+Каждый раз, начиная новый проект, приходится решать одни и те же задачи:
+
+- Как удобно читать настройки из файла конфигурации?
+- Как настроить логирование, чтобы сообщения писались и в консоль, и в файл с ежедневной ротацией?
+- Как безопасно хранить API-ключи и пароли, не записывая их в код или в файлы конфигурации?
+- Как сделать так, чтобы все это работало без жестко прописанных путей сразу после установки?
+
+**chutils** решает эти проблемы.
+
+## Ключевые возможности
+
+- **✨ Ноль конфигурации:** Библиотека **автоматически** находит корень вашего проекта и файл конфигурации (`config.yml`
+  или `config.ini`).
+- **⚙️ Гибкая конфигурация:** Поддержка `YAML` и `INI` форматов. Простые функции для получения типизированных данных.
+- **✍️ Продвинутый логгер:** Функция `setup_logger()` "из коробки" настраивает логирование в консоль и в ротируемые
+  файлы. Возвращает кастомный логгер с дополнительными уровнями отладки (`devdebug`, `mediumdebug`).
+- **🔒 Безопасное хранилище секретов:** Модуль `secret_manager` предоставляет простой интерфейс для сохранения и
+  получения секретов через системное хранилище ключей (Keyring).
+- **🚀 Готовность к работе:** Просто установите и используйте.
+
+## Установка
+
+```bash
+poetry add chutils
+```
+
+Или с помощью pip:
+
+```bash
+pip install chutils
+```
+
+Для разработки клонируйте репозиторий и установите его в режиме редактирования:
+
+```bash
+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`:**
+   ```yaml
+   API:
+     base_url: https://api.example.com
+
+   Database:
+     host: localhost
+     port: 5432
+     user: my_user
+   ```
+
+2. Используйте `chutils` в вашем коде `main.py`:
+
+   ```python
+   # 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% случаев вам это **не понадобится**. Но если автоматика не справилась, вы можете один раз указать путь к проекту
+вручную:
+
+```python
+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/pyproject.toml

@@ -0,0 +1,28 @@
+[tool.poetry]
+name = "chutils"
+version = "2.0.0"
+description = ""
+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"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+pythonpath = [
+  "src"
+]

chutils-2.0.0/src/chutils/__init__.py

@@ -0,0 +1,102 @@
+"""
+Пакет 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")
+
+"""
+
+import os
+
+from . import config
+from . import logger
+
+# --- Импорт публичных функций и классов ---
+# Явно импортируем все, что должно быть доступно пользователю напрямую из пакета chutils.
+
+from .config import (
+    get_config,
+    get_config_value,
+    get_config_int,
+    get_config_float,
+    get_config_boolean,
+    get_config_list,
+    get_config_section
+)
+from .logger import setup_logger, ChutilsLogger
+from .secret_manager import SecretManager
+
+
+def init(base_dir: str):
+    """
+    Ручная инициализация пакета с указанием базовой директории проекта.
+
+    Эту функцию нужно вызывать только в том случае, если автоматическое
+    определение корня проекта не сработало. Вызывать следует один раз
+    в самом начале работы основного скрипта вашего приложения.
+
+    Args:
+        base_dir (str): Абсолютный путь к корневой директории проекта.
+
+    Raises:
+        ValueError: Если указанная директория не существует.
+    """
+    if not os.path.isdir(base_dir):
+        raise ValueError(f"Указанная директория base_dir не существует или не является директорией: {base_dir}")
+
+    # Вручную устанавливаем базовую директорию. Модуль config сам найдет
+    # нужный файл (yml или ini) при первом обращении.
+    config._BASE_DIR = base_dir
+    config._paths_initialized = True
+
+    print(f"Пакет chutils вручную инициализирован с базовой директорией: {base_dir}")
+
+
+# --- Определение публичного API (`__all__`) ---
+# Определяет, что будет импортировано при `from chutils import *`
+
+__all__ = [
+    # Основная функция ручной инициализации
+    'init',
+
+    # Функции и классы из модуля config
+    'get_config',
+    'get_config_value',
+    'get_config_int',
+    'get_config_float',
+    'get_config_boolean',
+    'get_config_list',
+    'get_config_section',
+
+    # Функции и классы из модуля logger
+    'setup_logger',
+    'ChutilsLogger',
+
+    # Классы из модуля secret_manager
+    'SecretManager',
+]

chutils-2.0.0/src/chutils/config.py

@@ -0,0 +1,277 @@
+"""
+Модуль для работы с конфигурацией.
+
+Обеспечивает автоматический поиск файла `config.yml`, `config.yaml` или `config.ini`
+в корне проекта и предоставляет удобные функции для чтения настроек.
+"""
+
+import configparser
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Any, Optional, List, Dict
+
+import yaml
+
+# Настраиваем логгер для этого модуля
+logger = logging.getLogger(__name__)
+
+# --- Глобальное состояние для "ленивой" инициализации ---
+_BASE_DIR: Optional[str] = None
+_CONFIG_FILE_PATH: Optional[str] = None
+_paths_initialized = False
+
+_config_object: Optional[Dict] = None
+_config_loaded = False
+
+
+def find_project_root(start_path: Path, markers: List[str]) -> Optional[Path]:
+    """Ищет корень проекта, двигаясь вверх по дереву каталогов."""
+    current_path = start_path.resolve()
+    # Идем вверх до тех пор, пока не достигнем корня файловой системы
+    while current_path != current_path.parent:
+        for marker in markers:
+            if (current_path / marker).exists():
+                logger.debug(f"Найден маркер '{marker}' в директории: {current_path}")
+                return current_path
+        current_path = current_path.parent
+    logger.debug("Корень проекта не найден.")
+    return None
+
+
+def _initialize_paths():
+    """Автоматически находит и кэширует пути к корню проекта и файлу конфигурации."""
+    global _BASE_DIR, _CONFIG_FILE_PATH, _paths_initialized
+    if _paths_initialized:
+        return
+
+    # Приоритет поиска: сначала YAML, потом INI, потом общий маркер проекта.
+    markers = ['config.yml', 'config.yaml', 'config.ini', 'pyproject.toml']
+    project_root = find_project_root(Path.cwd(), markers)
+
+    if project_root:
+        _BASE_DIR = str(project_root)
+        # Находим, какой именно конфигурационный файл был найден
+        for marker in markers:
+            if (project_root / marker).is_file() and marker.startswith('config'):
+                _CONFIG_FILE_PATH = str(project_root / marker)
+                break
+        logger.info(f"Корень проекта автоматически определен: {_BASE_DIR}")
+    else:
+        logger.warning("Не удалось автоматически найти корень проекта.")
+
+    _paths_initialized = True
+
+
+def _get_config_path(cfg_file: Optional[str] = None) -> str:
+    """
+    Внутренняя функция-шлюз для получения пути к файлу конфигурации.
+
+    Если путь не был установлен, запускает автоматический поиск.
+    Если путь не передан явно и автоматический поиск не дал результатов,
+    выбрасывает исключение с понятным сообщением.
+    """
+    # Если путь к файлу передан явно, используем его.
+    if cfg_file:
+        return cfg_file
+
+    # Если пути еще не инициализированы, запускаем поиск.
+    if not _paths_initialized:
+        _initialize_paths()
+
+    # Если после инициализации путь все еще не определен, это ошибка.
+    if _CONFIG_FILE_PATH is None:
+        raise FileNotFoundError(
+            "Файл конфигурации не найден. Не удалось автоматически определить корень проекта. "
+            "Убедитесь, что в корне вашего проекта есть 'config.yml' или 'config.ini' или 'pyproject.toml', "
+            "либо укажите путь к конфигу вручную через chutils.init(base_dir=...)"
+        )
+    return _CONFIG_FILE_PATH
+
+
+def get_config() -> Dict:
+    """
+    Загружает конфигурацию из файла (YAML или INI) и возвращает ее как словарь.
+    Результат кэшируется для последующих вызовов.
+
+    Returns:
+        Dict: Загруженный объект конфигурации.
+    """
+    global _config_object, _config_loaded
+    if _config_loaded and _config_object is not None:
+        return _config_object
+
+    path = _get_config_path()
+    if not os.path.exists(path):
+        logger.critical(f"Файл конфигурации НЕ НАЙДЕН: {path}")
+        _config_object = {}
+        _config_loaded = True
+        return _config_object
+
+    file_ext = Path(path).suffix.lower()
+
+    try:
+        with open(path, 'r', encoding='utf-8') as f:
+            if file_ext in ['.yml', '.yaml']:
+                _config_object = yaml.safe_load(f)
+                logger.info(f"Конфигурация успешно загружена из YAML: {path}")
+            elif file_ext == '.ini':
+                parser = configparser.ConfigParser()
+                parser.read_string(f.read())
+                # Преобразуем объект ConfigParser в словарь
+                _config_object = {s: dict(parser.items(s)) for s in parser.sections()}
+                logger.info(f"Конфигурация успешно загружена из INI: {path}")
+            else:
+                _config_object = {}
+                logger.warning(f"Неподдерживаемый формат файла конфигурации: {path}")
+
+    except (yaml.YAMLError, configparser.Error) as e:
+        logger.critical(f"Ошибка чтения файла конфигурации {path}: {e}")
+        _config_object = {}
+
+    if _config_object is None:
+        _config_object = {}
+
+    _config_loaded = True
+    return _config_object
+
+
+def save_config_value(section: str, key: str, value: str, cfg_file: Optional[str] = None) -> bool:
+    """
+    Сохраняет одно значение в конфигурационном файле.
+    ВАЖНО: Эта функция работает только для файлов `.ini` и спроектирована так,
+    чтобы сохранять комментарии и структуру исходного файла.
+    При работе с `.yml` файлами она вернет `False`.
+    """
+    path = _get_config_path(cfg_file)
+    file_ext = Path(path).suffix.lower()
+
+    # Защита: работаем только с .ini файлами
+    if file_ext != '.ini':
+        logger.warning(f"Сохранение поддерживается только для .ini файлов. Файл {path} не будет изменен.")
+        return False
+
+    if not os.path.exists(path):
+        logger.error(f"Невозможно сохранить значение: файл конфигурации {path} не найден.")
+        return False
+
+    try:
+        with open(path, 'r', encoding='utf-8') as f:
+            lines = f.readlines()
+    except IOError as e:
+        logger.error(f"Ошибка чтения файла {path} для сохранения: {e}")
+        return False
+
+    updated = False
+    in_target_section = False
+    section_found = False
+    key_found_in_section = False
+    section_pattern = re.compile(r'^\s*\[\s*(?P<section_name>[^]]+)\s*\]\s*')
+    key_pattern = re.compile(rf'^\s*({re.escape(key)})\s*=\s*(.*)', re.IGNORECASE)
+
+    new_lines = []
+    for line in lines:
+        section_match = section_pattern.match(line)
+        if section_match:
+            current_section_name = section_match.group('section_name').strip()
+            if current_section_name.lower() == section.lower():
+                in_target_section = True
+                section_found = True
+            else:
+                in_target_section = False
+            new_lines.append(line)
+            continue
+
+        if in_target_section and not key_found_in_section:
+            key_match = key_pattern.match(line)
+            if key_match:
+                original_key = key_match.group(1)
+                new_line_content = f"{original_key} = {value}\n"
+                new_lines.append(new_line_content)
+                key_found_in_section = True
+                updated = True
+                logger.info(f"Ключ '{key}' в секции '[{section}]' будет обновлен на '{value}' в файле {path}")
+                continue
+
+        new_lines.append(line)
+
+    if not section_found:
+        logger.warning(f"Секция '[{section}]' не найдена в файле {path}. Значение НЕ сохранено.")
+        return False
+    if section_found and not key_found_in_section:
+        logger.warning(f"Ключ '{key}' не найден в секции '[{section}]' файла {path}. Значение НЕ сохранено.")
+        return False
+
+    if updated:
+        try:
+            with open(path, 'w', encoding='utf-8') as f:
+                f.writelines(new_lines)
+            logger.info(f"Файл конфигурации {path} успешно обновлен.")
+            return True
+        except IOError as e:
+            logger.error(f"Ошибка записи в файл {path} при сохранении: {e}")
+            return False
+    else:
+        logger.debug(f"Обновление для ключа '{key}' в секции '[{section}]' не потребовалось.")
+        return False
+
+
+# --- Функции-обертки для удобного получения значений ---
+
+def get_config_value(section: str, key: str, fallback: Any = "", config: Optional[Dict] = None) -> Any:
+    """Получает значение из конфигурации."""
+    if config is None: config = get_config()
+    return config.get(section, {}).get(key, fallback)
+
+
+def get_config_int(section: str, key: str, fallback: int = 0, config: Optional[Dict] = None) -> int:
+    """Получает целочисленное значение."""
+    value = get_config_value(section, key, fallback, config)
+    try:
+        return int(value)
+    except (ValueError, TypeError):
+        return fallback
+
+
+def get_config_float(section: str, key: str, fallback: float = 0.0, config: Optional[Dict] = None) -> float:
+    """Получает дробное значение."""
+    value = get_config_value(section, key, fallback, config)
+    try:
+        return float(value)
+    except (ValueError, TypeError):
+        return fallback
+
+
+def get_config_boolean(section: str, key: str, fallback: bool = False, config: Optional[Dict] = None) -> bool:
+    """Получает булево значение."""
+    value = get_config_value(section, key, fallback, config)
+    if isinstance(value, bool):
+        return value
+    if str(value).lower() in ['true', '1', 't', 'y', 'yes']:
+        return True
+    if str(value).lower() in ['false', '0', 'f', 'n', 'no']:
+        return False
+    return fallback
+
+
+def get_config_list(
+        section: str,
+        key: str,
+        fallback: Optional[List[Any]] = None,
+        config: Optional[Dict] = None) -> List[Any]:
+    """Получает значение как список."""
+    value = get_config_value(section, key, fallback, config)
+    if isinstance(value, list):
+        return value
+    if fallback is None:
+        return []
+    return fallback
+
+
+def get_config_section(section_name: str, fallback: Optional[Dict] = None, config: Optional[Dict] = None) -> Dict[
+    str,
+    Any]:
+    """Получает всю секцию как словарь."""
+    if config is None: config = get_config()
+    return config.get(section_name, fallback if fallback is not None else {})

chutils-2.0.0/src/chutils/logger.py

@@ -0,0 +1,203 @@
+"""
+Модуль для настройки логирования.
+
+Предоставляет унифицированную функцию setup_logger для создания и настройки логгеров,
+которые могут выводить сообщения в консоль и в файлы с автоматической ротацией.
+Директория для логов ('logs') создается автоматически в корне проекта.
+"""
+
+import logging
+import logging.handlers
+import os
+from typing import Optional
+
+# Импортируем наш модуль config для доступа к путям и настройкам
+from . import config
+
+# --- Пользовательские уровни логирования ---
+# Для более гранулярного контроля над отладочными сообщениями.
+
+DEVDEBUG_LEVEL_NUM = 9
+DEVDEBUG_LEVEL_NAME = "DEVDEBUG"
+MEDIUMDEBUG_LEVEL_NUM = 15
+MEDIUMDEBUG_LEVEL_NAME = "MEDIUMDEBUG"
+
+logging.addLevelName(MEDIUMDEBUG_LEVEL_NUM, MEDIUMDEBUG_LEVEL_NAME)
+logging.addLevelName(DEVDEBUG_LEVEL_NUM, DEVDEBUG_LEVEL_NAME)
+
+
+class ChutilsLogger(logging.Logger):
+    """
+    Кастомный класс логгера, который расширяет стандартный `logging.Logger`.
+
+    Основная цель этого класса — добавить поддержку пользовательских уровней
+    логирования (`devdebug` и `mediumdebug`), обеспечивая при этом
+    корректную работу статических анализаторов и автодополнения в IDE.
+
+    Вам не нужно создавать экземпляр этого класса напрямую. Используйте
+    функцию `setup_logger()`, которая автоматически вернет объект этого типа.
+
+    :Example:
+        from chutils.logger import setup_logger, ChutilsLogger
+
+        # Используем наш класс для аннотации типа, чтобы IDE давала подсказки
+        logger: ChutilsLogger = setup_logger()
+
+        # Теперь IDE знает об этом методе и не будет показывать предупреждений
+        logger.mediumdebug("Это сообщение с автодополнением.")
+    """
+
+    def mediumdebug(self, message, *args, **kws):
+        """Логирует сообщение с уровнем MEDIUMDEBUG (15)."""
+        if self.isEnabledFor(MEDIUMDEBUG_LEVEL_NUM):
+            self._log(MEDIUMDEBUG_LEVEL_NUM, message, args, **kws)
+
+    def devdebug(self, message, *args, **kws):
+        """Логирует сообщение с уровнем DEVDEBUG (9)."""
+        if self.isEnabledFor(DEVDEBUG_LEVEL_NUM):
+            self._log(DEVDEBUG_LEVEL_NUM, message, args, **kws)
+
+
+logging.setLoggerClass(ChutilsLogger)
+
+# --- Глобальное состояние для "ленивой" инициализации ---
+
+# Кэш для пути к директории логов. Изначально пуст.
+_LOG_DIR: Optional[str] = None
+# Глобальный экземпляр основного логгера приложения
+_logger_instance: Optional[ChutilsLogger] = None
+# Флаг, чтобы сообщение об инициализации выводилось только один раз
+_initialization_message_shown = False
+
+
+def _get_log_dir() -> Optional[str]:
+    """
+    "Лениво" получает и кэширует путь к директории логов.
+
+    При первом вызове:
+    1. Запускает поиск корня проекта через модуль config.
+    2. Создает директорию 'logs' в корне проекта, если ее нет.
+    3. Кэширует результат.
+    При последующих вызовах немедленно возвращает кэшированный путь.
+    """
+    global _LOG_DIR
+    # Если путь уже кэширован, сразу возвращаем его.
+    if _LOG_DIR is not None:
+        return _LOG_DIR
+
+    # Запускаем инициализацию в config, если она еще не была выполнена.
+    # Это "сердце" автоматического обнаружения.
+    config._initialize_paths()
+
+    # Берем найденный config'ом базовый каталог проекта.
+    base_dir = config._BASE_DIR
+
+    # Если корень проекта не был найден, файловое логирование невозможно.
+    if not base_dir:
+        print("ПРЕДУПРЕЖДЕНИЕ: Не удалось определить корень проекта, файловое логирование будет отключено.")
+        return None
+
+    # Создаем путь к директории логов и саму директорию, если нужно.
+    log_path = os.path.join(base_dir, 'logs')
+    if not os.path.exists(log_path):
+        try:
+            os.makedirs(log_path)
+            print(f"INFO: Создана директория для логов: {log_path}")
+        except OSError as e:
+            # Если не удалось создать директорию, логирование в файл будет невозможно.
+            print(f"ОШИБКА: Не удалось создать директорию для логов {log_path}: {e}")
+            return None
+
+    # Кэшируем успешный результат и возвращаем его.
+    _LOG_DIR = log_path
+    return _LOG_DIR
+
+
+def setup_logger(name: str = 'app_logger', log_level_str: str = '') -> ChutilsLogger:
+    """
+    Настраивает и возвращает логгер с нужным именем.
+
+    - Предотвращает повторную настройку уже существующего логгера.
+    - Читает настройки из config.ini (уровень, имя файла и т.д.).
+    - Добавляет обработчики для вывода в консоль и в файл с ежедневной ротацией.
+
+    Args:
+        name (str): Имя логгера. 'app_logger' используется для основного логгера приложения.
+        log_level_str (str, optional): Явное указание уровня логирования (например, 'DEBUG').
+                                       Если не задан, берется из конфига.
+
+    Returns:
+        logging.Logger: Настроенный экземпляр логгера.
+    """
+    global _logger_instance, _initialization_message_shown
+
+    # Если логгер с таким именем уже имеет обработчики, значит он настроен.
+    # Просто возвращаем его, чтобы не дублировать вывод.
+    existing_logger = logging.getLogger(name)
+    if existing_logger.hasHandlers():
+        return existing_logger  # type: ignore
+
+    # Если запрашивается основной логгер приложения и он уже есть в кэше.
+    if name == 'app_logger' and _logger_instance:
+        return _logger_instance
+
+    # Получаем директорию для логов. Это первая точка, где запускается вся магия поиска путей.
+    log_dir = _get_log_dir()
+
+    # Загружаем конфигурацию для получения настроек логирования.
+    cfg = config.get_config()
+
+    # Определяем уровень логирования
+    if not log_level_str:
+        log_level_str = config.get_config_value('Logging', 'log_level', 'INFO', cfg)
+    log_level = getattr(logging, log_level_str.upper(), logging.INFO)
+
+    # Получаем остальные настройки из конфига
+    log_file_name = config.get_config_value('Logging', 'log_file_name', 'app.log', cfg)
+    backup_count = config.get_config_int('Logging', 'log_backup_count', 3, cfg)
+
+    # Создаем и настраиваем новый экземпляр логгера
+    logger = logging.getLogger(name)
+    logger.setLevel(log_level)
+    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+
+    # 1. Обработчик для вывода в консоль (StreamHandler)
+    console_handler = logging.StreamHandler()
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)
+
+    # 2. Обработчик для записи в файл (TimedRotatingFileHandler)
+    #    Добавляем его, только если директория логов была успешно определена.
+    if log_dir and log_file_name:
+        log_file_path = os.path.join(log_dir, log_file_name)
+        try:
+            # Ротация каждый день ('D'), храним backup_count старых файлов
+            file_handler = logging.handlers.TimedRotatingFileHandler(
+                log_file_path,
+                when="D",
+                interval=1,
+                backupCount=backup_count,
+                encoding='utf-8'
+            )
+            file_handler.setFormatter(formatter)
+            logger.addHandler(file_handler)
+
+            # Выводим информационное сообщение только один раз для всего приложения
+            if not _initialization_message_shown:
+                logger.debug(
+                    f"Логирование настроено. Уровень: {log_level_str}. "
+                    f"Файл: {log_file_path}, ротация: {backup_count} дней."
+                )
+                _initialization_message_shown = True
+        except Exception as e:
+            logger.error(f"Не удалось настроить файловый обработчик логов для {log_file_path}: {e}")
+    else:
+        if not _initialization_message_shown:
+            logger.warning("Директория для логов не настроена. Файловое логирование отключено.")
+            _initialization_message_shown = True
+
+    # Кэшируем основной логгер приложения
+    if name == 'app_logger':
+        _logger_instance = logger
+
+    return logger  # type: ignore

chutils-2.0.0/src/chutils/secret_manager.py

@@ -0,0 +1,138 @@
+import keyring
+from keyring.errors import NoKeyringError, PasswordDeleteError
+from typing import Optional
+from . import logger as logging
+
+logger = logging.setup_logger(__name__)
+
+
+class SecretManager:
+    """
+    Универсальный менеджер для безопасного хранения и получения секретов
+    с использованием системного хранилища (keyring).
+
+    Изолирует секреты разных приложений по `service_name`.
+    """
+
+    prefix: str = "Chutils_"
+
+    def __init__(self, service_name: str) -> None:
+        """
+        Инициализирует менеджер для конкретного сервиса (приложения).
+
+        :param service_name: Уникальное имя для твоего приложения.
+                             Например, 'my_super_app' или 'project_alpha_db'.
+        """
+        if not service_name or not isinstance(service_name, str):
+            raise ValueError("service_name должен быть непустой строкой.")
+        self.service_name: str = self.prefix + service_name
+        logger.devdebug(f"Менеджер секретов инициализирован для сервиса: '{self.service_name}'")
+
+    def save_secret(self, key: str, value: str) -> bool:
+        """
+        Сохраняет пару ключ-значение в системном хранилище.
+        Если ключ уже существует, его значение будет перезаписано.
+
+        :param key: Ключ для секрета (например, 'db_password' или 'api_token').
+        :param value: Секретное значение, которое нужно сохранить.
+        """
+        try:
+            keyring.set_password(self.service_name, key, value)
+            logger.devdebug(f"Секрет для ключа '{key}' успешно сохранен.")
+            return True
+        except NoKeyringError:
+            logger.error("Ошибка: системное хранилище (keyring) не найдено. Секрет не сохранен.")
+            return False
+        except Exception as e:
+            logger.error(f"Произошла непредвиденная ошибка при сохранении секрета: {e}")
+            return False
+
+    def get_secret(self, key: str) -> Optional[str]:
+        """
+        Получает секретное значение по ключу из системного хранилища.
+
+        :param key: Ключ, по которому нужно найти секрет.
+        :return: Сохраненное значение или None, если ключ не найден.
+        """
+        try:
+            value = keyring.get_password(self.service_name, key)
+            if value is None:
+                logger.devdebug(f"Секрет для ключа '{key}' не найден.")
+            else:
+                logger.devdebug(f"Секрет для ключа '{key}' получен.")
+            return value
+        except NoKeyringError:
+            logger.critical("Ошибка: системное хранилище (keyring) не найдено. Невозможно получить секрет.")
+            return None
+        except Exception as e:
+            logger.error(f"Произошла непредвиденная ошибка при получении секрета: {e}")
+            return None
+
+    def delete_secret(self, key: str) -> bool:
+        """
+        Удаляет пару ключ-значение из системного хранилища.
+
+        :param key: Ключ, который нужно удалить.
+        """
+        try:
+            # Сначала проверим, есть ли что удалять, для более понятного вывода
+            if self.get_secret(key) is None:
+                # Сообщение об отсутствии секрета уже будет выведено из get_secret
+                return True
+
+            keyring.delete_password(self.service_name, key)
+            logger.devdebug(f"Секрет для ключа '{key}' успешно удален.")
+            return True
+        except PasswordDeleteError:
+            logger.error(f"Ошибка: не удалось удалить секрет для ключа '{key}'.")
+            return False
+        except NoKeyringError:
+            logger.critical("Ошибка: системное хранилище (keyring) не найдено. Невозможно удалить секрет.")
+            return False
+        except Exception as e:
+            logger.error(f"Произошла непредвиденная ошибка при удалении секрета: {e}")
+            return False
+
+    def update_secret(self, key: str, value: str) -> bool:
+        """
+        Обновляет значение для существующего ключа.
+        Это псевдоним для функции save_secret, так как keyring перезаписывает значение.
+
+        :param key: Ключ для секрета (например, 'db_password' или 'api_token').
+        :param value: Секретное значение, которое нужно сохранить.
+        """
+        logger.devdebug(f"Обновление секрета для ключа '{key}'...")
+        return self.save_secret(key, value)
+
+
+# --- Пример использования ---
+# Этот блок выполнится, только если запустить этот файл напрямую (python secret_manager.py)
+if __name__ == '__main__':
+    # 1. Создаем экземпляр менеджера для нашего приложения "my_test_project"
+    secrets = SecretManager("my_test_project")
+
+    # 2. Определяем ключ для пароля от базы данных
+    db_password_key = "postgres_password"
+
+    # 3. Сохраняем пароль
+    secrets.save_secret(db_password_key, "MySuperSecretPassword123!")
+
+    # 4. Получаем его обратно
+    retrieved_password = secrets.get_secret(db_password_key)
+    if retrieved_password:
+        print(f"  -> Полученный пароль: {retrieved_password}")
+
+    # 5. Пробуем получить несуществующий ключ
+    secrets.get_secret("non_existent_key")
+
+    # 6. Обновляем пароль
+    secrets.update_secret(db_password_key, "NewPassword456!")
+    retrieved_password_after_update = secrets.get_secret(db_password_key)
+    if retrieved_password_after_update:
+        print(f"  -> Пароль после обновления: {retrieved_password_after_update}")
+
+    # 7. Удаляем пароль
+    secrets.delete_secret(db_password_key)
+
+    # 8. Убеждаемся, что он удален
+    secrets.get_secret(db_password_key)