chutils 2.6.1__tar.gz → 2.7.1__tar.gz

chutils-2.6.1/README.md → chutils-2.7.1/PKG-INFO

@@ -1,3 +1,55 @@
+Metadata-Version: 2.4
+Name: chutils
+Version: 2.7.1
+Summary: Набор простых и удобных утилит для Python, который избавляет от рутины при работе с конфигурацией и логированием в новых проектах.
+License-Expression: MIT
+License-File: LICENSE
+Author: Chu4hel
+Author-email: sergeiivanov636@gmail.com
+Requires-Python: >=3.9, !=3.9.0, !=3.9.1
+Classifier: Programming Language :: Python :: 3
+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
+Provides-Extra: date
+Provides-Extra: full
+Provides-Extra: json
+Provides-Extra: otel
+Provides-Extra: pydantic
+Provides-Extra: rich
+Provides-Extra: secrets
+Provides-Extra: testing
+Provides-Extra: watch
+Requires-Dist: keyring (>=25.7.0)
+Requires-Dist: keyring (>=25.7.0) ; extra == "full"
+Requires-Dist: keyring (>=25.7.0) ; extra == "secrets"
+Requires-Dist: opentelemetry-api (>=1.41.1) ; extra == "full"
+Requires-Dist: opentelemetry-api (>=1.41.1) ; extra == "otel"
+Requires-Dist: opentelemetry-exporter-otlp (>=1.41.1) ; extra == "full"
+Requires-Dist: opentelemetry-exporter-otlp (>=1.41.1) ; extra == "otel"
+Requires-Dist: opentelemetry-sdk (>=1.41.1) ; extra == "full"
+Requires-Dist: opentelemetry-sdk (>=1.41.1) ; extra == "otel"
+Requires-Dist: pydantic (>=2.13.4) ; extra == "full"
+Requires-Dist: pydantic (>=2.13.4,<3.0.0) ; extra == "pydantic"
+Requires-Dist: pytest (>=8.0.0) ; (python_full_version < "3.10.0") and (extra == "full")
+Requires-Dist: pytest (>=8.0.0) ; (python_full_version < "3.10.0") and (extra == "testing")
+Requires-Dist: pytest (>=9.0.3) ; (python_full_version >= "3.10.0") and (extra == "full")
+Requires-Dist: pytest (>=9.0.3) ; (python_full_version >= "3.10.0") and (extra == "testing")
+Requires-Dist: python-dateutil (>=2.9.0) ; extra == "date"
+Requires-Dist: python-dateutil (>=2.9.0) ; extra == "full"
+Requires-Dist: python-dotenv (>=1.2.1) ; python_full_version < "3.10.0"
+Requires-Dist: python-dotenv (>=1.2.2) ; python_full_version >= "3.10.0"
+Requires-Dist: python-json-logger (>=3.2.1) ; extra == "full"
+Requires-Dist: python-json-logger (>=3.2.1) ; extra == "json"
+Requires-Dist: pyyaml (>=6.0.3)
+Requires-Dist: rich (>=15.0.0) ; extra == "full"
+Requires-Dist: rich (>=15.0.0) ; extra == "rich"
+Requires-Dist: watchdog (>=6.0.0) ; extra == "full"
+Requires-Dist: watchdog (>=6.0.0) ; extra == "watch"
+Description-Content-Type: text/markdown
+
 [Русская версия](docs/README_RU.md)
 
 # chutils: Stop the Routine!
@@ -34,6 +86,12 @@ Every time you start a new project, you have to solve the same tasks:
   box. It returns a custom logger with additional debug levels (`devdebug`, `mediumdebug`).
 - **🔒 Secure Secret Storage:** The `secret_manager` module provides a simple interface for saving and retrieving secrets
   via the system `keyring`, with a fallback to `.env` files.
