Logging Utilities

The logging module provides comprehensive logging functionality with automatic configuration and file rotation support.

Module Overview

Modern logging system for siege_utilities. Provides structured logging with proper configuration management.

siege_utilities.core.logging.LoggerName: alias of str

class siege_utilities.core.logging.LoggerManager[source]

Bases: object

Manages multiple loggers with consistent configuration.

__init__()[source]: Initialize the logger manager.

configure_shared_logging(log_file_path=None, level='INFO', max_bytes=5000000, backup_count=5)[source]

Configure shared logging for all loggers.

Parameters:

log_file_path (str | Path | None) – Path to shared log file. If None, configures console-only logging.
level (str | int) – Log level for shared file (or console if no file)
max_bytes (int) – Max file size before rotation
backup_count (int) – Number of backup files to keep

Return type:

None

get_logger(name=None)[source]

Get or create a logger with the specified name.

Parameters:: name (str | None) – Logger name, uses default if None
Returns:: Configured logger instance
Return type:: Logger

cleanup_logger(name)[source]

Remove and cleanup a logger.

Parameters:: name (str)
Return type:: bool

cleanup_all_loggers()[source]

Cleanup all loggers.

Return type:: None

set_default_logger_name(name)[source]

Set the default logger name.

Parameters:: name (str)
Return type:: None

class siege_utilities.core.logging.LoggingConfig[source]

Bases: object

Configuration for logging system.

log_to_file: bool = False

log_dir: Path

max_bytes: int = 5000000

backup_count: int = 5

log_to_console: bool = True

console_level: str | int = 'INFO'

file_level: str | int = 'DEBUG'

shared_log_file: Path | None = None

shared_level: str | int = 'INFO'

__init__(log_to_file=False, log_dir=<factory>, max_bytes=5000000, backup_count=5, log_to_console=True, console_level='INFO', file_level='DEBUG', shared_log_file=None, shared_level='INFO')

Parameters:

log_to_file (bool)
log_dir (Path)
max_bytes (int)
backup_count (int)
log_to_console (bool)
console_level (str | int)
file_level (str | int)
shared_log_file (Path | None)
shared_level (str | int)

Return type:

None

siege_utilities.core.logging.configure_shared_logging(log_file_path=None, level='INFO', max_bytes=5000000, backup_count=5)[source]

Configure shared logging for all loggers.

Parameters:

log_file_path (str | Path | None) – Path to shared log file. If None, configures console-only logging.
level (str | int) – Log level for logging
max_bytes (int) – Max file size before rotation (only used with file logging)
backup_count (int) – Number of backup files to keep (only used with file logging)

Return type:

None

siege_utilities.core.logging.get_logger(name=None)[source]

Get a logger instance.

Parameters:: name (str | None)
Return type:: Logger

siege_utilities.core.logging.init_logger(name, log_to_file=False, log_dir='logs', level='INFO', max_bytes=5000000, backup_count=5, shared_log_file=None)[source]

Initialize a logger with specific configuration.

Deprecated since version The: name suggests this function does first-time setup distinct from get_logger(), but both are get-or-create with shared config. Prefer configure_shared_logging() to set the shared config and get_logger() to retrieve loggers; the init_logger shape will be removed in a future release.

Parameters:

name (str) – Logger name
log_to_file (bool) – Whether to log to file
log_dir (str | Path) – Directory for log files
level (str | int) – Log level
max_bytes (int) – Max file size before rotation
backup_count (int) – Number of backup files
shared_log_file (str | Path | None) – Path to shared log file

Returns:

Configured logger instance

Return type:

Logger

siege_utilities.core.logging.cleanup_logger(name)[source]

Cleanup a specific logger.

Parameters:: name (str)
Return type:: bool

siege_utilities.core.logging.cleanup_all_loggers()[source]

Cleanup all loggers.

Return type:: None

siege_utilities.core.logging.set_default_logger_name(name)[source]

Set the default logger name.

Parameters:: name (str)
Return type:: None

siege_utilities.core.logging.log_debug(message, logger_name=None)[source]

Log a debug message.

Parameters:

message (str)
logger_name (str | None)

Return type:

None

siege_utilities.core.logging.log_info(message, logger_name=None)[source]

Log an info message.

Parameters:

