Python Logging Levels Enum Usage

While Python's built-in logging module uses integer constants (logging.DEBUG, logging.INFO, etc.) for log levels, modern Python practice encourages using the enum.Enum class for defining symbolic names, especially for configurations and custom values.

Using an Enum to wrap or reference standard logging levels significantly enhances code readability, prevents hard-to-debug typos, and aids type checking when passing levels as function arguments.

1. The Need for an Enum Wrapper

The standard logging levels are simple integers (e.g., logging.DEBUG is 10, logging.ERROR is 40). When setting a level based on configuration, developers often retrieve a string (e.g., "INFO") and convert it using getattr(logging, loglevel_string.upper()).

This string-based approach is fragile:

• No Type Safety: Functions accepting a log level usually take an int or str, offering no compile-time checking.
• Typo Risk: If a user types "INF0" instead of "INFO" in a config file, getattr will raise an AttributeError at runtime.

Wrapping these levels in a custom Enum addresses these issues.

2. Implementing a Standard Log Level Enum

The most common and effective technique is to create an Enum where the members are named identically to the standard levels, and their values are mapped to the corresponding integer constants from the logging module.

import logging
from enum import Enum

class LogLevel(Enum):
    """
    A readable Enum mapping for standard logging levels.
    """
    DEBUG = logging.DEBUG     # 10
    INFO = logging.INFO       # 20
    WARNING = logging.WARNING # 30
    ERROR = logging.ERROR     # 40
    CRITICAL = logging.CRITICAL # 50
    NOTSET = logging.NOTSET   # 0

    def __str__(self):
        # Provides a clean string representation for easier configuration
        return self.name 

3. Usage: Setting Levels with the Enum

Once defined, this LogLevel Enum can be used in configuration functions, dramatically improving clarity.

A. Setting the Logger Level

Instead of passing the raw integer, you pass the Enum value:

# Function to configure the logger
def configure_logger(level: LogLevel):
    # Pass the integer value of the Enum member to the logging functions
    logging.basicConfig(level=level.value) 

# Usage: Clean, type-checked, and readable
configure_logger(LogLevel.INFO)

B. Reading from Configuration (Safe Conversion)

The Enum acts as a safe validation layer when converting user input (a string) into a logging integer.

def set_level_from_config(level_string: str):
    try:
        # 1. Look up the Enum member by name (case-insensitive)
        enum_member = LogLevel[level_string.upper()] 
        
        # 2. Set the level using the safe integer value
        logging.getLogger().setLevel(enum_member.value)
        print(f"Set logging level to: {enum_member.name}")
        
    except KeyError:
        # Handle invalid input explicitly
        raise ValueError(
            f"Invalid log level '{level_string}'. Must be one of: "
            f"{[e.name for e in LogLevel]}"
        )

# Safe usage example
set_level_from_config("warning") # Works
# set_level_from_config("INF0") # Raises ValueError safely

---

4. Advanced Usage: Defining Custom Log Levels

While generally discouraged for general-purpose libraries, an Enum is the ideal place to define custom log levels for a specific application.

To create a custom level, you must:

1. Choose an integer value that doesn't conflict with standard levels (usually multiples of 5 between 0 and 50, e.g., 5 or 25).
2. Register the new name and number with the logging module globally using logging.addLevelName().

# 1. Define the custom level number
TRACE_LEVEL_NUM = 5 

class CustomLogLevel(LogLevel): # Inherit to include standard levels
    TRACE = TRACE_LEVEL_NUM

# 2. Register the custom level globally
logging.addLevelName(CustomLogLevel.TRACE.value, CustomLogLevel.TRACE.name)

# 3. Create a convenience method on the Logger class (Optional but recommended)
def trace(self, message, *args, **kwargs):
    if self.isEnabledFor(TRACE_LEVEL_NUM):
        self._log(TRACE_LEVEL_NUM, message, args, **kwargs)

# Monkey-patch the Logger class
logging.Logger.trace = trace

# Usage
logger = logging.getLogger('custom')
logger.setLevel(CustomLogLevel.TRACE.value) # Use the Enum value
logger.trace("A very fine-grained trace message.") 

Using the CustomLogLevel Enum provides a single source of truth for all logging levels-both standard and custom-making the entire logging setup easier to manage, configure, and statically analyze.

---

Sources and Further Reading

1. Python Documentation - enum Module
2. Python Documentation - Custom Logging Levels
3. Real Python - Using Enums in Python
4. Python Logging - Lesson 02 - Log Levels