class_desc/classes/logger.md

Класс `Logger`

Класс Logger реализует систему журналирования для приложения. Он позволяет:

централизованно управлять логированием сообщений разных уровней;
настраивать минимальный уровень логирования (фильтрация сообщений);
подключать несколько обработчиков логов (ILogHandler) для вывода в разные места (консоль, файл, сеть и т.д.);
гибко конфигурировать систему через словарь настроек;
использовать единый форматтер (ILogFormatter) для всех обработчиков;
вызывать логирование через удобные методы‑обёртки (debug(), info(), error() и т.д.).

Основная информация

Имя файла: anb_python_components/classes/logger.py
Автор: Александр Бабаев
Версия: 1.0.0
Дата начала поддержки: с версии 1.5.0

Методы класса

Конструктор (`init`)

Инициализирует экземпляр системы журналирования.

Сигнатура:

def __init__ (self, config: dict[str, Any] = None):
    ...

Параметры:

Параметр	Тип	Описание
config	dict[str,Any] \| None	Необязательный словарь с конфигурацией системы журналирования. Если не указан, используются настройки по умолчанию

Пример использования:

from anb_python_components import Logger

logger = Logger()

`add_handler`

Добавляет обработчик в массив обработчиков.

Сигнатура:

def add_handler (self, handler: ILogHandler) -> None:
    ...

Параметры:

Параметр	Тип	Описание
handler_	ILogHandler	Экземпляр обработчика логов, реализующий интерфейс ILogHandler

Поведение:

Проверяет, не был ли обработчик такого типа уже добавлен (выбрасывает ValueError, если да).
Передаёт обработчику текущую конфигурацию (__config) и форматтер (__formatter).

Пример использования:

from anb_python_components import Logger, ConsoleLogHandler

logger = Logger()
logger.add_handler(ConsoleLogHandler())

`set_formatter`

Устанавливает обработчик сообщений (форматтер).

Сигнатура:

def set_formatter (self, formatter: ILogFormatter, update_handlers: bool = True) -> None:
    ...

Параметры:

Параметр	Тип	Описание
formatter	ILogFormatter	Экземпляр форматтера, реализующий интерфейс ILogFormatter
update_handlers	bool	Флаг, указывающий, нужно ли обновить форматтер во всех уже подключённых обработчиках. По умолчанию True

Пример использования:

from anb_python_components import Logger, JsonLogFormatter

logger = Logger()
logger.set_formatter(JsonLogFormatter())

`set_config`

Устанавливает (обновляет) конфигурацию системы журналирования.

Сигнатура:

def set_config (self, config: dict[str, Any]) -> None:
    ...

Параметры:

Параметр	Тип	Описание
config	dict[str,Any]	Словарь с параметрами конфигурации (уровень логирования, форматтер, список обработчиков и т.д.)

Особенности:

автоматически устанавливает уровень логирования (__min_level);
обновляет форматтер (если указан);
очищает текущий список обработчиков и добавляет новые из конфигурации.

`set_level`

Устанавливает минимально допустимый тип журналируемого события.

Сигнатура:

def set_level (self, level: MessageType | int) -> None:
    ...

Параметры:

Параметр	Тип	Описание
level	MessageType\|int	Уровень логирования (например, DEBUG, INFO, WARNING, ERROR). Сообщения ниже этого уровня игнорируются

Пример:

logger.set_level(MessageType.INFO)  # Будут логироваться INFO, WARNING, ERROR и т. д.
...
logger.set_level(20)  # Будут логироваться WARNING, ERROR и т. д.

`log`

Добавляет сообщение в журнал.

Сигнатура:

def log (self, level: MessageType | int, message: str, context: dict[str, Any] = None) -> None:
    ...

Параметры:

Параметр	Тип	Описание
level	MessageType\|int	Уровень сообщения
message	str	Текст сообщения журнала
context	dict[str,Any]\|None	Необязательный словарь с дополнительной контекстной информацией

Логика:

проверяет, превышает ли уровень сообщения минимальный (__is_level_enabled);
если да, передаёт сообщение всем подключённым обработчикам (handle).

Вспомагательные методы для более простых случаев

Удобные методы для логирования сообщений определённого уровня:

debug(message: str, context: dict[str, Any] = None) → log(MessageType.DEBUG, ...)
info(message: str, context: dict[str, Any] = None) → log(MessageType.INFO, ...)
success(message: str, context: dict[str, Any] = None) → log(MessageType.SUCCESS, ...)
warning(message: str, context: dict[str, Any] = None) → log(MessageType.WARNING, ...)
stop(message: str, context: dict[str, Any] = None) → log(MessageType.STOP, ...)
critical(message: str, context: dict[str, Any] = None) → log(MessageType.CRITICAL, ...)
error(message: str, context: dict[str, Any] = None) → log(MessageType.ERROR, ...)