+- **🚀 CLI Booster:** Turn any function into a CLI tool in seconds using the `@cli_command` decorator with automatic type
+  mapping and docstring parsing.
+- **⏰ Painless Datetime:** Always-aware UTC time utilities, smart parsing, and human-readable time intervals.
+- **📡 Distributed Tracing:** Seamless OpenTelemetry integration with `@trace` decorator and automatic log correlation.
+- **🔍 Config Diagnostics:** Interactive trace of configuration sources and priorities via `config debug` command.
+- **🌐 Remote Configuration:** Load settings from HTTP/HTTPS endpoints with background polling and fallback support.
 - **🔄 Hot-Reload:** Support for automatic configuration reloading on file changes without restart (requires
   `pip install chutils[watch]`).
 - **⚡ Async Ready:** Most core functions have asynchronous versions (prefixed with `a`) for non-blocking execution.
@@ -249,8 +307,15 @@ In environments like Docker or CI/CD where `keyring` is unavailable, you can sup
 - `@log_function_details`: Logs arguments, execution time, and result (uses `DEVDEBUG` level).
 - `@timeout(seconds, fallback)`: Limits function execution time. Supports sync/async and optional fallback.
 - `@retry`: Automatically retries a function if it fails. Supports sync/async, backoff, jitter, and exception filtering.
+- `@cli_command`: Turns any function into a standalone CLI script with automatic argument parsing.
+
+### Time & Dates (`chutils.time`)
+
+- `utc_now()`: Returns a timezone-aware UTC datetime.
+- `parse_datetime(value)`: Smart parsing of strings and timestamps into UTC.
+- `humanize_timedelta(dt)`: Returns human-readable strings like "5 minutes ago" or "tomorrow".
 
-#### Example of @retry usage:
+### Example of @retry usage:
 
 ```python
 from chutils.decorators import retry
@@ -262,6 +327,67 @@ def fetch_data():
     ...
 ```
 
+## Command Line Interface (CLI)
+
+`chutils` includes a set of tools to speed up development and debugging.
+
+### 1. Initialize Project
+
+Quickly set up a new project with a default configuration and `.gitignore` rules:
+
+```bash
+# Interactive mode
+chutils init
+
+# Non-interactive mode (default values)
+chutils init -y
+```
+
+### 2. Validate Configuration
+
+Check if your configuration files match your Pydantic models:
+
+```bash
+# Automatically finds 'Settings' class in context.py or config.py
+chutils validate
+
+# Explicitly specify the model path
+chutils validate --model src.settings:AppConfig
+```
+
+### 3. Debug Search Paths
+
+See exactly where `chutils` is looking for configuration files:
+
+```bash
+# Human-readable output
+chutils show-paths
+
+# JSON output for automation
+chutils show-paths --json
+```
+
+### 4. Manage Secrets
+
+Manage your system keyring secrets directly from the terminal:
+
+```bash
+# Set a secret
+chutils secrets set API_KEY "your-secret-value" --service my_app
+
+# Delete a secret
+chutils secrets delete API_KEY --service my_app
+```
+
+### 5. Debug Configuration
+
+Trace exactly where each configuration value comes from:
+
+```bash
+chutils config debug
+```
+
 ## License
 
 The project is distributed under the MIT License.
+

chutils-2.6.1/PKG-INFO → chutils-2.7.1/README.md

@@ -1,34 +1,3 @@
-Metadata-Version: 2.4
-Name: chutils
-Version: 2.6.1
-Summary: Набор простых и удобных утилит для Python, который избавляет от рутины при работе с конфигурацией и логированием в новых проектах.
-License-Expression: MIT
-License-File: LICENSE
-Author: Chu4hel
-Author-email: sergeiivanov636@gmail.com
-Requires-Python: >=3.9, !=3.9.0, !=3.9.1
-Classifier: Programming Language :: Python :: 3
-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
-Provides-Extra: full
-Provides-Extra: json
-Provides-Extra: pydantic
-Provides-Extra: watch
-Requires-Dist: keyring (>=25.7.0)
-Requires-Dist: pydantic (>=2.13.4) ; extra == "full"
-Requires-Dist: pydantic (>=2.13.4,<3.0.0) ; extra == "pydantic"
-Requires-Dist: python-dotenv (>=1.2.1) ; python_full_version < "3.10.0"
-Requires-Dist: python-dotenv (>=1.2.2) ; python_full_version >= "3.10.0"
-Requires-Dist: python-json-logger (>=3.2.1) ; extra == "full"
-Requires-Dist: python-json-logger (>=3.2.1) ; extra == "json"
-Requires-Dist: pyyaml (>=6.0.3)
-Requires-Dist: watchdog (>=6.0.0) ; extra == "full"
-Requires-Dist: watchdog (>=6.0.0) ; extra == "watch"
-Description-Content-Type: text/markdown
-
 [Русская версия](docs/README_RU.md)
 
 # chutils: Stop the Routine!
