examples_return_handler.py

"""Exemplo de uso do ReturnHandler para manipulação de logs e mensagens."""

import logging

import pathfix

from src.infrastructure.logger import LoggerSingleton
from src.infrastructure.return_handler import ReturnHandler

# Cores para formatação de saída
b1 = "\033[1m"
b0 = "\033[0m"

# Inicializa o LoggerSingleton
logger = LoggerSingleton.get_logger() or logging.getLogger(__name__)

# Cria uma instância do ReturnHandler com o logger
handler = ReturnHandler(logger)

# Define os níveis de log como constantes
DEBUG = ReturnHandler.DEBUG
INFO = ReturnHandler.INFO
WARNING = ReturnHandler.WARNING
ERROR = ReturnHandler.ERROR

# Métodos de conveniência
print(f"{b1}\n• Métodos de conveniência:{b0}")
handler.debug("Mensagem de depuração")
handler.info("Mensagem informativa")
handler.error("Mensagem de erro")
handler.warning("Mensagem de aviso")

# Método genérico
print(f"{b1}\n• Método genérico:{b0}")
handler.message("DEBUG message", DEBUG)
handler.message("INFO message", INFO)
handler.message("WARNING message", WARNING)
handler.message("ERROR info", ERROR)

# Lançar exceção
print(f"{b1}\n• Lançando exceção com mensagem de erro:{b0}")
try:
    handler.exception("Erro de validação", ValueError)
except ValueError as e:
    print(f"Capturada: {e}")

return_handler.py

"""Método utilitário para manipulação de retornos de funções."""

import logging
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from collections.abc import Callable


class ReturnHandler:
    """Classe para manipular retornos de funções."""

    ERROR = 40
    """Nível de log equivalente ao logging.ERROR."""

    WARNING = 30
    """Nível de log equivalente ao logging.WARNING."""

    INFO = 20
    """Nível de log equivalente ao logging.INFO."""

    DEBUG = 10
    """Nível de log equivalente ao logging.DEBUG."""

    def __init__(self, logger: logging.Logger) -> None:
        """Inicializa o manipulador de retornos recebendo um `logging.Logger`."""
        self.logger = logger
        """Inicializa a variável `Logger` para registrar as mensagens."""

    def _normalize_level(self, level: int) -> int:
        """Normaliza o nível de log para o valor padrão do logging."""
        return {4: self.ERROR, 3: self.WARNING, 2: self.INFO, 1: self.DEBUG}.get(level, level)

    def message(self, message: str, level: int = INFO, stacklevel: int = 2) -> str:
        """Registra uma mensagem com o nível de log especificado."""
        normalized_level = self._normalize_level(level)
        self._validate_log_level(normalized_level)

        if normalized_level == self.ERROR:
            self.logger.error(message, stacklevel=stacklevel)
        elif normalized_level == self.WARNING:
            self.logger.warning(message, stacklevel=stacklevel)
        elif normalized_level == self.INFO:
            self.logger.info(message, stacklevel=stacklevel)
        elif normalized_level == self.DEBUG:
            self.logger.debug(message, stacklevel=stacklevel)

        return message

    def _validate_log_level(self, level: int) -> None:
        """Valida se o nível de log é válido."""
        valid_levels = {self.ERROR, self.WARNING, self.INFO, self.DEBUG}
        if level not in valid_levels:
            error_msg = (
                f"Nível de log inválido: {level}. "
                f"Use: ERROR({self.ERROR}), WARNING({self.WARNING}), "
                f"INFO({self.INFO}), DEBUG({self.DEBUG}) "
                f"ou os valores simplificados: 4, 3, 2, 1."
            )
            self.logger.error(error_msg)
            raise ValueError(error_msg)

    def exception(self, message: str, exception: type[Exception]) -> None:
        """Registra uma exceção com uma mensagem e levanta a exceção."""
        if not self._is_valid_exception_type(exception):
            error_msg = (
                f"O parâmetro 'exception' deve ser uma classe de exceção válida."
                f"Recebido: {exception} (tipo: {type(exception)})"
            )
            self.logger.error(error_msg, stacklevel=2)
            raise TypeError(error_msg)

        self.logger.exception(message, stacklevel=2)
        raise exception(message)

    def _is_valid_exception_type(self, exception: type[Exception]) -> bool:
        """Valida se o parâmetro é uma classe de exceção válida."""
        return isinstance(exception, type) and issubclass(exception, Exception)

    def info(self, message: str) -> str:
        """Registra uma mensagem de sucesso."""
        return self.message(message, level=self.INFO, stacklevel=3)

    def error(self, message: str) -> str:
        """Registra uma mensagem de erro."""
        return self.message(message, level=self.ERROR, stacklevel=3)

    def warning(self, message: str) -> str:
        """Registra uma mensagem de aviso."""
        return self.message(message, level=self.WARNING, stacklevel=3)

    def debug(self, message: str) -> str:
        """Registra uma mensagem de debug."""
        return self.message(message, level=self.DEBUG, stacklevel=3)