Пример использования:

logger.info("Приложение запущено")
logger.error("Ошибка подключения к БД", {"db_host": "localhost"})

`close`

Закрывает всех обработчики и завершения работы системы журналирования. Необходим при работе с буферами.

Сигнатура:

def close (self) -> None:
    ...

Параметры: нет.

Пример:

logger = Loger(...)
...
logger.close();  # Далее, нам нельзя ничего записывать в журнал!

ВАЖНО! Ни в коем случае не вызывать в деструкторе класса! Иначе возможны ошибки. Например,

Exception ignored while calling deallocator <function BufferedRotatingFileHandler.__del__ at ***:
Traceback (most recent call last):
File "...\log_handlers\buffered_rotating_file_handler.py", line 57, in __del__
File "...\log_handlers\buffered_rotating_file_handler.py", line 107, in __flush
NameError: name 'open' is not defined

Примеры использования

Пример 1: Базовая настройка и логирование

from anb_python_components import Logger, ConsoleLogHandler, RussianLogFormatter, MessageType

# Создаём логгер
logger = Logger()

# Устанавливаем форматтер
logger.set_formatter(RussianLogFormatter())

# Добавляем обработчик вывода в консоль
logger.add_handler(ConsoleLogHandler())

# Устанавливаем уровень логирования
logger.set_level(MessageType.DEBUG)

# Логируем сообщения
logger.debug("Отладочная информация")
logger.info("Информационное сообщение")
logger.error("Произошла ошибка", {"user_id": 123})

Пример 2: Настройка через конфигурацию

from anb_python_components import FileHandler, Logger, MessageType, RussianLogFormatter

config = {
    'base': {
        'level': MessageType.WARNING,
        'formatter': RussianLogFormatter(),
        'handlers': [FileHandler()],
    },
    'file_handler': {
        'file': "test.log"
    }
}

logger = Logger(config)

logger.warning("Предупреждение: низкий уровень заряда батареи")

Сценарии применения

Класс Logger полезен в следующих случаях:

Централизованное логирование в приложениях с модульной архитектурой.
Гибкая настройка вывода логов — можно одновременно выводить сообщения в консоль (для отладки), в файл (для архивации) и в централизованную систему мониторинга (например, ELK Stack).
Фильтрация по уровням логирования — настройка минимального уровня (DEBUG, INFO, WARNING и т. д.) позволяет контролировать объём выводимой информации без изменения кода.
Динамическая смена формата логов — переключение между текстовым, JSON и другими форматами на лету через set_formatter().
Интеграция с внешними системами — подключение кастомных обработчиков (ILogHandler) для отправки логов в Slack, Telegram, системы мониторинга (Prometheus, Grafana) или базы данных.
Контекстное логирование — передача дополнительной информации (context) вместе с сообщением для упрощения отладки и анализа ошибок.
Автоматизация настройки — использование конфигурации (set_config()) для управления логированием через конфигурационные файлы или переменные окружения.
Тестирование — возможность подменять обработчики и форматтеры на заглушки (mocks) в юнит‑тестах для проверки логики логирования.
Масштабирование — добавление новых обработчиков без изменения основной логики приложения (например, подключение обработчика для отправки критических ошибок в мессенджер).

Важные особенности

Защита от дублирования обработчиков — метод add_handler() проверяет, не был ли обработчик такого типа уже добавлен, и выбрасывает ValueError при попытке дублирования.
Автоматическая синхронизация — при смене форматтера (set_formatter()) он автоматически применяется ко всем подключённым обработчикам (если update_handlers=True).
Безопасная обработка конфигурации — метод set_config() содержит защиту от некорректных значений (например, автоматически устанавливает MessageType.WARNING, если переданный уровень не соответствует MessageType).
Игнорирование низкоприоритетных сообщений — сообщения с уровнем ниже __min_level не передаются обработчикам, что снижает нагрузку на систему.
Поддержка контекста — все методы логирования позволяют передавать словарь context с дополнительной информацией (ID пользователя, параметры запроса, метаданные и т. д.).

class_desc/classes/logger.md

Класс Logger

Основная информация

Методы класса

Конструктор (__init__)

add_handler

set_formatter

set_config

set_level

log

Вспомагательные методы для более простых случаев

close

Примеры использования

Пример 1: Базовая настройка и логирование

Пример 2: Настройка через конфигурацию

Сценарии применения

Важные особенности

Рекомендации по использованию

Класс `Logger`

Конструктор (`init`)

`add_handler`

`set_formatter`

`set_config`

`set_level`

`log`

`close`