ddp_utils.debug_logger¶

import ddp_utils.debug_logger

Provide lightweight file-backed debugging and call tracing.

Handlers remain open for the logger lifetime, avoiding a file open per record. DebugLogger.trace instruments selected callables, while DebugLogger.trace_all instruments public instance methods once when a class is defined. Thread-local state supplies the active logger and nested-call depth.

Examples

Provide lightweight file-backed debugging and call tracing:

logger = DebugLogger("run-42", storage="local", local_dir="debug")
with logger.session():
    logger.info("Started")

class ddp_utils.debug_logger.GlobalConfig(global_dir: str | Path)¶

Bases: object

Configure the shared directory used for global debug logs.

Variables

Name	Type	Description
global_dir	str \| pathlib.Path	Shared log directory, normalized to `Path`.

Examples

Configure the shared directory used for global debug logs:

config = GlobalConfig(global_dir="/var/log/projects")

class ddp_utils.debug_logger.DebugLogger(guid: str, mode: str = 'silent', storage: str = 'local', local_dir: Path | str | None = None, global_config: GlobalConfig | None = None, global_dir: Path | str | None = None, max_repr: int = 500, logger_attr: str = 'log')¶

Bases: object

Write one run’s debug stream to local, global, or mirrored log files.

Silent mode writes only to files; active mode also mirrors records to stdout. Decorated methods discover the logger through a configurable instance attribute or the current thread’s active logger stack.

Examples

Write one run’s debug stream to local, global, or mirrored log files:

logger = DebugLogger("run-42", storage="local", local_dir="debug")

Initialize file handlers and optional console mirroring for one run.

Parameters

Name	Type	Description
guid	str	Run identifier included in the log filename and session marker.
mode	Mode	`silent` for file-only output or `active` to also mirror to stdout.
storage	Storage	Destination policy: `local`, `global`, or `both`.
local_dir	Optional[Union[str, Path]]	Local log directory required by local or mirrored storage.
global_config	Optional[GlobalConfig]	Optional shared-directory configuration.
global_dir	Optional[Union[str, Path]]	Explicit global directory overriding `global_config`.
max_repr	int	Maximum representation length before truncation.
logger_attr	str	Instance attribute inspected by trace wrappers for a logger.

Raises

Exception	Description
ValueError	Mode, storage policy, or required destination configuration is invalid.
OSError	A destination directory or log file cannot be created or opened.

Examples

Initialize file handlers and optional console mirroring for one run:

logger = DebugLogger("run-42", mode="silent", storage="local", local_dir="debug")

debug(msg: str) → None¶

Write a debug-level message with current call-depth indentation.

Parameters

Name	Type	Description
msg	str	Message or contextual exception label.

Examples

Write a debug-level message with current call-depth indentation:

logger.debug("cache lookup")

info(msg: str) → None¶

Write an informational message with current call-depth indentation.

Parameters

Name	Type	Description
msg	str	Message or contextual exception label.

Examples

Write an informational message with current call-depth indentation:

logger.info("worker started")

warning(msg: str) → None¶

Write a warning message with current call-depth indentation.

Parameters

Name	Type	Description
msg	str	Message or contextual exception label.

Examples

Write a warning message with current call-depth indentation:

logger.warning("retrying request")

error(msg: str) → None¶

Write an error message with current call-depth indentation.

Parameters

Name	Type	Description
msg	str	Message or contextual exception label.

Examples

Write an error message with current call-depth indentation:

logger.error("request failed")

note(msg: str) → None¶

Record the reason for an execution decision as an informational note.

Parameters

Name	Type	Description
msg	str	Message or contextual exception label.

Examples

Record the reason for an execution decision as an informational note:

logger.note("record already processed; skipping")

value(name: str, value: Any, src: str | None = None) → None¶

Record a named value and optionally identify its source.

Parameters

Name	Type	Description
name	str	Label assigned to a recorded value.
value	Any	Value represented and bounded for the log record.
src	str \| None	Optional description of where the value originated.

Examples

Record a named value and optionally identify its source:

logger.value("page", 4, src="cursor")

exception(msg: str = '') → None¶

Record the traceback of the exception currently being handled.

Parameters

Name	Type	Description
msg	str	Message or contextual exception label.

Examples

Record the traceback of the exception currently being handled:

try:
    perform_work()
except Exception:
    logger.exception("perform_work failed")

activate() → None¶

Push this logger onto the current thread’s active logger stack.

Examples

Push this logger onto the current thread’s active logger stack:

logger.activate()

deactivate() → None¶

Pop the most recently activated logger from the current thread.

Examples

Pop the most recently activated logger from the current thread:

logger.deactivate()

session()¶

Activate this logger for a managed run and always close its handlers.

Normal completion records an OK marker. An escaping BaseException records an error marker and traceback before it is re-raised.

Returns

Context manager yielding this logger.

Raises

Exception	Description
BaseException	Any exception escaping the managed run is logged and re-raised.

Examples

Activate this logger for a managed run and always close its handlers:

with logger.session():
    perform_work()

close() → None¶

Flush, close, and detach every handler owned by this logger.

Examples

Flush, close, and detach every handler owned by this logger:

logger.close()

static trace(func: F | None = None, *, attr: str = 'log') → Any¶

Decorate one callable with entry, return, and exception tracing.

The decorator supports both @DebugLogger.trace and configured invocation. If no logger is available, the wrapped callable executes directly without trace formatting.

Parameters

Name	Type	Description
func	F \| None	Callable supplied by bare-decorator syntax.
attr	str	First-argument attribute used to locate a logger.

Returns

Type	Description
Any	Decorated callable or a decorator awaiting a callable.

Examples

Decorate one callable with entry, return, and exception tracing:

@DebugLogger.trace
def calculate(value):
    return value * 2

static trace_all(cls: type | None = None, *, attr: str = 'log') → Any¶

Decorate every public instance function defined directly on a class.

Private names and non-FunctionType descriptors are left unchanged. The decorator supports both bare and configured invocation.

Parameters

Name	Type	Description
cls	type \| None	Class supplied by bare class-decorator syntax.
attr	str	First-argument attribute used to locate a logger.

Returns

Type	Description
Any	Decorated class or a decorator awaiting a class.

Examples

Decorate every public instance function defined directly on a class:

@DebugLogger.trace_all
class Worker:
    def run(self):
        return True