API Reference

This section provides detailed documentation for the tiered-debug module’s classes, functions, and types, generated from their docstrings.

Modules

Base implementation for tiered debug logging.

The TieredDebug class provides multi-level debug logging with configurable stack tracing for accurate caller reporting. It supports logging at levels 1-5, with level 1 always logged and levels 2-5 conditional on the configured debug level. Designed for projects like ElasticKeeper and ElasticCheckpoint, it allows flexible logger configuration and stack level adjustments.

Examples

>>> from tiered_debug._base import TieredDebug
>>> debug = TieredDebug(level=2)
>>> debug.level
2
>>> import logging
>>> handler = logging.StreamHandler()
>>> debug.add_handler(
...     handler, logging.Formatter("%(message)s")
... )
>>> debug.lv1("Always logged")
>>> debug.lv3("Not logged")  # Ignored (level 3 > 2)

tiered_debug._base.DebugLevel

Type hint for debug level (1-5).

alias of Literal[1, 2, 3, 4, 5]

tiered_debug._base.DEFAULTS = {'debug': 1, 'stack': 3}: Default values for debug level (1) and stack level (3).

class tiered_debug._base.TieredDebug(level: int = 1, stacklevel: int = 3, logger_name: str = 'tiered_debug._base')[source]

Bases: object

Tiered debug logging with configurable levels and stack tracing.

Supports debug logging at levels 1-5, with level 1 always logged and levels 2-5 conditional on the configured debug level. Allows custom stack levels for accurate caller reporting and flexible logger configuration via handlers.

Parameters:

level – Debug level (1-5, default 1). (int)
stacklevel – Stack level for caller reporting (1-9, default 3). (int)
logger_name – Name for the logger (default “tiered_debug._base”). (str)

level: Current debug level (1-5). (int)

stacklevel: Current stack level for caller reporting (1-9). (int)

logger

Configured logger instance. (logging.Logger)

Type:: logging.Logger

Examples

>>> debug = TieredDebug(level=2)
>>> debug.level
2
>>> import logging
>>> handler = logging.StreamHandler()
>>> debug.add_handler(
...     handler, logging.Formatter("%(message)s")
... )
>>> debug.lv1("Level 1 message")
>>> debug.lv3("Level 3 message")  # Not logged

Initialize a TieredDebug instance with specified settings.

Log a message at debug level 1.

Parameters:

msg – Message to log, optionally with format specifiers. (str)
*args – Arguments for message formatting.
exc_info – Include exception info if True. (bool)
stack_info – Include stack trace if True. (bool)
stacklevel – Stack level for caller reporting (1-9). (int)
extra – Extra metadata dictionary. (Dict[str, Any])

Log a message at debug level 2.

Parameters:

msg – Message to log, optionally with format specifiers. (str)
*args – Arguments for message formatting.
exc_info – Include exception info if True. (bool)
stack_info – Include stack trace if True. (bool)
stacklevel – Stack level for caller reporting (1-9). (int)
extra – Extra metadata dictionary. (Dict[str, Any])

Log a message at debug level 3.

Parameters:

msg – Message to log, optionally with format specifiers. (str)
*args – Arguments for message formatting.
exc_info – Include exception info if True. (bool)
stack_info – Include stack trace if True. (bool)
stacklevel – Stack level for caller reporting (1-9). (int)
extra – Extra metadata dictionary. (Dict[str, Any])

Log a message at debug level 4.

Parameters:

msg – Message to log, optionally with format specifiers. (str)
*args – Arguments for message formatting.
exc_info – Include exception info if True. (bool)
stack_info – Include stack trace if True. (bool)
stacklevel – Stack level for caller reporting (1-9). (int)
extra – Extra metadata dictionary. (Dict[str, Any])

Log a message at debug level 5.

Parameters:

msg – Message to log, optionally with format specifiers. (str)
*args – Arguments for message formatting.
exc_info – Include exception info if True. (bool)
stack_info – Include stack trace if True. (bool)
stacklevel – Stack level for caller reporting (1-9). (int)
extra – Extra metadata dictionary. (Dict[str, Any])

logger: Logger

property level: int

Get the current debug level (1-5).

Returns:: Current debug level.
Return type:: int

Examples

>>> debug = TieredDebug(level=3)
>>> debug.level
3

property stacklevel: int

