chutils 2.5.0__tar.gz → 2.6.0__tar.gz

chutils-2.5.0/README.md → chutils-2.6.0/PKG-INFO

@@ -1,3 +1,34 @@
+Metadata-Version: 2.4
+Name: chutils
+Version: 2.6.0
+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!
@@ -34,9 +65,28 @@ 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.
+- **🔄 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.
 - **🚀 Ready to Use:** Just install and use.
 
+## Command Line Interface (CLI)
+
+The library provides a `chutils` console command for convenient secret management without writing code.
+
+### Secret Management
+
+```bash
+# Save a secret to the system storage (keyring)
+chutils secrets set MY_API_KEY "super-secret-value"
+
+# Delete a secret
+chutils secrets delete MY_API_KEY
+
+# Explicitly specify service name
+chutils secrets set DB_PASSWORD "12345" --service my_custom_app
+```
+
 ## Installation
 
 ```bash
@@ -76,13 +126,60 @@ Each example focuses on a specific task.
    db_port = get_config_int("Database", "port", fallback=5432)
    ```
 
+   #### Validation via Pydantic (Optional)
+
+   For strict typing and validation, you can use Pydantic models (requires `pip install chutils[pydantic]`):
+
+   ```python
+   from pydantic import BaseModel
+   from chutils import get_config
+
+   class AppConfig(BaseModel):
+       app_name: str
+       version: str
+
+   # Returns an instance of AppConfig
+   cfg = get_config(model=AppConfig)
+   print(cfg.app_name)
+   ```
+
+   You can also validate specific sections:
+   ```python
+   from chutils import get_config_section
+   db_cfg = get_config_section("Database", model=MyDbModel)
+   ```
+
    #### Overriding Configuration with Local Files (`config.local.yml`)
 
    You can create a `config.local.yml` next to your main file. Values from the local file will **override**
    corresponding values from the main file. This is perfect for local development or storing sensitive data (ensure
    `*.local.*` is in your `.gitignore`).
 
-### 2. Logging Setup
+### 2. Hot-Reload
+
+You can make your application react to configuration file changes in real-time.
+
+```python
+from chutils import start_config_watcher, on_config_change, get_config_value
+
+
+def reload_logic():
+    print("Configuration updated!")
+    # Update app state here
+    db_url = get_config_value("Database", "url")
+
+
+# Register callback
+on_config_change(reload_logic)
+
+# Start watcher (requires watchdog package)
+start_config_watcher()
+```
+
+To use this feature, install `watchdog`:
+`pip install chutils[watch]`
+
+### 3. Logging Setup
 
 1. Configure and use the logger:
 
@@ -96,8 +193,39 @@ Each example focuses on a specific task.
    logger.devdebug("Deep debug message (level 9).")
    ```
 
+   #### Structured Logging (JSON)
+
+   If you need to output logs in JSON format for ELK, Splunk, or cloud logging (requires `pip install chutils[json]`):
+
+   ```python
+   # Via code
+   logger = setup_logger(json_format=True)
+
+   # Or via config in the [Logging] section
+   # json_format: true
+   ```
+
+   #### Contextual Logging (ContextVar)
+
+   You can bind metadata to the current execution context (thread or coroutine), and it will be automatically
+   included in all log messages.
+
+   ```python
+   from chutils import setup_logger, bind_context
+
+   logger = setup_logger()
+
+   # Bind request ID and user to the current context
+   bind_context(request_id="REQ-123", user="admin")
+
+   logger.info("Action performed")
+   # Text: ... [request_id=REQ-123 user=admin] Action performed
+   # JSON: {..., "message": "Action performed", "context": {"request_id": "REQ-123", "user": "admin"}}
+   ```
+
    #### Controlling Logging via Environment Variables
 
+    - `CH_LOG_JSON=true`: Forces JSON format.
     - `CH_LOG_NO_TIME=true`: Removes the date/time from the log format (for clean Docker logs).
     - `CH_LOG_NO_FILE=true`: Disables creating log files.
 
@@ -132,7 +260,8 @@ In environments like Docker or CI/CD where `keyring` is unavailable, you can sup
 
 - `get_config_value(section, key, fallback)` / `aget_config()`
 - `get_config_int`, `get_config_boolean`, `get_config_list`, `get_config_path`
-- `save_config_value(section, key, value)` / `asave_config_value()`
+- `save_config_value(section, key, value, notify=True)` / `asave_config_value()`
+- Use `notify=False` to update the file without triggering Hot-Reload callbacks.
 
 ### Logging (`chutils.logger`)
 
@@ -149,7 +278,22 @@ In environments like Docker or CI/CD where `keyring` is unavailable, you can sup
 ### Decorators (`chutils.decorators`)
 
 - `@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.
