Logging Module
Logging functionality for the prismalog package.
This module provides a high-performance, feature-rich logging system designed specifically for multiprocessing and multithreading environments. It extends Python’s standard logging with colored output, automatic log rotation, and improved handling of critical errors.
- Key components:
ColoredFormatter: Adds color-coding to console output based on log levels.
- MultiProcessingLog: Thread-safe and process-safe log handler using a shared
lock and RotatingFileHandler for file output and rotation.
- CriticalExitHandler: Optional handler that exits the program on critical errors
if configured via LoggingConfig.
- ColoredLogger: Main logger class wrapping the standard logger, providing
easy access to configured handlers and levels.
- get_logger: Factory function to obtain properly configured logger instances,
handling initialization and configuration application.
- Features:
- Performance: Optimized for speed, especially when using %(created)f timestamp format.
(Note: Performance figures depend heavily on configuration and environment).
- Colored Console Output: Improves readability using ANSI color codes. Configurable
via LoggingConfig (‘colored_console’).
- Automatic Log File Rotation: Based on size (‘rotation_size_mb’) and backup count
(‘backup_count’). Can be disabled (‘disable_rotation’).
- Process-Safe & Thread-Safe File Logging: Uses MultiProcessingLog with a
multiprocessing.Lock to prevent corruption.
- Critical Error Handling: Option to exit the application on critical logs via
CriticalExitHandler (controlled by ‘exit_on_critical’).
- Configurable Verbosity: Set default levels (‘default_level’) and per-module levels
(‘external_loggers’) via LoggingConfig.
- Flexible Configuration: Leverages LoggingConfig for settings from defaults, files,
environment variables, and CLI arguments.
Example
>>> from prismalog import get_logger, LoggingConfig
>>> # Initialize configuration (optional, happens automatically on first get_logger)
>>> # LoggingConfig.initialize(config_file="logging.yaml", use_cli_args=True)
>>>
>>> logger = get_logger(__name__) # Use module name
>>> logger.info("Application started successfully.")
>>> logger.debug("Detailed debugging information for developers.")
>>> try:
... 1 / 0
... except ZeroDivisionError:
... logger.error("An error occurred during calculation.", exc_info=True) # Log exception info
>>> logger.critical("A critical failure occurred, application might exit if configured.")
- class prismalog.log.ColoredFormatter(fmt=None, datefmt=None, style='%', colored=True)[source]
Bases:
FormatterCustom formatter that adds ANSI color codes to log level names in console output.
- This enhances readability by color-coding log messages based on their severity:
DEBUG: Blue
INFO: Green
WARNING: Yellow
ERROR: Red
CRITICAL: Bright Red
Colors are only applied when the formatter is initialized with colored=True and when the output stream supports ANSI color codes.
- Parameters:
- COLORS = {'CRITICAL': '\x1b[91m\x1b[1m', 'DEBUG': '\x1b[94m', 'ERROR': '\x1b[91m', 'INFO': '\x1b[92m', 'WARNING': '\x1b[93m'}
- RESET = '\x1b[0m'
- class prismalog.log.MultiProcessingLog(filename, mode='a', maxBytes=0, backupCount=0)[source]
Bases:
HandlerThread-safe and process-safe logging handler based on RotatingFileHandler.
This handler ensures consistent log file access across multiple processes by using a Lock to coordinate file operations. It automatically handles log file rotation and ensures all processes write to the current active log file.
- file_lock = <Lock(owner=None)>
- active_log_file = None
- __init__(filename, mode='a', maxBytes=0, backupCount=0)[source]
Initialize the handler with the specified file and rotation settings.
- emit(record)[source]
Process a log record and write it to the log file.
- Parameters:
record (LogRecord)
- Return type:
None
- class prismalog.log.CriticalExitHandler[source]
Bases:
HandlerHandler that exits the program when a critical message is logged.
This handler only processes CRITICAL level log messages. When such a message is received, it checks the exit_on_critical configuration setting and calls sys.exit(1) if enabled.
The handler can be temporarily disabled for testing purposes.
- Class methods:
disable_exit(): Temporarily disable program exit on critical logs enable_exit(): Re-enable program exit on critical logs
- exit_disabled = False
- classmethod disable_exit(disable=True)[source]
Control exit functionality for testing.
When exits are disabled, critical logs will not cause the program to terminate, allowing tests to safely check critical error paths.
- Parameters:
disable (bool) – If True (default), disable exits. If False, enable exits.
- Return type:
None
- class prismalog.log.ColoredLogger(name, verbose=None)[source]
Bases:
objectLogger with colored output support.
- classmethod setup_file_handler(log_file_path=None)[source]
Set up the file handler using LoggingConfig.
- Parameters:
log_file_path (str | None) – Optional explicit path for the log file
- Returns:
The configured MultiProcessingLog handler or None if setup fails
- Return type:
MultiProcessingLog | None
- classmethod reset(new_file=False)[source]
Reset all active loggers and optionally create a new log file.
This method is useful when reconfigure logging is required or when testing different logging configurations. It closes all existing handlers, clears the internal registry, and optionally creates a new log file.
- Parameters:
new_file (bool) – If True, generate a new unique log file. If False, reuse the existing one.
- Returns:
The ColoredLogger class for method chaining
- Return type:
- property handlers: List[Handler]
Return the handlers from the underlying logger.
- Returns:
List of handlers attached to the logger
- property level: int
Return the effective level for the logger (for testing).
- Returns:
The configured log level as an integer
- prismalog.log.configure_external_loggers(external_loggers)[source]
Configure external library loggers with specified levels.
- prismalog.log.register_exception_hook(exit_on_critical=True)[source]
Register a custom exception hook to log unhandled exceptions.
- Parameters:
exit_on_critical (bool)
- Return type:
None
- prismalog.log.create_logger(name, log_dir=None, level=None, format_string=None)[source]
Create a new logger with console and optional file output.
- prismalog.log.handle_critical_exception(message, exit_code=1)[source]
Log a critical error and exit the application.
- prismalog.log.init_root_logger(level=None, log_dir=None, format_string=None, colored_console=True)[source]
Initialize and configure the root logger.
- prismalog.log.enable_debug_logging(logger_names=None)[source]
Enable DEBUG level logging for specified loggers.
- prismalog.log.get_caller_frame(depth=1)[source]
Get the caller’s frame at the specified depth.
- Parameters:
depth (int)
- Return type:
FrameType
- prismalog.log.get_module_name()[source]
Get the name of the calling module.
- Returns:
The name of the calling module
- Return type:
- prismalog.log.get_class_logger()[source]
Get a logger named after the calling class.
- Returns:
A logger instance named after the calling class
- Return type:
- prismalog.log.log_to_file(message, level='INFO', file_path=None)[source]
Log a message directly to a file without using the logging system.