{"id":10292,"library":"tiered-debug","title":"Tiered Debug Logging Helper","description":"Tiered Debug is a Python logging helper module that provides multiple, configurable levels of debug logging. It wraps standard Python `logging.debug()` calls, allowing developers to set a maximum debug tier that will be logged at runtime. The library is actively maintained, with version 1.4.0 released recently, and shows a consistent release cadence with several updates in the past year.","status":"active","version":"1.4.0","language":"en","source_language":"en","source_url":"https://github.com/untergeek/tiered-debug","tags":["logging","debug","logger","development","utility"],"install":[{"cmd":"pip install tiered-debug","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"TieredDebug","correct":"from tiered_debug import TieredDebug"}],"quickstart":{"code":"import logging\nimport os\nfrom tiered_debug import TieredDebug\n\n# Configure a basic logger for demonstration\nlogging.basicConfig(\n    level=logging.DEBUG,\n    format='%(levelname)s:%(name)s:%(message)s'\n)\n\n# Instantiate TieredDebug with a specific level or rely on default (1)\n# The debug_level argument overrides any TIERED_DEBUG_LEVEL env var for this instance.\ntd = TieredDebug(debug_level=3, logger_name=\"my_app\")\n\n# Log at different tiers\ntd.lv1(\"This is a level 1 debug message. Always visible if debug_level >= 1.\")\ntd.lv2(\"This is a level 2 debug message. Visible if debug_level >= 2.\")\ntd.lv3(\"This is a level 3 debug message. Visible if debug_level >= 3.\")\ntd.lv4(\"This is a level 4 debug message. Not visible with current config (debug_level=3).\")\n\n# Using the generic log method\ntd.log(5, \"This message is also at level 5. Not visible.\")\n\n# Temporarily increase the debug level using a context manager\nprint(\"\\n--- Entering higher debug context ---\")\nwith td.log_level_context(5):\n    td.lv4(\"This level 4 message is now visible within the context!\")\n    td.lv5(\"And this level 5 message is also visible!\")\n    # You can also pass keyword arguments directly to the underlying logging call\n    try:\n        raise ValueError(\"Something went wrong!\")\n    except ValueError:\n        td.lv1(\"Error with exc_info\", exc_info=True)\nprint(\"--- Exiting higher debug context ---\")\n\ntd.lv4(\"This level 4 message is no longer visible after exiting the context.\")\n","lang":"python","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"1.0.x to 1.1.0+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"1.3.0, 1.3.1, 1.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Change your import statement from `import debug` or `from debug import ...` to `from tiered_debug import TieredDebug`.","cause":"The Python package is named `tiered-debug` on PyPI, but its internal module name is `tiered_debug` (with an underscore) when imported.","error":"ModuleNotFoundError: No module named 'debug'"},{"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`.","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.","error":"Logging messages are not appearing, even when the debug level is set correctly."},{"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')))`.","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.","error":"Environment variable TIERED_DEBUG_LEVEL is set, but my TieredDebug instance isn't respecting it."}]}