+
+#### Example of @retry usage:
+
+```python
+from chutils.decorators import retry
+
+
+@retry(retries=3, delay=1.0, backoff=2.0)
+def fetch_data():
+    # Will be retried up to 3 times on any Exception
+    ...
+```
 
 ## License
 
 The project is distributed under the MIT License.
+

chutils-2.5.0/PKG-INFO → chutils-2.6.0/README.md

@@ -1,25 +1,3 @@
-Metadata-Version: 2.4
-Name: chutils
-Version: 2.5.0
-Summary: Набор простых и удобных утилит для Python, который избавляет от рутины при работе с конфигурацией и логированием в новых проектах.
-License: MIT
-License-File: LICENSE
-Author: Chu4hel
-Author-email: sergeiivanov636@gmail.com
-Requires-Python: >=3.9, !=2.7.*, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, !=3.6.*, !=3.7.*, !=3.8.*
-Classifier: License :: OSI Approved :: MIT License
-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
-Requires-Dist: keyring (>=25.7.0,<26.0.0)
-Requires-Dist: python-dotenv (==1.2.1) ; python_version < "3.10"
-Requires-Dist: python-dotenv (>=1.2.2,<2.0.0) ; python_version >= "3.10"
-Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
-Description-Content-Type: text/markdown
-
 [Русская версия](docs/README_RU.md)
 
 # chutils: Stop the Routine!
@@ -56,9 +34,28 @@ 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.
+- **🔄 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.
 - **🚀 Ready to Use:** Just install and use.
 
+## Command Line Interface (CLI)
+
+The library provides a `chutils` console command for convenient secret management without writing code.
+
+### Secret Management
+
+```bash
+# Save a secret to the system storage (keyring)
+chutils secrets set MY_API_KEY "super-secret-value"
+
+# Delete a secret
+chutils secrets delete MY_API_KEY
+
+# Explicitly specify service name
+chutils secrets set DB_PASSWORD "12345" --service my_custom_app
+```
+
 ## Installation
 
 ```bash
@@ -98,13 +95,60 @@ Each example focuses on a specific task.
    db_port = get_config_int("Database", "port", fallback=5432)
    ```
 
+   #### Validation via Pydantic (Optional)
+
+   For strict typing and validation, you can use Pydantic models (requires `pip install chutils[pydantic]`):
+
+   ```python
+   from pydantic import BaseModel
+   from chutils import get_config
+
+   class AppConfig(BaseModel):
+       app_name: str
+       version: str
+
+   # Returns an instance of AppConfig
+   cfg = get_config(model=AppConfig)
+   print(cfg.app_name)
+   ```
+
+   You can also validate specific sections:
+   ```python
+   from chutils import get_config_section
+   db_cfg = get_config_section("Database", model=MyDbModel)
+   ```
+
    #### Overriding Configuration with Local Files (`config.local.yml`)
 
    You can create a `config.local.yml` next to your main file. Values from the local file will **override**
    corresponding values from the main file. This is perfect for local development or storing sensitive data (ensure
    `*.local.*` is in your `.gitignore`).
 
-### 2. Logging Setup
+### 2. Hot-Reload
+
+You can make your application react to configuration file changes in real-time.
+
+```python
+from chutils import start_config_watcher, on_config_change, get_config_value
+
+
+def reload_logic():
+    print("Configuration updated!")
+    # Update app state here
+    db_url = get_config_value("Database", "url")
+
+
+# Register callback
+on_config_change(reload_logic)
+
+# Start watcher (requires watchdog package)
+start_config_watcher()
+```
+
+To use this feature, install `watchdog`:
+`pip install chutils[watch]`
+
+### 3. Logging Setup
 
 1. Configure and use the logger:
 