Get the current stack level for caller reporting (1-9).

Returns:: Current stack level.
Return type:: int

Examples

>>> debug = TieredDebug(stacklevel=4)
>>> debug.stacklevel
4

check_val(val: int, kind: str) → int[source]

Validate and return a debug or stack level, or default if invalid.

Parameters:

val – Value to validate. (int)
kind – Type of value (“debug” or “stack”). (str)

Returns:

Validated value or default if invalid.

Return type:

int

Raises:

ValueError – If kind is neither “debug” nor “stack”.

Examples

>>> debug = TieredDebug()
>>> debug.check_val(3, "debug")
3
>>> debug.check_val(0, "debug")  # Invalid, returns default
1

add_handler(handler: Handler, formatter: Formatter | None = None) → None[source]

Add a handler to the logger if not already present.

Parameters:

handler – Handler to add to the logger. (logging.Handler)
formatter – Optional formatter for the handler. (logging.Formatter)

Examples

>>> debug = TieredDebug()
>>> import logging
>>> handler = logging.StreamHandler()
>>> debug.add_handler(handler)
>>> handler in debug.logger.handlers
True

change_level(level: int) → Generator[None, None, None][source]

Temporarily change the debug level within a context.

Parameters:: level – Debug level to set temporarily (1-5). (int)

Examples

>>> debug = TieredDebug(level=2)
>>> with debug.change_level(4):
...     assert debug.level == 4
>>> debug.level
2

Log a message at the specified debug level.

Parameters:

level – Debug level for the message (1-5). (DebugLevel)
msg – Message to log, optionally with format specifiers. (str)
*args – Arguments for message formatting.
exc_info – Include exception info if True. (bool)
stack_info – Include stack trace if True. (bool)
stacklevel – Stack level for caller reporting (1-9). (int)
extra – Extra metadata dictionary. (Dict[str, Any])

Raises:

ValueError – If level is not between 1 and 5.
TypeError – If extra is not a dictionary or None.

Examples

>>> debug = TieredDebug(level=2)
>>> import logging
>>> debug.add_handler(logging.StreamHandler())
>>> debug.log(1, "Level 1 message: %s", "test")
>>> debug.log(3, "Level 3 message")  # Not logged

Module for tiered debugging with a global TieredDebug instance.

Provides a global TieredDebug instance and a begin_end decorator to log function entry and exit at specified debug levels. Designed for use in projects like ElasticKeeper and ElasticCheckpoint to trace function execution with configurable stack levels.

Examples

>>> from tiered_debug.debug import debug, begin_end
>>> debug.level = 3
>>> import logging
>>> debug.add_handler(logging.StreamHandler())
>>> @begin_end(debug, begin=2, end=3, stacklevel=2, extra={"func": "test"})
... def example():
...     return "Test"
>>> example()
'Test'

tiered_debug.debug.DEFAULT_BEGIN = 2: Default debug level for BEGIN messages.

tiered_debug.debug.DEFAULT_END = 3: Default debug level for END messages.

tiered_debug.debug.debug = <tiered_debug._base.TieredDebug object>: Global TieredDebug instance with default level 1 and stacklevel 3.

tiered_debug.debug.begin_end(debug_obj: TieredDebug | None = None, begin: Literal[1, 2, 3, 4, 5] = 2, end: Literal[1, 2, 3, 4, 5] = 3, stacklevel: int = 2, extra: dict[str, Any] | None = None) → Callable[[Callable[[P], R]], Callable[[P], R]][source]

Decorator to log function entry and exit at specified debug levels.

Logs “BEGIN CALL” at the begin level and “END CALL” at the end level using the provided or global debug instance. Adjusts the stacklevel by 1 to report the correct caller.

Parameters:

debug_obj – TieredDebug instance to use (default: global debug).
begin – Debug level for BEGIN message (1-5, default 2). (int)
end – Debug level for END message (1-5, default 3). (int)
stacklevel – Stack level for reporting (1-9, default 2). (int)
extra – Extra metadata dictionary (default None). (dict[str, Any])

Returns:

Decorated function with logging.

Return type:

Callable

Examples

>>> debug.level = 3
>>> import logging
>>> debug.add_handler(logging.StreamHandler())
>>> @begin_end(debug, begin=2, end=3)
... def test_func():
...     return "Result"
>>> test_func()
'Result'