Tiered Debug Logging Helper

Common errors

• ModuleNotFoundError: No module named 'debug'

  cause The Python package is named `tiered-debug` on PyPI, but its internal module name is `tiered_debug` (with an underscore) when imported.
  fix Change your import statement from `import debug` or `from debug import ...` to `from tiered_debug import TieredDebug`.

• Logging messages are not appearing, even when the debug level is set correctly.

  cause The underlying `logging` module's handlers or logger level are not configured to process `DEBUG` level messages. `TieredDebug` controls *which* debug level messages are sent, but `logging` controls *if* they are handled.
  fix Before instantiating `TieredDebug` or using its methods, ensure `logging.basicConfig(level=logging.DEBUG)` is called, or explicitly add a handler to the `TieredDebug` instance's logger using `td.add_handler(my_handler)` and set the logger's level to `logging.DEBUG`.

• Environment variable TIERED_DEBUG_LEVEL is set, but my TieredDebug instance isn't respecting it.

  cause Since version 1.1.0, the `TieredDebug` class constructor's `debug_level` argument takes precedence over the `TIERED_DEBUG_LEVEL` environment variable. If `debug_level` is explicitly passed, the environment variable is ignored for that instance.
  fix To have an instance respect the environment variable, initialize it without the `debug_level` argument: `td = TieredDebug()`. Alternatively, explicitly set the `debug_level` in the constructor: `td = TieredDebug(debug_level=int(os.getenv('TIERED_DEBUG_LEVEL', '1')))`.

Warnings

• breaking Version 1.1.0 introduced a class-based structure (`TieredDebug`) that replaced the primary reliance on global functions and the `TIERED_DEBUG_LEVEL` environment variable for controlling debug levels. Code written for 1.0.x will not work directly with 1.1.x+ without migrating to the `TieredDebug` class.
  Fix: Refactor code to instantiate `TieredDebug` and use its instance methods (`lv1`, `lv2`, `log`, `set_level`, etc.) instead of the old module-level functions. The `debug_level` argument in the constructor replaces the environment variable for instance-specific control.
• gotcha The default handling of `exc_info`, `stack_info`, `stacklevel`, and `extra` keyword arguments in `log`, `lv1` through `lv5` methods has been inconsistent across versions 1.3.0, 1.3.1, and 1.4.0. This can lead to subtle differences in how these parameters are passed to the underlying `logging` module, especially if `None` was explicitly provided or implied by omitting the argument.
  Fix: Always explicitly pass `False`, `True`, or an appropriate value for `exc_info`, `stack_info`, `stacklevel`, and `extra` if you require specific behavior, rather than relying on the method's default `None` (which defers to the `logging` module's default) or specific boolean defaults.
• gotcha While `TieredDebug` helps manage debug levels, it still relies on the standard Python `logging` module for handlers, formatters, and actual output. If no `logging.Handler` is configured for the `TieredDebug` instance's logger, messages may not appear even if the debug level is met.
  Fix: Ensure that the `logging` module is properly configured with at least one handler (e.g., `logging.basicConfig()` or `td.add_handler(logging.StreamHandler())`) and that the logger's level is set to `logging.DEBUG` or lower to capture debug messages.

Install

• pip install tiered-debug Install stable version

Imports

• TieredDebug

  from tiered_debug import TieredDebug

Quickstart

This quickstart demonstrates how to instantiate `TieredDebug`, set its debug level, and log messages using the `lvX()` methods or the generic `log()` method. It also shows how to temporarily adjust the logging level using the `log_level_context` context manager and how to pass standard `logging` keyword arguments like `exc_info`.

import logging
import os
from tiered_debug import TieredDebug

# Configure a basic logger for demonstration
logging.basicConfig(
    level=logging.DEBUG,
    format='%(levelname)s:%(name)s:%(message)s'
)

# Instantiate TieredDebug with a specific level or rely on default (1)
# The debug_level argument overrides any TIERED_DEBUG_LEVEL env var for this instance.
td = TieredDebug(debug_level=3, logger_name="my_app")

# Log at different tiers
td.lv1("This is a level 1 debug message. Always visible if debug_level >= 1.")
td.lv2("This is a level 2 debug message. Visible if debug_level >= 2.")
td.lv3("This is a level 3 debug message. Visible if debug_level >= 3.")
td.lv4("This is a level 4 debug message. Not visible with current config (debug_level=3).")

# Using the generic log method
td.log(5, "This message is also at level 5. Not visible.")

# Temporarily increase the debug level using a context manager
print("\n--- Entering higher debug context ---")
with td.log_level_context(5):
    td.lv4("This level 4 message is now visible within the context!")
    td.lv5("And this level 5 message is also visible!")
    # You can also pass keyword arguments directly to the underlying logging call
    try:
        raise ValueError("Something went wrong!")
    except ValueError:
        td.lv1("Error with exc_info", exc_info=True)
print("--- Exiting higher debug context ---")

td.lv4("This level 4 message is no longer visible after exiting the context.")