@@ -118,8 +162,39 @@ Each example focuses on a specific task.
    logger.devdebug("Deep debug message (level 9).")
    ```
 
+   #### Structured Logging (JSON)
+
+   If you need to output logs in JSON format for ELK, Splunk, or cloud logging (requires `pip install chutils[json]`):
+
+   ```python
+   # Via code
+   logger = setup_logger(json_format=True)
+
+   # Or via config in the [Logging] section
+   # json_format: true
+   ```
+
+   #### Contextual Logging (ContextVar)
+
+   You can bind metadata to the current execution context (thread or coroutine), and it will be automatically
+   included in all log messages.
+
+   ```python
+   from chutils import setup_logger, bind_context
+
+   logger = setup_logger()
+
+   # Bind request ID and user to the current context
+   bind_context(request_id="REQ-123", user="admin")
+
+   logger.info("Action performed")
+   # Text: ... [request_id=REQ-123 user=admin] Action performed
+   # JSON: {..., "message": "Action performed", "context": {"request_id": "REQ-123", "user": "admin"}}
+   ```
+
    #### Controlling Logging via Environment Variables
 
+    - `CH_LOG_JSON=true`: Forces JSON format.
     - `CH_LOG_NO_TIME=true`: Removes the date/time from the log format (for clean Docker logs).
     - `CH_LOG_NO_FILE=true`: Disables creating log files.
 
@@ -154,7 +229,8 @@ In environments like Docker or CI/CD where `keyring` is unavailable, you can sup
 
 - `get_config_value(section, key, fallback)` / `aget_config()`
 - `get_config_int`, `get_config_boolean`, `get_config_list`, `get_config_path`
-- `save_config_value(section, key, value)` / `asave_config_value()`
+- `save_config_value(section, key, value, notify=True)` / `asave_config_value()`
+- Use `notify=False` to update the file without triggering Hot-Reload callbacks.
 
 ### Logging (`chutils.logger`)
 
@@ -171,8 +247,21 @@ In environments like Docker or CI/CD where `keyring` is unavailable, you can sup
 ### Decorators (`chutils.decorators`)
 
 - `@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.
+
+#### Example of @retry usage:
+
+```python
+from chutils.decorators import retry
+
+
+@retry(retries=3, delay=1.0, backoff=2.0)
+def fetch_data():
+    # Will be retried up to 3 times on any Exception
+    ...
+```
 
 ## License
 
 The project is distributed under the MIT License.
-

chutils-2.6.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "chutils"
+version = "2.6.0"
+description = "Набор простых и удобных утилит для Python, который избавляет от рутины при работе с конфигурацией и логированием в новых проектах."
+authors = [{name = "Chu4hel", email = "sergeiivanov636@gmail.com"}]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.9, !=3.9.0, !=3.9.1"
+dependencies = [
+    "keyring (>=25.7.0)",
+    "pyyaml (>=6.0.3)",
+    "python-dotenv (>=1.2.1) ; python_full_version < '3.10'",
+    "python-dotenv (>=1.2.2) ; python_full_version >= '3.10'"
+]
+
+[project.optional-dependencies]
+pydantic = ["pydantic (>=2.13.4,<3.0.0)"]
+json = ["python-json-logger (>=3.2.1)"]
+watch = ["watchdog (>=6.0.0)"]
+full = [
+    "pydantic (>=2.13.4)",
+    "python-json-logger (>=3.2.1)",
+    "watchdog (>=6.0.0)"
+]
+
+[project.scripts]
+chutils = "chutils.cli:main"
+
+[tool.poetry]
+packages = [{ include = "chutils", from = "src" }]
+exclude = [
+    "tests/",
+    "site/",
+    "examples/",
+    "docs/",
+    ".github/",
+    ".idea/",
+    "__pycache__/",
+    "*.pyc",
+    "*.log",
+    "*.egg-info/",
+    ".vscode/",
+    ".ruff_cache/",
+    "coverage.xml",
+    ".coverage",
+    "PUBLISHING.md",
+    "project.txt",
+    "changelog.txt",
+]
+
+[tool.poetry.group.dev.dependencies]
+pytest = { version = "^9.0.3", python = ">=3.10" }
+pytest-mock = "^3.15.1"
+pyfakefs = { version = "^6.2.0", python = ">=3.10" }
+mkdocs = "^1.6.1"
+mkdocs-material = "^9.7.5"
+mkdocstrings = { version = "^1.0.4", python = ">=3.10" }
+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"
+
+[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.5.0 → chutils-2.6.0}/src/chutils/__init__.py

@@ -36,10 +36,6 @@ import os
 
 from . import config
 from . import logger
