class_desc/protocols/i_log_handler.md

Интерфейс `ILogHandler`

Интерфейс ILogHandler определяет контракт для классов, отвечающих за обработку и вывод сообщений системы журналирования. Он позволяет:

управлять форматом вывода логов через подключение различных форматтеров (ILogFormatter);
настраивать параметры логирования динамически;
направлять логи в различные конечные точки (файл, консоль, сеть, очередь и т.д.);
гибко конфигурировать систему журналирования без изменения основной логики приложения.

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

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

Методы интерфейса

`set_formatter`

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

Сигнатура:

def set_formatter (self, formatter: ILogFormatter) -> None:
    pass

Параметры:

Параметры	Тип	Описание
formatter	ILogFormatter	Экземпляр класс‑форматтера, реализующий интерфейс ILogFormatter. Определяет правила форматирования логов.

Возвращаемое значение: None

`get_formatter`

Возвращает текущий форматтер.

Сигнатура:

def get_formatter (self) -> ILogFormatter:
    pass

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

Возвращаемое значение:

ILogFormatter: Текущий экземпляр форматтера, используемый для форматирования сообщений.

`set_config`

Устанавливает настройки системы журналирования.

Сигнатура:

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

Параметры:

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

Возвращаемое значение: None

`get_config_section`

Возвращает название секции в конфигурации системы журналирования, где хранятся параметры этого обработчика.

Сигнатура:

def get_config_section (self) -> str:
    pass

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

Возвращаемое значение:

str: Название секции.

`handle`

Задаёт контракт для всех обработчиков, отвечающих за вывод логов (в файл, консоль, очередь и т.п.).

Сигнатура:

def handle (self, level: int, message: str, context: dict | None = None) -> None:
    pass

Параметры:

Параметр	Тип	Описание
level	int	Уровень сообщения (например, DEBUG, INFO, WARNING, ERROR). Используется для категоризации и фильтрации логов.
message	str	Основной текст сообщения лога. Должен быть читаемым и информативным.
context	dict[str,Any] \| None	Необязательный словарь с дополнительной контекстной информацией (например, идентификатор пользователя, время операции, параметры запроса). Если контекст не указан, значение равно None.

Возвращаемое значение: None

Метод выполняет:

Получение отформатированного сообщения через текущий форматтер (get_formatter()).
Вывод результата в целевую систему (файл, консоль и т. д.) согласно настройкам конфигурации.

`destroy`

Уничтожение объекта обработчика.

Сигнатура:

def destroy (self) -> None:
    pass

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

Возвращаемое значение: Нет.

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

Пример 1: Простая реализация (вывод в консоль)

# anb_python_components/log_handlers/console_handler.py
from typing import Any

from anb_python_components.enums.message_type import MessageType
from anb_python_components.extensions.array_extension import ArrayExtension
from anb_python_components.protocols import ILogFormatter, ILogHandler


