stacklog package

Submodules

• stacklog.compat module
  • ParamSpec
    • ParamSpec.args
    • ParamSpec.kwargs
  • StrEnum

Module contents

Top-level package for stacklog.

Classes:

stacklog(method, message, *args[, conditions])	Stack log messages
stacktime(method, message[, unit])	Stack log messages with timing information

class stacklog.stacklog(method: Callable[[str], Any], message: str, *args, conditions: List[Tuple[type, str]] | None = None, **kwargs)

Bases: object

Stack log messages

Example usage:

with stacklog(logging.info, 'Running long function'):
    run_long_function()

with stacklog(logging.info, 'Running error-prone function'):
    raise Exception

with stacklog(logging.info, 'Skipping not implemented',
              conditions=[(NotImplementedError, 'SKIPPED')]):
    raise NotImplementedError

This produces logging output:

INFO:root:Running long function...
INFO:root:Running long function...DONE
INFO:root:Running error-prone function...
INFO:root:Running error-prone function...FAILURE
INFO:root:Skipping not implemented...
INFO:root:Skipping not implemented...SKIPPED

Parameters:

• method – log callable

• message – log message

• *args – right-most args to log method

• conditions (List[Tuple]) – list of tuples of exceptions or tuple of exceptions to catch and log conditions, such as [(NotImplementedError, 'SKIPPED')].

• **kwargs – kwargs to log method

Methods:

log([suffix])	Log a message with given suffix
on_begin(func)	Add callback for beginning of block
on_condition(match, func)	Add callback for failed execution
on_enter(func)	Append callback for entering block
on_exit(func)	Append callback for exiting block
on_failure(func)	Add callback for failed execution
on_success(func)	Add callback for successful execution

log(suffix: str = '') → None

Log a message with given suffix

on_begin(func: Callable[[stacklog], None]) → None

Add callback for beginning of block

The function func takes one argument, the stacklog instance.

on_condition(match: Callable[[type | None], bool] | Callable[[type | None, BaseException | None], bool] | Callable[[type | None, BaseException | None, TracebackType | None], bool], func: Callable[[stacklog], None])

Add callback for failed execution

The first function match takes up to three arguments, exc_type (type), exc_val (BaseException), and exc_tb (types.TracebackType). This is the same tuple of values as returned by sys.exc_info() and allows the client to determine whether to respond to this exception or not. This function should return a bool and have no side effects.

The second function func takes the stacklog instance as the first argument and the exception info triple as the remaining arguments.

Both methods can optionally receive fewer arguments by simply declaring fewer arguments in their signatures. They will be called with the first arguments they declare.

See also: - https://docs.python.org/3/library/sys.html#sys.exc_info

on_enter(func: Callable[[stacklog], None])

Append callback for entering block

The function func takes one argument, the stacklog instance. This callback is intended for initializing resources that will be used after the block has been executed.

on_exit(func: Callable[[stacklog], None])

Append callback for exiting block

The function func takes one argument, the stacklog instance. This callback is intended for resolving or processing resources.

on_failure(func: Callable[[stacklog], None])

Add callback for failed execution

The function func takes one argument, the stacklog instance.

on_success(func: Callable[[stacklog], None]) → None

Add callback for successful execution

The function func takes one argument, the stacklog instance.

class stacklog.stacktime(method: Callable[[str], Any], message: str, unit: str = 'auto', **kwargs)

Bases: stacklog

Stack log messages with timing information

The same arguments apply as to stacklog, with one additional kwarg.

Parameters:

unit (str) – one of ‘auto’, ‘ns’, ‘mks’, ‘ms’, ‘s’, ‘min’. Defaults to ‘auto’.

Example usage:

>>> with stacktime(print, 'Running some code', unit='ms'):
...     time.sleep(1e-2)
...
Running some code...
Running some code...DONE in 11.11 ms

Attributes:

elapsed
elapsed_seconds

property elapsed: str

property elapsed_seconds: float