-
-# --- Импорт публичных функций и классов ---
-# Явно импортируем все, что должно быть доступно пользователю напрямую из пакета chutils.
-
 from .config import (
     get_config,
     get_config_value,
@@ -50,11 +46,20 @@ from .config import (
     get_config_section,
     get_config_path,
     aget_config,
-    asave_config_value
+    save_config_value,
+    asave_config_value,
+    start_config_watcher,
+    stop_config_watcher,
+    on_config_change,
+)
+from .context import bind_context, unbind_context, clear_context
+from .decorators import log_function_details, retry, timeout
+from .logger import (
+    setup_logger,
+    ChutilsLogger,
+    SafeTimedRotatingFileHandler
 )
-from .logger import setup_logger, ChutilsLogger, SafeTimedRotatingFileHandler
 from .secret_manager import SecretManager
-from .decorators import log_function_details
 
 
 def init(base_dir: str):
@@ -74,10 +79,9 @@ def init(base_dir: str):
     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
+    # Вручную устанавливаем базовую директорию через менеджер состояний.
+    config._cm.base_dir = base_dir
+    config._cm.paths_initialized = True
 
     print(f"Пакет chutils вручную инициализирован с базовой директорией: {base_dir}")
 
@@ -99,16 +103,25 @@ __all__ = [
     'get_config_section',
     'get_config_path',
     'aget_config',
+    "save_config_value",
     'asave_config_value',
+    'start_config_watcher',
+    'stop_config_watcher',
+    'on_config_change',
 
     # Функции и классы из модуля logger
     'setup_logger',
     'ChutilsLogger',
     'SafeTimedRotatingFileHandler',
+    'bind_context',
+    'unbind_context',
+    'clear_context',
 
     # Классы из модуля secret_manager
     'SecretManager',
 
     # Декораторы
     'log_function_details',
+    'retry',
+    'timeout',
 ]

chutils-2.6.0/src/chutils/cli.py

@@ -0,0 +1,71 @@
+import argparse
+import sys
+
+from chutils import config
+from chutils.secret_manager import SecretManager
+
+
+def handle_secrets_set(args: argparse.Namespace):
+    """Обработчик команды сохранения секрета."""
+    service_name = args.service or config.get_config_value("Secrets", "service_name", "")
+    sm = SecretManager(service_name)
+
+    if sm.save_secret(args.key, args.value):
+        print(f"[OK] Секрет '{args.key}' успешно сохранен в системном хранилище.")
+    else:
+        print(f"[ERROR] Не удалось сохранить секрет '{args.key}'. Проверьте доступность keyring.")
+        sys.exit(1)
+
+
+def handle_secrets_delete(args: argparse.Namespace):
+    """Обработчик команды удаления секрета."""
+    service_name = args.service or config.get_config_value("Secrets", "service_name", "")
+    sm = SecretManager(service_name)
+
+    if sm.delete_secret(args.key):
+        print(f"[OK] Секрет '{args.key}' успешно удален.")
+    else:
+        print(f"[ERROR] Не удалось удалить секрет '{args.key}' или он не существовал.")
+        sys.exit(1)
+
+
+def main():
+    """Точка входа в CLI."""
+    parser = argparse.ArgumentParser(
+        prog="chutils",
+        description="Набор утилит chutils для командной строки."
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Команды")
+
+    # Секция секретов
+    secrets_parser = subparsers.add_parser("secrets", help="Управление секретами")
+    secrets_subparsers = secrets_parser.add_subparsers(dest="subcommand", help="Действия с секретами")
+
+    # secrets set <key> <value>
+    set_parser = secrets_subparsers.add_parser("set", help="Сохранить секрет")
+    set_parser.add_argument("key", help="Имя ключа")
+    set_parser.add_argument("value", help="Значение секрета")
+    set_parser.add_argument("-s", "--service", help="Имя сервиса (service_name) для keyring")
+
+    # secrets delete <key>
+    delete_parser = secrets_subparsers.add_parser("delete", help="Удалить секрет")
+    delete_parser.add_argument("key", help="Имя ключа")
+    delete_parser.add_argument("-s", "--service", help="Имя сервиса (service_name) для keyring")
+
+    args = parser.parse_args()
+
+    if args.command == "secrets":
+        if args.subcommand == "set":
+            handle_secrets_set(args)
+        elif args.subcommand == "delete":
+            handle_secrets_delete(args)
+        else:
+            secrets_parser.print_help()
+    else:
+        parser.print_help()
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()