class ConsoleHandler(ILogHandler):
    """
    Обработчик системы журналирования для вывода в консоль.
    
    Настройки должны находится в секции `console_handler`. Принимаются следующие настройки:
        - color - dict[MessageType, str] - цвет вывода по уровню.
    
    @example Пример настроек:
        {
            'color': {
                MessageType.DEBUG: '\033[36m',
                MessageType.INFO: '\033[32m',
                MessageType.SUCCESS: '\033[32m',
                MessageType.WARNING: '\033[33m',
                MessageType.STOP: '\033[31m',
                MessageType.CRITICAL: '\033[31m',
                MessageType.ERROR: '\033[31m',
                MessageType.NOLOG: '\033[36m'
                }
        }
    """
    
    def __init__ (self) -> None:
        """
        Конструктор класса.
        """
        # Обработчик сообщений (форматер)
        self.__formatter: ILogFormatter | None = None
        
        # Цвета вывода по уровню.
        self.__color: dict[MessageType, str] = {}
    
    def __get_color (self, level: int, color: dict[MessageType, Any] | None = None) -> str:
        """
        Получение цвета из конфига или цвета по умолчанию.
        :param level: Уровень сообщения.
        :param color: Словарь с цветами или None для получения их системной конфигурации.
        :return: Текстовое представление уровня сообщения.
        """
        # Задаю цвета по умолчанию
        default_colors = {
            MessageType.DEBUG: '\033[36m',
            MessageType.INFO: '\033[32m',
            MessageType.SUCCESS: '\033[32m',
            MessageType.WARNING: '\033[33m',
            MessageType.STOP: '\033[31m',
            MessageType.CRITICAL: '\033[31m',
            MessageType.ERROR: '\033[31m',
            MessageType.NOLOG: '\033[36m'
        }
        
        # Если передан словарь цветов, то беру его, если нет, то получаем из настойки
        from_color = color if color is not None else self.__color
        
        # Перевожу уровень в MessageType
        level = MessageType.from_int(level)
        
        # Если не удалось перевести level к типу MessageType
        if isinstance(level, int):
            # - то будет выведено сообщение без формата
            level = MessageType.NOLOG
        
        # Возвращаю значение
        return ArrayExtension.get_dictionary_value(
            from_color,
            (level,),
            ArrayExtension.get_dictionary_value(default_colors, (level,), '\033[36m')
        )
    
    def set_color_scheme (self, color: dict[MessageType, Any]) -> None:
        """
        Устанавливает цвета вывода по уровню.
        :param color: Цвета вывода по уровню.
        :return: None
        """
        
        # Задаю цвета в поддерживаемый массив
        
        self.__color = {
            MessageType.DEBUG: self.__get_color(MessageType.DEBUG.value, color),
            MessageType.INFO: self.__get_color(MessageType.INFO.value, color),
            MessageType.SUCCESS: self.__get_color(MessageType.SUCCESS.value, color),
            MessageType.WARNING: self.__get_color(MessageType.WARNING.value, color),
            MessageType.STOP: self.__get_color(MessageType.STOP.value, color),
            MessageType.CRITICAL: self.__get_color(MessageType.CRITICAL.value, color),
            MessageType.ERROR: self.__get_color(MessageType.ERROR.value, color),
            MessageType.NOLOG: self.__get_color(MessageType.NOLOG.value, color)
        }
    
    def get_formatter (self) -> ILogFormatter:
        """
        Возвращает текущий форматер.
        :return: Текущее значение форматера.
        """
        # Если обработчик ещё не создан
        if self.__formatter is None:
            # - вызываем исключение
            raise ValueError("Форматтер не задан")
        
        # Возвращаем обработчик
        return self.__formatter
    
    def set_formatter (self, formatter: ILogFormatter) -> None:
        """
        Устанавливает обработчик сообщений (форматтер).
        :param formatter: Обработчик сообщений.
        :return: None
        """
        self.__formatter = formatter
    
    def get_config_section (self) -> str:
        """
        Возвращает название секции в конфигурации системы журналирования, где хранятся параметры этого обработчика.
        :return: Название секции.
        """
        return 'console_handler'
    
    def set_config (self, config: dict[str, Any]) -> None:
        """
        Устанавливает настройки системы журналирования.
        :param config: Словарь настроек.
        :return: None
        """
        # Устанавливаю цвет
        self.set_color_scheme(ArrayExtension.get_dictionary_value(config, ('color',), {}))
    
    def handle (self, level: int, message: str, context: dict | None = None) -> None:
        """
        Задаёт контракт для всех обработчиков, отвечающих за вывод логов (в файл, консоль, очередь и т.п.).
        :param level: Уровень сообщения.
        :param message: Текст сообщения.
        :param context: Контекст сообщения или None.
        :return: None
        """
        # Получаю текущий цвет
        color = self.__get_color(level)
        
        # Добавляю ссылку на новую строку
        reset = "\033[0m"
        
        # Получаю строку
        formatted = self.__formatter.format_message(level, message, context)
        
        # Преобразую её для консоли
        log_line = f"{color}{formatted}{reset}\n"
        
        # Вывожу строку
        print(log_line)
    
    def destroy (self) -> None:
        """
        Уничтожение объекта обработчика.
        :return: None.
        """
        pass

