1"""
 2Módulo logging.py
 3==================
 4
 5[PT-BR] Módulo de configuração central do sistema de logs. Permite:
 6
 7- Registro de mensagens em arquivo (.txt) com formatação padronizada;
 8- Definição de níveis diferentes para log em console e arquivo;
 9- Criação automática da pasta de logs, se necessário.
10
11[EN] Centralized logging configuration module. Provides:
12
13- Logging to a .txt file with standardized formatting;
14- Different logging levels for console and file outputs;
15- Automatic creation of the logs directory if it doesn't exist.
16
17Uso / Usage:
18    from services.logging import setup_logging
19    setup_logging()
20"""
21
22import logging
23import os
24from typing import Optional
25
26def setup_logging(
27    log_file: str = "logs/errors.txt",
28    console_level: int = logging.INFO,
29    file_level: int = logging.DEBUG,
30    enable_console: bool = True,
31    append: bool = False,
32    logger_name: Optional[str] = None
33) -> logging.Logger:
34    """
35    [PT-BR] Configura o sistema de logging com opções para arquivo e console.
36    [EN] Sets up the logging system with options for file and console.
37
38    Parâmetros / Parameters:
39        log_file (str): Caminho para o arquivo de log / Log file path.
40        console_level (int): Nível do log para o console / Console log level.
41        file_level (int): Nível do log para o arquivo / File log level.
42        enable_console (bool): Habilita ou não o log no console / Enable console output.
43        append (bool): Se True, adiciona ao arquivo existente / If True, appends to log file.
44        logger_name (Optional[str]): Nome do logger / Logger name (None = root logger).
45
46    Retorna / Returns:
47        logging.Logger: Instância configurada do logger / Configured logger instance.
48    """
49    os.makedirs(os.path.dirname(log_file), exist_ok=True)
50
51    logger = logging.getLogger(logger_name)
52    logger.setLevel(logging.DEBUG)
53
54    if logger.hasHandlers():
55        logger.handlers.clear()
56
57    mode = "a" if append else "w"
58    f_handler = logging.FileHandler(log_file, mode=mode, encoding="utf-8")
59    f_handler.setLevel(file_level)
60
61    fmt = logging.Formatter("%(asctime)s - %(levelname)-8s - %(name)s - %(message)s")
62    f_handler.setFormatter(fmt)
63    logger.addHandler(f_handler)
64
65    if enable_console:
66        c_handler = logging.StreamHandler()
67        c_handler.setLevel(console_level)
68        c_handler.setFormatter(fmt)
69        logger.addHandler(c_handler)
70
71    return logger