carlogtt_python_library.logger.app_logger module

This module contains the application logger class. Guidelines for the application logger class are as follows:

10 - DEBUG: Detailed information, typically of interest only when diagnosing problems.

20 - INFO: Confirmation that things are working as expected.

30 - WARNING: An indication that something unexpected happened, or indicative of some problem in the near future (e.g. ‘disk space low’). The software is still working as expected.

40 - ERROR: Due to a more serious problem, the software has not been able to perform some function.

50 - CRITICAL: A serious error, indicating that the program itself may be unable to continue running.

class carlogtt_python_library.logger.app_logger.Logger(log_name: str, log_level: str | LoggerLevel, log_color: str = 'default', log_fmt: str | None = None)

Bases: object

Custom logger class for application-wide logging with support for file, console, and StringIO logging. Provides colored formatting and hierarchical logging capabilities.

Parameters:

• log_name – The name of the logger, used as a namespace for hierarchical logging.

• log_level – The minimum log level for the logger. Messages below this level will not be logged.

• log_color – Specifies the color of the log messages. This is used to set the initial color for all log messages handled by this logger. The default color is ‘default’, which applies no additional color formatting. Available colors include ‘red’, ‘green’, ‘yellow’, ‘blue’, ‘magenta’, ‘cyan’.

• log_fmt – The log format.

add_console_handler(logger_console_stream: TextIO | None = None) → None

Adds a console handler to log messages to the console.

Parameters:

logger_console_stream – The stream to log messages to. Typically, sys.stdout or sys.stderr. If not specified, sys.stderr is used.

add_file_handler(logger_file_path: str | Path) → None

Adds a file handler to log messages to a file.

Parameters:

logger_file_path – The path to the log file. Can be a string or a pathlib.Path object.

add_stringio_handler(logger_stringio_stream: TextIO | None = None) → None

Adds a StringIO handler to log messages to a StringIO stream.

Parameters:

logger_stringio_stream – The StringIO stream to log messages to. If not specified, io.StringIO is used.

attach_root_logger() → None

Attach the current handlers and logging level of ‘app_logger’ to the root logger.

This ensures that calls to the Python root logger (e.g. logging.info(), logging.debug()) will produce output that matches the configuration of ‘app_logger’.

change_logger_level(log_level: str | LoggerLevel) → None

Change the logger’s effective level at runtime.

This method updates both the logger instance’s level and all registered handlers’ levels to the newly specified value.

Parameters:

log_level – The desired new log level. It can be either: - A LoggerLevel enum member (e.g. LoggerLevel.DEBUG) - A string representing one of the valid log level names (e.g. "DEBUG", "INFO")

Raises:

LoggerError – If the provided string does not match any LoggerLevel member.

Returns:

None

detach_root_logger() → None

Detach custom handlers from the root logger and revert to a higher-level filter (WARNING).

This effectively disables or limits root-logger output. Any modules still calling logging.info() or logging.debug() against the root logger will no longer produce output (or be limited to WARNING+).

get_child_logger(log_name: str) → Logger

Creates and returns a child logger with a specific name.

Parameters:

log_name – The name of the child logger. This name is appended to the parent logger’s name.

Returns:

A new child logger instance.

class carlogtt_python_library.logger.app_logger.LoggerLevel(*values)

Bases: Enum

CRITICAL = 50

DEBUG = 10

ERROR = 40

INFO = 20

WARNING = 30