all2md.cli.timing

Timing and instrumentation utilities for all2md CLI.

This module provides utilities for timing operations and logging performance metrics in trace mode.

class all2md.cli.timing.TimingContext

Bases: object

Context manager for timing operations with automatic logging.

Parameters:

operation_name (str) – Name of the operation being timed
logger_instance (logging.Logger, optional) – Logger to use for output. If None, uses module logger
log_level (int, default logging.DEBUG) – Log level for timing messages

Examples

>>> with TimingContext("PDF parsing"):
...     parse_pdf(document)
[DEBUG] PDF parsing completed in 2.45s

Initialize the timing context for an operation.

__init__(operation_name: str, logger_instance: Logger | None = None, log_level: int = 10) → None: Initialize the timing context for an operation.

property elapsed: float

Get elapsed time in seconds.

Returns:: Elapsed time in seconds
Return type:: float

all2md.cli.timing.instrument_timing(operation_name: str | None = None, logger_instance: Logger | None = None, log_level: int = 10) → Callable[[F], F]

Automatically time and log function execution.

Parameters:

operation_name (str, optional) – Name for the operation. If None, uses function name
logger_instance (logging.Logger, optional) – Logger to use. If None, uses module logger
log_level (int, default logging.DEBUG) – Log level for timing messages

Returns:

Decorated function with timing instrumentation

Return type:

Callable

Examples

>>> @instrument_timing("PDF conversion")
... def convert_pdf(path):
...     return process(path)

all2md.cli.timing.timing(operation_name: str, logger_instance: Logger | None = None) → Generator[TimingContext, None, None]

Context manager for timing operations.

Parameters:

operation_name (str) – Name of the operation being timed
logger_instance (logging.Logger, optional) – Logger to use for output

Yields:

TimingContext – Timing context with elapsed time tracking

Examples

>>> with timing("File processing") as timer:
...     process_files()
...     print(f"Processed in {timer.elapsed:.2f}s")

all2md.cli.timing.format_duration(seconds: float) → str

Format duration in human-readable format.

Parameters:: seconds (float) – Duration in seconds
Returns:: Formatted duration string
Return type:: str

Examples

>>> format_duration(0.123)
'123ms'
>>> format_duration(65.5)
'1m 5.5s'
>>> format_duration(3665)
'1h 1m 5s'

class all2md.cli.timing.OperationTimer

Bases: object

Timer for tracking multiple operations with cumulative stats.

Examples

>>> timer = OperationTimer()
>>> timer.start("parsing")
>>> # ... do work ...
>>> timer.stop("parsing")
>>> timer.start("rendering")
>>> # ... do work ...
>>> timer.stop("rendering")
>>> timer.report()

Initialize the operation timer with empty tracking dictionaries.

__init__() → None: Initialize the operation timer with empty tracking dictionaries.

start(operation_name: str) → None

Start timing an operation.

Parameters:: operation_name (str) – Name of the operation

stop(operation_name: str) → float

Stop timing an operation and record duration.

Parameters:: operation_name (str) – Name of the operation
Returns:: Duration in seconds
Return type:: float
Raises:: ValueError – If operation was not started

get_stats(operation_name: str) → dict[str, float]

Get statistics for an operation.

Parameters:: operation_name (str) – Name of the operation
Returns:: Statistics including total, count, mean, min, max
Return type:: dict[str, float]

report(logger_instance: Logger | None = None) → str

Generate timing report.

Parameters:: logger_instance (logging.Logger, optional) – Logger to output report to
Returns:: Formatted timing report
Return type:: str