@@ -65,6 +34,12 @@ Every time you start a new project, you have to solve the same tasks:
   box. It returns a custom logger with additional debug levels (`devdebug`, `mediumdebug`).
 - **🔒 Secure Secret Storage:** The `secret_manager` module provides a simple interface for saving and retrieving secrets
   via the system `keyring`, with a fallback to `.env` files.
+- **🚀 CLI Booster:** Turn any function into a CLI tool in seconds using the `@cli_command` decorator with automatic type
+  mapping and docstring parsing.
+- **⏰ Painless Datetime:** Always-aware UTC time utilities, smart parsing, and human-readable time intervals.
+- **📡 Distributed Tracing:** Seamless OpenTelemetry integration with `@trace` decorator and automatic log correlation.
+- **🔍 Config Diagnostics:** Interactive trace of configuration sources and priorities via `config debug` command.
+- **🌐 Remote Configuration:** Load settings from HTTP/HTTPS endpoints with background polling and fallback support.
 - **🔄 Hot-Reload:** Support for automatic configuration reloading on file changes without restart (requires
   `pip install chutils[watch]`).
 - **⚡ Async Ready:** Most core functions have asynchronous versions (prefixed with `a`) for non-blocking execution.
@@ -280,8 +255,15 @@ In environments like Docker or CI/CD where `keyring` is unavailable, you can sup
 - `@log_function_details`: Logs arguments, execution time, and result (uses `DEVDEBUG` level).
 - `@timeout(seconds, fallback)`: Limits function execution time. Supports sync/async and optional fallback.
 - `@retry`: Automatically retries a function if it fails. Supports sync/async, backoff, jitter, and exception filtering.
+- `@cli_command`: Turns any function into a standalone CLI script with automatic argument parsing.
+
+### Time & Dates (`chutils.time`)
+
+- `utc_now()`: Returns a timezone-aware UTC datetime.
+- `parse_datetime(value)`: Smart parsing of strings and timestamps into UTC.
+- `humanize_timedelta(dt)`: Returns human-readable strings like "5 minutes ago" or "tomorrow".
 
-#### Example of @retry usage:
+### Example of @retry usage:
 
 ```python
 from chutils.decorators import retry
@@ -293,7 +275,66 @@ def fetch_data():
     ...
 ```
 
+## Command Line Interface (CLI)
+
+`chutils` includes a set of tools to speed up development and debugging.
+
+### 1. Initialize Project
+
+Quickly set up a new project with a default configuration and `.gitignore` rules:
+
+```bash
+# Interactive mode
+chutils init
+
+# Non-interactive mode (default values)
+chutils init -y
+```
+
+### 2. Validate Configuration
+
+Check if your configuration files match your Pydantic models:
+
+```bash
+# Automatically finds 'Settings' class in context.py or config.py
+chutils validate
+
+# Explicitly specify the model path
+chutils validate --model src.settings:AppConfig
+```
+
+### 3. Debug Search Paths
+
+See exactly where `chutils` is looking for configuration files:
+
+```bash
+# Human-readable output
+chutils show-paths
+
+# JSON output for automation
+chutils show-paths --json
+```
+
+### 4. Manage Secrets
+
+Manage your system keyring secrets directly from the terminal:
+
+```bash
+# Set a secret
+chutils secrets set API_KEY "your-secret-value" --service my_app
+
+# Delete a secret
+chutils secrets delete API_KEY --service my_app
+```
+
+### 5. Debug Configuration
+
+Trace exactly where each configuration value comes from:
+
+```bash
+chutils config debug
+```
+
 ## License
 
 The project is distributed under the MIT License.
-

