Logging Utilities

Logging utilities for Macrodata Refinement (MDR).

This module provides logging setup, configuration, and utilities.

class mdr.utils.logging.LogLevel(value)

Bases: Enum

Log levels for the MDR logger.

DEBUG = 1

INFO = 2

WARNING = 3

ERROR = 4

CRITICAL = 5

class mdr.utils.logging.LogHandler(value)

Bases: Enum

Types of log handlers.

CONSOLE = 1

FILE = 2

JSON = 3

mdr.utils.logging.setup_logger(name='mdr', level=LogLevel.INFO, handlers=[LogHandler.CONSOLE], log_dir=None, log_format=None, date_format=None)

Set up and configure the MDR logger.

Parameters:

• name (str) – Name of the logger

• level (LogLevel | str | int) – Log level (can be a LogLevel enum, string name, or integer level)

• handlers (List[LogHandler]) – List of handlers to add to the logger

• log_dir (str | None) – Directory for log files (for FILE handler)

• log_format (str | None) – Log message format string

• date_format (str | None) – Date format string for log messages

Returns:

Configured logger instance

Return type:

Logger

mdr.utils.logging.get_logger()

Get the MDR logger instance.

Returns:

Logger instance (creates a default one if not already set up)

Return type:

Logger

mdr.utils.logging.set_log_level(level)

Set the log level for the MDR logger.

Parameters:

level (LogLevel | str | int) – New log level (can be a LogLevel enum, string name, or integer level)

Return type:

None

mdr.utils.logging.log_execution_time(func)

Decorator to log the execution time of a function.

Parameters:

func (F) – Function to decorate

Returns:

Decorated function

Return type:

F

Overview

The logging module provides a consistent logging framework for the MDR package. It includes functions for setting up loggers, configuring log levels, formatting log messages, and routing logs to appropriate outputs.

Core Components

LogLevel

class mdr.utils.logging.LogLevel(value)

Log levels for the MDR logger.

An enumeration of log levels used in MDR, including DEBUG, INFO, WARNING, ERROR, and CRITICAL.

Functions

mdr.utils.logging.setup_logger(name='mdr', level=LogLevel.INFO, handlers=[LogHandler.CONSOLE], log_dir=None, log_format=None, date_format=None)

Set up and configure the MDR logger.

Parameters:

• name (str) – Name of the logger

• level (LogLevel | str | int) – Log level (can be a LogLevel enum, string name, or integer level)

• handlers (List[LogHandler]) – List of handlers to add to the logger

• log_dir (str | None) – Directory for log files (for FILE handler)

• log_format (str | None) – Log message format string

• date_format (str | None) – Date format string for log messages

Returns:

Configured logger instance

Return type:

Logger

mdr.utils.logging.get_logger()

Get the MDR logger instance.

Returns:

Logger instance (creates a default one if not already set up)

Return type:

Logger

mdr.utils.logging.set_log_level(level)

Set the log level for the MDR logger.

Parameters:

level (LogLevel | str | int) – New log level (can be a LogLevel enum, string name, or integer level)

Return type:

None

Usage Examples

Basic logging setup:

from mdr.utils.logging import setup_logger, get_logger, LogLevel

# Set up the logger
setup_logger(level=LogLevel.INFO)

# Get a logger instance
logger = get_logger()

# Log messages at different levels
logger.debug("This is a debug message")  # Won't be shown at INFO level
logger.info("This is an info message")
logger.warning("This is a warning message")
logger.error("This is an error message")

Using the LoggingMixin:

from mdr.utils.logging import LoggingMixin, setup_logger, LogLevel

# Set up the logger
setup_logger(level=LogLevel.DEBUG)

# Create a class with logging capabilities
class MyProcessor(LoggingMixin):
    def process_data(self, data):
        self.logger.info("Starting data processing")

        if len(data) == 0:
            self.logger.warning("Empty data received")
            return None

        self.logger.debug(f"Processing {len(data)} data points")

        # Process the data...
        result = data * 2

        self.logger.info("Data processing completed")
        return result

# Use the class
processor = MyProcessor()
result = processor.process_data([1, 2, 3, 4, 5])

Advanced Configuration

Configure logging with custom handlers and formatters:

import logging
from mdr.utils.logging import setup_logger, LogLevel

# Configure a file handler
file_handler = logging.FileHandler("mdr.log")
file_formatter = logging.Formatter(
    "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)
file_handler.setFormatter(file_formatter)

# Set up the logger with custom handlers
setup_logger(
    level=LogLevel.DEBUG,
    handlers=[file_handler],
    format_string="%(levelname)s: %(message)s"
)