message (str)
logger_name (str | None)

Return type:

None

siege_utilities.core.logging.log_warning(message, logger_name=None)[source]

Log a warning message.

Parameters:

message (str)
logger_name (str | None)

Return type:

None

siege_utilities.core.logging.log_error(message, logger_name=None)[source]

Log an error message.

Parameters:

message (str)
logger_name (str | None)

Return type:

None

siege_utilities.core.logging.log_critical(message, logger_name=None)[source]

Log a critical message.

Parameters:

message (str)
logger_name (str | None)

Return type:

None

siege_utilities.core.logging.parse_log_level(level)[source]

Convert a string or numeric level into a logging level constant.

Parameters:: level (str | int) – String (‘DEBUG’, ‘INFO’, etc.) or int (10, 20, etc.)
Returns:: Logging level constant
Return type:: int

siege_utilities.core.logging.temporary_logging_config(config)[source]

Temporarily change logging configuration.

Parameters:: config (LoggingConfig)
Return type:: Generator[None, None, None]

Functions

siege_utilities.core.logging.init_logger(name, log_to_file=False, log_dir='logs', level='INFO', max_bytes=5000000, backup_count=5, shared_log_file=None)[source]

Initialize a logger with specific configuration.

Deprecated since version The: name suggests this function does first-time setup distinct from get_logger(), but both are get-or-create with shared config. Prefer configure_shared_logging() to set the shared config and get_logger() to retrieve loggers; the init_logger shape will be removed in a future release.

Parameters:

name (str) – Logger name
log_to_file (bool) – Whether to log to file
log_dir (str | Path) – Directory for log files
level (str | int) – Log level
max_bytes (int) – Max file size before rotation
backup_count (int) – Number of backup files
shared_log_file (str | Path | None) – Path to shared log file

Returns:

Configured logger instance

Return type:

Logger

siege_utilities.core.logging.get_logger(name=None)[source]

Get a logger instance.

Parameters:: name (str | None)
Return type:: Logger

siege_utilities.core.logging.log_debug(message, logger_name=None)[source]

Log a debug message.

Parameters:

message (str)
logger_name (str | None)

Return type:

None

siege_utilities.core.logging.log_info(message, logger_name=None)[source]

Log an info message.

Parameters:

message (str)
logger_name (str | None)

Return type:

None

siege_utilities.core.logging.log_warning(message, logger_name=None)[source]

Log a warning message.

Parameters:

message (str)
logger_name (str | None)

Return type:

None

siege_utilities.core.logging.log_error(message, logger_name=None)[source]

Log an error message.

Parameters:

message (str)
logger_name (str | None)

Return type:

None

siege_utilities.core.logging.log_critical(message, logger_name=None)[source]

Log a critical message.

Parameters:

message (str)
logger_name (str | None)

Return type:

None

siege_utilities.core.logging.parse_log_level(level)[source]

Convert a string or numeric level into a logging level constant.

Parameters:: level (str | int) – String (‘DEBUG’, ‘INFO’, etc.) or int (10, 20, etc.)
Returns:: Logging level constant
Return type:: int

Usage Examples

Basic logging setup:

import siege_utilities

# Initialize logger with custom configuration
siege_utilities.init_logger(
    name='my_app',
    log_to_file=True,
    log_dir='logs',
    level='DEBUG'
)

# Use logging functions directly
siege_utilities.log_info("Application started")
siege_utilities.log_debug("Debug information")
siege_utilities.log_warning("Warning message")
siege_utilities.log_error("Error occurred")

Advanced logging with file rotation:

# Configure with file rotation
siege_utilities.init_logger(
    name='production_app',
    log_to_file=True,
    log_dir='logs',
    level='INFO',
    max_bytes=10000000,  # 10MB
    backup_count=10
)

# Get logger instance for custom handling
logger = siege_utilities.get_logger()
logger.handlers[0].setFormatter(
    logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
)

Unit Tests

The logging module has comprehensive test coverage:

✅ test_core_logging.py - All logging functionality tests pass

Test Coverage:
- Logger initialization and configuration
- All log level functions (debug, info, warning, error, critical)
- File logging and rotation
- Log level parsing
- Logger instance retrieval

Test Results: All logging tests pass successfully with 100% coverage.