{chutils-2.6.1 → chutils-2.7.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "chutils"
-version = "2.6.1"
+version = "2.7.1"
 description = "Набор простых и удобных утилит для Python, который избавляет от рутины при работе с конфигурацией и логированием в новых проектах."
 authors = [{name = "Chu4hel", email = "sergeiivanov636@gmail.com"}]
 license = "MIT"
@@ -14,13 +14,33 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+secrets = ["keyring (>=25.7.0)"]
 pydantic = ["pydantic (>=2.13.4,<3.0.0)"]
 json = ["python-json-logger (>=3.2.1)"]
 watch = ["watchdog (>=6.0.0)"]
+rich = ["rich (>=15.0.0)"]
+date = ["python-dateutil (>=2.9.0)"]
+testing = [
+    "pytest (>=8.0.0) ; python_full_version < '3.10'",
+    "pytest (>=9.0.3) ; python_full_version >= '3.10'"
+]
+otel = [
+    "opentelemetry-api (>=1.41.1)",
+    "opentelemetry-sdk (>=1.41.1)",
+    "opentelemetry-exporter-otlp (>=1.41.1)"
+]
 full = [
     "pydantic (>=2.13.4)",
     "python-json-logger (>=3.2.1)",
-    "watchdog (>=6.0.0)"
+    "watchdog (>=6.0.0)",
+    "rich (>=15.0.0)",
+    "python-dateutil (>=2.9.0)",
+    "opentelemetry-api (>=1.41.1)",
+    "opentelemetry-sdk (>=1.41.1)",
+    "opentelemetry-exporter-otlp (>=1.41.1)",
+    "keyring (>=25.7.0)",
+    "pytest (>=8.0.0) ; python_full_version < '3.10'",
+    "pytest (>=9.0.3) ; python_full_version >= '3.10'"
 ]
 
 [project.scripts]
@@ -59,6 +79,7 @@ mkdocstrings-python = { version = "^2.0.3", python = ">=3.10" }
 pytest-cov = "^7.1.0"
 pytest-asyncio = { version = "^1.3.0", python = ">=3.10" }
 ruff = "^0.15.12"
+rich = "^15.0.0"
 
 [build-system]
 requires = ["poetry-core>=2.0.0,<3.0.0"]

chutils-2.7.1/src/chutils/__init__.py

@@ -0,0 +1,184 @@
+"""
+Пакет 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 importlib
+import os
+from typing import Any
+
+# Словарь соответствия имен атрибутов их модулям и именам внутри этих модулей.
+# Формат: 'имя_атрибута': ('относительный_путь_к_модулю', 'имя_в_модуле' или None для самого модуля)
+_LAZY_MAPPING = {
+    # modules
+    'config': ('.config', None),
+    'logger': ('.logger', None),
+    'secret_manager': ('.secret_manager', None),
+    'decorators': ('.decorators', None),
+    'cache': ('.cache', None),
+    'exceptions': ('.exceptions', None),
+    'context': ('.context', None),
+    'lifecycle': ('.lifecycle', None),
+    'time': ('.time', None),
+    'tracing': ('.tracing', None),
+    'testing': ('.testing', None),
+
+    # config
+    'get_config': ('.config', 'get_config'),
+    'get_config_value': ('.config', 'get_config_value'),
+    'get_config_int': ('.config', 'get_config_int'),
+    'get_config_float': ('.config', 'get_config_float'),
+    'get_config_boolean': ('.config', 'get_config_boolean'),
+    'get_config_list': ('.config', 'get_config_list'),
+    'get_config_section': ('.config', 'get_config_section'),
+    'get_config_path': ('.config', 'get_config_path'),
+    'aget_config': ('.config', 'aget_config'),
+    'save_config_value': ('.config', 'save_config_value'),
+    'asave_config_value': ('.config', 'asave_config_value'),
+    'start_config_watcher': ('.config', 'start_config_watcher'),
+    'stop_config_watcher': ('.config', 'stop_config_watcher'),
+    'on_config_change': ('.config', 'on_config_change'),
+    'generate_yaml_template': ('.config', 'generate_yaml_template'),
+    'generate_env_template': ('.config', 'generate_env_template'),
+    'generate_json_schema': ('.config', 'generate_json_schema'),
+
+    # features
+    'is_feature_enabled': ('.features', 'is_feature_enabled'),
+    'require_feature': ('.features', 'require_feature'),
+
+    # logger
+    'setup_logger': ('.logger', 'setup_logger'),
+    'ChutilsLogger': ('.logger', 'ChutilsLogger'),
+    'SafeTimedRotatingFileHandler': ('.logger', 'SafeTimedRotatingFileHandler'),
+
+    # context
+    'bind_context': ('.context', 'bind_context'),
+    'unbind_context': ('.context', 'unbind_context'),
+    'clear_context': ('.context', 'clear_context'),
+
+    # lifecycle
+    'register_cleanup': ('.lifecycle', 'register_cleanup'),
+    'setup_graceful_shutdown': ('.lifecycle', 'setup_graceful_shutdown'),
+
+    # cli_booster
+    'cli_command': ('.cli_booster', 'cli_command'),
+
+    # time
+    'utc_now': ('.time', 'utc_now'),
+    'parse_datetime': ('.time', 'parse_datetime'),
+    'humanize_timedelta': ('.time', 'humanize_timedelta'),
+
+    # secret_manager
+    'SecretManager': ('.secret_manager', 'SecretManager'),
+
+    # decorators
+    'log_function_details': ('.decorators', 'log_function_details'),
+    'retry': ('.decorators', 'retry'),
+    'timeout': ('.decorators', 'timeout'),
+
+    # tracing
+    'trace': ('.tracing', 'trace'),
+    'setup_tracing': ('.tracing', 'setup_tracing'),
+    'IS_OTEL_AVAILABLE': ('.tracing', 'IS_OTEL_AVAILABLE'),
+
+    # exceptions
+    'ChutilsException': ('.exceptions', 'ChutilsException'),
+    'ConfigError': ('.exceptions', 'ConfigError'),
+    'ConfigLoadError': ('.exceptions', 'ConfigLoadError'),
+    'ConfigParseError': ('.exceptions', 'ConfigParseError'),
+    'SecretError': ('.exceptions', 'SecretError'),
+    'SecretNotFoundError': ('.exceptions', 'SecretNotFoundError'),
+    'SecretProviderError': ('.exceptions', 'SecretProviderError'),
+    'LoggerConfigurationError': ('.exceptions', 'LoggerConfigurationError'),
+    'WatcherInitializationError': ('.exceptions', 'WatcherInitializationError'),
+    'OptionalDependencyError': ('.exceptions', 'OptionalDependencyError'),
+    'ChutilsTimeoutError': ('.exceptions', 'ChutilsTimeoutError'),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """
+    Реализация ленивой загрузки согласно PEP 562.
+    Вызывается при обращении к атрибутам модуля, которые не определены явно.
+    """
+    if name in _LAZY_MAPPING:
+        mod_path, attr_name = _LAZY_MAPPING[name]
+        module = importlib.import_module(mod_path, __name__)
+        if attr_name is None:
+            return module
+        return getattr(module, attr_name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    """
+    Возвращает список всех доступных атрибутов для поддержки автодополнения и интроспекции.
+    """
+    return sorted(list(_LAZY_MAPPING.keys()) + [
+        'init', '__all__', '__doc__', '__file__', '__path__',
+        '__name__', '__package__', '__spec__'
+    ])
+
+
+def init(base_dir: str):
+    """
+    Ручная инициализация пакета с указанием базовой директории проекта.
+
+    Эту функцию нужно вызывать только в том случае, если автоматическое
+    определение корня проекта не сработало. Вызывать следует один раз
+    в самом начале работы основного скрипта вашего приложения.
+
+    Args:
+        base_dir (str): Абсолютный путь к корневой директории проекта.
+
+    Raises:
+        ChutilsException: Если указанная директория не существует.
+    """
+    if not os.path.isdir(base_dir):
+        # Импортируем исключение лениво
+        from .exceptions import ChutilsException
+        raise ChutilsException(
+            f"Указанная директория base_dir не существует или не является директорией: {base_dir}",
+            base_dir=base_dir
+        )
+
+    # Вручную устанавливаем базовую директорию через менеджер состояний.
+    from .config.manager import _cm
+    _cm.base_dir = base_dir
+    _cm.paths_initialized = True
+
+    print(f"Пакет chutils вручную инициализирован с базовой директорией: {base_dir}")
+
+
+# --- Определение публичного API (`__all__`) ---
+__all__ = list(_LAZY_MAPPING.keys()) + ['init']