Пример 2: Реализация для записи в файл

# anb_python_components/log_handlers/file_handler.py
from typing import Any

from anb_python_components.extensions.array_extension import ArrayExtension
from anb_python_components.protocols import ILogFormatter, ILogHandler


class FileHandler(ILogHandler):
    """
    Обработчик системы журналирования для вывода в файл.
    
    Настройки должны находится в секции `file_handler`. Принимаются следующие настройки:
        - file - str - имя файла журнала.
     @example Пример настроек:
            {'file': 'c:/logs/my_log.log'}
     """
    
    def __init__ (self) -> None:
        """
        Конструктор класса.
        """
        # Обработчик сообщений (форматер)
        self.__formatter: ILogFormatter | None = None
        
        # Путь к файлу журналов
        self.__log_file: str = ""
    
    def set_file (self, log_file: str) -> None:
        """
        Устанавливает путь до файла журнала.
        :param log_file: Полный путь к файлу журнала.
        :return: None
        """
        self.__log_file = log_file
    
    def set_formatter (self, formatter: ILogFormatter) -> None:
        """
        Устанавливает обработчик сообщений (форматтер).
        :param formatter: Обработчик сообщений.
        :return: None
        """
        self.__formatter = formatter
    
    def get_formatter (self) -> ILogFormatter:
        """
        Возвращает текущий форматер.
        :return: Текущее значение форматера.
        """
        return self.__formatter
    
    def get_config_section (self) -> str:
        """
        Возвращает название секции в конфигурации системы журналирования, где хранятся параметры этого обработчика.
        :return: Название секции.
        """
        return 'file_handler'
    
    def set_config (self, config: dict[str, Any]) -> None:
        """
        Устанавливает настройки системы журналирования.
        :param config: Словарь настроек.
        :return: None
        """
        # Получаем полный путь к файлу журнала из конфигурации
        log_file = ArrayExtension.get_dictionary_value(config, ('file',), 'log.txt')
        
        # Устанавливаю имя файла журнала
        self.set_file(log_file)
    
    def handle (self, level: int, message: str, context: dict | None = None) -> None:
        """
        Задаёт контракт для всех обработчиков, отвечающих за вывод логов (в файл, консоль, очередь и т.п.).
        :param level: Уровень сообщения.
        :param message: Текст сообщения.
        :param context: Контекст сообщения или None.
        :return: None
        """
        # Получаю форматированную строку
        formatted = self.__formatter.format_message(level, message, context)
        
        # Создаю запись для журнала
        log_line = f"{formatted}\n"
        
        # Отправляю в файл
        try:
            with open(self.__log_file, 'a', encoding='utf-8') as file:
                file.write(log_line + '\n')
        except IOError as e:
            print(f"Ошибка записи в лог: {e}")
    
    def destroy (self) -> None:
        """
        Уничтожение объекта обработчика.
        :return: None.
        """
        pass

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

Реализация ILogHandler полезна в следующих случаях:

Вывод логов в консоль для отладки и мониторинга в режиме реального времени.
Запись логов в файл для долгосрочного хранения и анализа.
Отправка логов в централизованную систему (например, ELK Stack, Graylog) через сетевые протоколы.
Интеграция с очередями сообщений (RabbitMQ, Kafka) для асинхронной обработки логов.
Фильтрация по уровням (DEBUG, ERROR) перед выводом.
Динамическая смена форматтера во время выполнения (например, переключение с текстового формата на JSON).
Гибкая настройка параметров логирования через конфигурационные файлы или переменные окружения.

На главную

class_desc/protocols/i_log_handler.md

Интерфейс ILogHandler

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

Методы интерфейса

set_formatter

get_formatter

set_config

get_config_section

handle

destroy

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

Пример 1: Простая реализация (вывод в консоль)

Пример 2: Реализация для записи в файл

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

Интерфейс `ILogHandler`

`set_formatter`

`get_formatter`

`set_config`

`get_config_section`

`handle`

`destroy`