cs-pfx

Dynamic message prefixes providing execution context.

The primary facility here is Pfx, a context manager which maintains a per thread stack of context prefixes.

Usage is like this:

from cs.pfx import Pfx
...
def parser(filename):
  with Pfx("parse(%r)", filename):
    with open(filename) as f:
      for lineno, line in enumerate(f, 1):
        with Pfx("%d", lineno) as P:
          if line_is_invalid(line):
            raise ValueError("problem!")
          P.info("line = %r", line)

This produces log messages like:

datafile: 1: line = 'foo\n'

and exception messages like:

datafile: 17: problem!

which lets one put just the relevant complaint in exception and log messages and get useful calling context on the output. This does make for wordier logs and exceptions but used with a little discretion produces far more debuggable results.

Function `gen(func)`

Decorator for generators to manage the Pfx stack.

Before running the generator the current stack height is noted. After yield, the stack above that height is trimmed and saved, and the value yielded. On recommencement the saved stack is reapplied to the current stack (which may have changed) and the generator continued.

Class `Pfx`

A context manager to maintain a per-thread stack of message prefixes.

Method `Pfx.init(self, mark, *args, **kwargs)`

Initialise a new Pfx instance.

Parameters:

mark: message prefix string
args: if not empty, apply to the prefix string with %
absolute: optional keyword argument, default False. If true, this message forms the base of the message prefixes; existing prefixes will be suppressed.
loggers: which loggers should receive log messages.

Note: the mark and args are only combined if the Pfx instance gets used, for example for logging or to annotate an exception. Otherwise, they are not combined. Therefore the values interpolated are as they are when the Pfx is used, not necessarily as they were when the Pfx was created. If args is subject to change and you require the original values, apply them to mark immediately, for example:

with Pfx('message %s ...' % (arg1, arg2, ...)):

This is a bit more expensive, and the common usage is:

with Pfx('message %s ...', arg1, arg2, ...):

Function `pfx(func)`

Decorator for functions that should run inside:

with Pfx(func_name):

Use:

@pfx
def f(...):

Function `pfx_iter(tag, iterable)`

Wrapper for iterables to prefix exceptions with tag.

Class `PfxCallInfo`

MRO: Pfx
Subclass of Pfx to insert current function an caller into messages.

Function `pfxtag(tag, loggers=None)`

Decorator for functions that should run inside:

with Pfx(tag, loggers=loggers):

Use:

@pfxtag(tag)
def f(...):

Function `PfxThread(target=None, **kw)`

Factory function returning a Thread which presents the current prefix as context.

Function `prefix()`

Return the current Pfx prefix.

Function `PrePfx(tag, *args)`

Push a temporary value for Pfx._state._ur_prefix to enloundenify messages.

Function `XP(msg, *args, **kwargs)`

Variation on cs.x.X which prefixes the message with the current Pfx prefix.

Function `XX(prepfx, msg, *args, **kwargs)`

Trite wrapper for XP() to transiently insert a leading prefix string.

Example:

XX("NOTE!", "some message")

Release files for cs-pfx 20190607

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cs-pfx 20190607
File	Size	Uploaded
cs.pfx-20190607.tar.gz	7.0 kB	Jun 7, 2019	Details

Release files / cs.pfx-20190607.tar.gz

Download URL	cs.pfx-20190607.tar.gz
Size	7.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`1b962c7ff861402688f45020fcc58c5757bd54eb5177912d50f34595746ac1cd`
BLAKE2b-256 checksum How to use checksums	`295e25a8e8c4c0756e5d7adea64c55635dcbdf4b3b1da4ef0449786950a298ee`
Upload date	Jun 7, 2019
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/1.13.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/39.0.1 requests-toolbelt/0.9.1 tqdm/4.32.1 CPython/3.7.3`