Documentation for ToMeDa

tomeda.tomeda_logging

This module provides extended logging functionality, including the TraceLogger class and the TomedaLogging class for flexible logging configuration.

TraceLogger enhances Python's standard logging.Logger class by introducing a new logging level, TRACE, which is lower than DEBUG. It includes a new trace method for logging at this level.

TomedaLogging, on the other hand, provides a convenient interface for configuring both the root logger and any custom loggers needed by individual modules. It manages the format of log messages, the default log level, and the routing of logs to various outputs, such as the console or a file. For a logger that does not require a unique configuration, simply invoking logging.getLogger(__name__) will apply the default settings as set by root logger.

In essence, this module extends Python's logging capabilities, making it easier to manage and adapt logs according to specific needs.

logger module-attribute

logger = getLogger(__name__)

TomedaLogging

TomedaLogging(
    name: str | None = None,
    console_level: int | None = TraceLogger.TRACE,
    file_level: int | None = logging.DEBUG,
    file_name: str | None = "tomeda.log",
    console_formatter: Formatter
    | str
    | None = _CONSOLE_HANDLER_FORMATTER,
    file_formatter: Formatter
    | str
    | None = _FILE_HANDLER_FORMATTER,
)

This class configures logging for the application, primarily focusing on configuring the root logger, but also supports configuring module-specific loggers.

The TomedaLogging class supports configuring different loggers with different levels, formatting styles, and handlers for console and file output. If a logger does not need to be specifically configured, it will inherit the configuration from the root logger, which can be simply retrieved using 'logging.getLogger(name)'.

The class doesn't require the logger configuration to be present in the same module where the logger is used. This allows for a centralized logger configuration.

Example

To configure the root logger and then retrieve a module-specific logger:

TomedaLogging()
logger = logging.getLogger(__name__)

To configure a logger with a custom name, specify a filename for the log file, set the log level for file logging to WARNING, and disable console logging:

TomedaLogging(
    "my_special_logger",
    file_name="my_special_logger.log",
    file_level=logging.WARNING,
    console_level=None
)
logger = logging.getLogger("my_special_logger")

Source code in tomeda/tomeda_logging.py

def __init__(
    self,
    name: str | None = None,
    console_level: int | None = TraceLogger.TRACE,
    file_level: int | None = logging.DEBUG,
    file_name: str | None = "tomeda.log",
    console_formatter: (
        Formatter | str | None
    ) = _CONSOLE_HANDLER_FORMATTER,
    file_formatter: (Formatter | str | None) = _FILE_HANDLER_FORMATTER,
) -> None:
    self._console_level: int | None = console_level
    self._file_level: int | None = file_level
    self._console_handler: StreamHandler[TextIO] | None = StreamHandler()
    self._file_handler: FileHandler | None = None

    if logging.getLoggerClass() != TraceLogger:
        logging.setLoggerClass(TraceLogger)

    self._logger: Logger = logging.getLogger(name)
    self._logger.setLevel(logging.INFO)

    self._configure_console_handler(
        level=console_level,
        formatter=console_formatter,
    )
    self._configure_file_handler(
        level=file_level,
        formatter=file_formatter,
        file_name=file_name,
    )
    logger.info(
        "Logger '%s' initialized with level '%s'.",
        self._logger.name,
        logging.getLevelName(self._logger.getEffectiveLevel()),
    )

set_console_level

set_console_level(level: int | None) -> None

Set the log level for the console handler.

If the level is set to None, the console handler will be removed.

Parameters:

Name	Type	Description	Default
level	int | None	The log level. If it's None, the console handler will be removed.	required

Source code in tomeda/tomeda_logging.py

def set_console_level(self, level: int | None) -> None:
    """
    Set the log level for the console handler.

    If the level is set to None, the console handler will be
    removed.

    Parameters
    ----------
    level : int | None
        The log level. If it's None, the console handler will be
        removed.

    """
    formatter = (
        self._console_handler.formatter if self._console_handler else None
    )
    self._configure_console_handler(level, formatter)

set_file_level

set_file_level(level: int | None) -> None

Set the log level for the file handler.

If the level is set to None, the file handler will be removed.

Parameters:

Name	Type	Description	Default
level	int | None	The log level. If it's None, the file handler will be removed.	required

Source code in tomeda/tomeda_logging.py

def set_file_level(self, level: int | None) -> None:
    """
    Set the log level for the file handler.

    If the level is set to None, the file handler will be removed.

    Parameters
    ----------
    level : int | None
        The log level. If it's None, the file handler will be
        removed.

    """
    formatter = self._file_handler.formatter if self._file_handler else None
    filename = (
        self._file_handler.baseFilename if self._file_handler else None
    )
    self._configure_file_handler(level, formatter, filename)

TraceLogger

Bases: Logger

Extended Logger class that introduces a new logging level TRACE.

The TRACE level is situated below the DEBUG level and is represented by the numeric value 5. A corresponding method trace is provided to log messages at this level.

TRACE class-attribute instance-attribute

TRACE = 5

trace

trace(msg: Any, *args: Any, **kwargs: Any) -> None

Log a message with a severity TRACE on this logger.

Parameters:

Name	Type	Description	Default
msg	Any	The message to be logged. It can be any Python structure that has a str method.	required
args	Any	Variable argument list that gets formatted with msg.	()
kwargs	Any	Arbitrary keyword arguments that are interpreted according e.g. to the exc_info, stack_info, stacklevel or extra parameters of the logging.Logger.log method.	{}

Source code in tomeda/tomeda_logging.py

def trace(
    self,
    msg: Any,
    *args: Any,
    **kwargs: Any,
) -> None:
    """
    Log a message with a severity `TRACE` on this logger.

    Parameters
    ----------
    msg : Any
        The message to be logged. It can be any Python structure
        that has a `str` method.
    args : Any
        Variable argument list that gets formatted with `msg`.
    kwargs : Any
        Arbitrary keyword arguments that are interpreted according e.g.
        to the `exc_info`, `stack_info`, `stacklevel` or `extra` parameters
        of the `logging.Logger.log` method.

    """
    if self.isEnabledFor(self.TRACE):
        self._log(
            self.TRACE,
            msg,
            args,
            **kwargs,
        )