Add log_manager documentation to doc/

doc/src.utils.log_manager.md

@@ -0,0 +1,271 @@
+# LogManager
+
+Модуль логирования с выводом в консоль и файл с поддержкой ротации.
+
+## Установка
+
+```python
+import src.utils.log_manager as log
+```
+
+## Быстрый старт
+
+```python
+import src.utils.config_manager as config
+import src.utils.log_manager as log
+
+# Загрузка конфигурации
+config.load()
+
+# Регистрация глобальных параметров логирования
+log.register_global_params()
+
+# Регистрация модулей
+log.register(module="my_module", log_console=True, log_file="my_module.log")
+
+# Инициализация
+log.setup()
+
+# Использование
+logger = log.get_logger("my_module")
+logger.print("Сообщение")                    # в консоль
+logger.print("Отладочное", level="debug")   # с уровнем
+logger.print("Ошибка", level="error")       # в stderr
+```
+
+## Константы
+
+```python
+from src.utils.log_manager import (
+    LOG_CATEGORY,
+    LOG_CONSOLE,
+    LOG_STDERR,
+    LOG_FILE,
+    LOG_PATH,
+    LOG_LEVEL,
+    LOG_FILE_LEVEL,
+    LOG_ROTATION,
+    LOG_ROTATION_SIZE,
+    LOG_ROTATION_COUNT,
+    LOG_TIMESTAMP,
+    LOG_BUFFERED,
+    MODULE_LOG_CONSOLE,
+    MODULE_LOG_STDERR,
+    MODULE_LOG_FILE,
+    MODULE_LOG_LEVEL,
+    DEFAULT_TIMESTAMP,
+    DEFAULT_LOG_LEVEL,
+    DEFAULT_FILE_LEVEL,
+    DEFAULT_LOG_PATH,
+    DEFAULT_LOG_FILE,
+    DEFAULT_ROTATION,
+    DEFAULT_ROTATION_SIZE,
+    DEFAULT_ROTATION_COUNT,
+)
+```
+
+| Константа | Значение | Описание |
+|----------|---------|----------|
+| `LOG_CATEGORY` | `"logger"` | Категория параметров логера |
+| `LOG_CONSOLE` | `"log_console"` | Включить вывод в консоль |
+| `LOG_STDERR` | `"log_stderr"` | Включить вывод в stderr |
+| `LOG_FILE` | `"log_file"` | Имя файла логов |
+| `LOG_PATH` | `"log_path"` | Путь к директории логов |
+| `LOG_LEVEL` | `"log_level"` | Уровень логирования |
+| `LOG_FILE_LEVEL` | `"log_file_level"` | Уровень для файла |
+| `LOG_ROTATION` | `"log_rotation"` | Тип ротации: `size` или `external` |
+| `LOG_ROTATION_SIZE` | `"log_rotation_size"` | Размер файла для ротации |
+| `LOG_ROTATION_COUNT` | `"log_rotation_count"` | Количество ротированных файлов |
+| `LOG_TIMESTAMP` | `"log_timestamp"` | Формат timestamp |
+| `LOG_BUFFERED` | `"log_buffered"` | Буферизация записей |
+| `DEFAULT_TIMESTAMP` | `"%Y-%m-%d %H:%M:%S"` | Формат времени по умолчанию |
+
+## Регистрация глобальных параметров
+
+```python
+log.register_global_params()
+```
+
+Регистрирует параметры в `config_manager`:
+- `logger.log_console` - включить вывод в консоль (default: `true`)
+- `logger.log_stderr` - включить stderr для ошибок (default: `true`)
+- `logger.log_file` - имя файла логов (default: `app.log`)
+- `logger.log_path` - путь к директории (default: `./log`)
+- `logger.log_level` - уровень для консоли (default: `INFO`)
+- `logger.log_file_level` - уровень для файла (default: `DEBUG`)
+- `logger.log_rotation` - тип ротации: `size` или `external` (default: `size`)
+- `logger.log_rotation_size` - размер для ротации (default: `10MB`)
+- `logger.log_rotation_count` - количество файлов (default: `5`)
+- `logger.log_timestamp` - формат timestamp (default: `%Y-%m-%d %H:%M:%S`)
+
+## Регистрация модуля
+
+```python
+log.register(
+    module="my_module",      # имя модуля
+    log_console=True,        # вывод в консоль
+    log_stderr=False,        # вывод в stderr
+    log_file="my.log",       # имя файла (None = не писать в файл)
+    log_level="INFO"         # уровень (None = наследуется)
+)
+```
+
+### Параметры модуля
+
+Если параметр не указан или `None`, используется глобальное значение.
+
+## Конфигурация в global.yaml
+
+```yaml
+# Глобальные настройки
+logger.log_console: true
+logger.log_stderr: true
+logger.log_file: "app.log"
+logger.log_path: "./log"
+logger.log_level: "INFO"
+logger.log_file_level: "DEBUG"
+logger.log_rotation: "size"
+logger.log_rotation_size: "10MB"
+logger.log_rotation_count: 5
+logger.log_timestamp: "%Y-%m-%d %H:%M:%S"
+logger.log_buffered: false
+
+# Настройки для конкретного модуля (переопределяют глобальные)
+my_module.log_console: false
+my_module.log_file: "custom.log"
+my_module.log_level: "DEBUG"
+```
+
+## API
+
+### Регистрация
+
+```python
+log.register_global_params()  # регистрация глобальных параметров
+log.register(module, log_console, log_stderr, log_file, log_level)
+```
+
+### Получение логера
+
+```python
+logger = log.get_logger("module_name")
+```
+
+### Вывод сообщений
+
+```python
+logger.print("message")                    # в консоль (stdout)
+logger.print("msg", level="debug")       # уровень для лога
+logger.print("msg", level="info")         # default
+logger.print("msg", level="warning")     # в stderr
+logger.print("msg", level="error")       # в stderr
+
+log.print("global message")               # от корневого логера
+```
+
+### Уровни логирования
+
+- `debug` - stdout + файл (DEBUG)
+- `info` - stdout + файл (INFO, default)
+- `warning` - stderr + файл (WARNING)
+- `error` - stderr + файл (ERROR)
+
+### Инициализация
+
+```python
+log.setup()  # вызывается при старте приложения
+```
+
+## Ротация логов
+
+### По размеру (`log_rotation=size`)
+
+Используется `RotatingFileHandler`. При достижении `log_rotation_size` происходит ротация.
+
+```yaml
+logger.log_rotation: "size"
+logger.log_rotation_size: "10MB"
+logger.log_rotation_count: 5
+```
+
+Файлы: `app.log`, `app.log.1`, `app.log.2`, ...
+
+### Внешняя (`log_rotation=external`)
+
+Используется базовый `FileHandler`. Ротацией управляет внешняя система (logrotate).
+
+```yaml
+logger.log_rotation: "external"
+```
+
+## Правила написания модулей
+
+### Обязательно использовать `logger.print()` вместо `print()`
+
+```python
+# НЕПРАВИЛЬНО
+print("Сообщение")
+
+# ПРАВИЛЬНО
+logger = log.get_logger("my_module")
+logger.print("Сообщение")
+```
+
+### Инициализация модуля
+
+```python
+# my_module/__init__.py
+import src.utils.log_manager as log
+
+def init():
+    log.register(module="my_module", log_console=True, log_file="my_module.log")
+
+def main():
+    log.print("Модуль запущен")
+```
+
+## Примеры
+
+### Базовое использование
+
+```python
+import src.utils.config_manager as config
+import src.utils.log_manager as log
+
+config.load()
+log.register_global_params()
+log.register(module="app", log_console=True)
+log.setup()
+
+logger = log.get_logger("app")
+logger.print("Application started")
+```
+
+### С настройками из конфига
+
+```python
+import src.utils.config_manager as config
+import src.utils.log_manager as log
+
+config.load()
+log.register_global_params()
+
+# Регистрация модулей с параметрами из конфига
+log.register(module="model")
+log.register(module="ui", log_console=True)
+
+log.setup()
+```
+
+### Разные форматы timestamp
+
+```yaml
+# Короткий
+logger.log_timestamp: "%H:%M:%S"
+
+# Полный
+logger.log_timestamp: "%Y-%m-%d %H:%M:%S"
+
+# С микросекундами
+logger.log_timestamp: "%Y-%m-%d %H:%M:%S.%f"
+```