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')

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)

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.

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

property logger: Logger

Get the configured logger instance.

Returns:

Logger instance for this TieredDebug object.

Return type:

logging.Logger

Examples

>>> debug = TieredDebug()
>>> isinstance(debug.logger, logging.Logger)
True

check_val(val: int, kind: str) → int

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

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) → Iterator[None]

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(level: Literal[1, 2, 3, 4, 5], msg: str, *args, exc_info: bool | None = None, stack_info: bool | None = None, stacklevel: int | None = None, extra: Dict[str, Any] | None = None) → None

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

lv1(msg: str, *args, exc_info: bool | None = None, stack_info: bool | None = None, stacklevel: int | None = None, extra: Dict[str, Any] | None = None) → None

Log a message at debug level 1 (always logged).

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])

Raises:

TypeError – If extra is not a dictionary or None.

Examples

>>> debug = TieredDebug(level=2)
>>> import logging
>>> debug.add_handler(logging.StreamHandler())
>>> debug.lv1("Level 1 message: %s", "test")

lv2(msg: str, *args, exc_info: bool | None = None, stack_info: bool | None = None, stacklevel: int | None = None, extra: Dict[str, Any] | None = None) → None

Log a message at debug level 2 (logged if 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])

Raises:

TypeError – If extra is not a dictionary or None.

Examples

>>> debug = TieredDebug(level=2)
>>> import logging
>>> debug.add_handler(logging.StreamHandler())
>>> debug.lv2("Level 2 message: %s", "test")

lv3(msg: str, *args, exc_info: bool | None = None, stack_info: bool | None = None, stacklevel: int | None = None, extra: Dict[str, Any] | None = None) → None

Log a message at debug level 3 (logged if 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])

Raises:

TypeError – If extra is not a dictionary or None.

Examples

>>> debug = TieredDebug(level=3)
>>> import logging
>>> debug.add_handler(logging.StreamHandler())
>>> debug.lv3("Level 3 message: %s", "test")

lv4(msg: str, *args, exc_info: bool | None = None, stack_info: bool | None = None, stacklevel: int | None = None, extra: Dict[str, Any] | None = None) → None

Log a message at debug level 4 (logged if 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])

Raises:

TypeError – If extra is not a dictionary or None.

Examples

>>> debug = TieredDebug(level=4)
>>> import logging
>>> debug.add_handler(logging.StreamHandler())
>>> debug.lv4("Level 4 message: %s", "test")

lv5(msg: str, *args, exc_info: bool | None = None, stack_info: bool | None = None, stacklevel: int | None = None, extra: Dict[str, Any] | None = None) → None

Log a message at debug level 5 (logged if 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])

Raises:

TypeError – If extra is not a dictionary or None.

Examples

>>> debug = TieredDebug(level=5)
>>> import logging
>>> debug.add_handler(logging.StreamHandler())
>>> debug.lv5("Level 5 message: %s", "test")

Sample usage of tiered debug logging with a global instance and decorator.

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)

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'