module documentation

Tools for formatting logging events.

Class CallMapping Read-only mapping that turns a ()-suffix in key names into an invocation of the key rather than a lookup of the key.
Class PotentialCallWrapper Object wrapper that wraps getattr() so as to process call-parentheses "()" after a dotted attribute access.
Function formatUnformattableEvent Formats an event as text that describes the event generically and a formatting error.
Function formatWithCall Format a string like str.format, but:
Function keycall Check to see if key ends with parentheses ("()"); if not, wrap up the result of get in a PotentialCallWrapper. Otherwise, call the result of get first, before wrapping it up.
Function _formatEvent Formats an event as a string, using the format in event["log_format"].
Function _formatSystem Format the system specified in the event in the "log_system" key if set, otherwise the "log_namespace" and "log_level", joined by a "#". Each defaults to "-" is not set. If formatting fails completely, "UNFORMATTABLE" is returned.
Function _formatTraceback Format a failure traceback, assuming UTF-8 and using a replacement strategy for errors. Every effort is made to provide a usable traceback, but should not that not be possible, a message and the captured exception are logged.
def formatUnformattableEvent(event: LogEvent, error: BaseException) -> str: (source)

Formats an event as text that describes the event generically and a formatting error.

Parameters
event:LogEventA logging event.
error:BaseExceptionThe formatting error.
Returns
strA formatted string.
def formatWithCall(formatString: str, mapping: Mapping[str, Any]) -> str: (source)

Format a string like str.format, but:

  • taking only a name mapping; no positional arguments
  • with the additional syntax that an empty set of parentheses correspond to a formatting item that should be called, and its result str'd, rather than calling str on the element directly as normal.

For example:

    >>> formatWithCall("{string}, {function()}.",
    ...                dict(string="just a string",
    ...                     function=lambda: "a function"))
    'just a string, a function.'
Parameters
formatString:strA PEP-3101 format string.
mapping:Mapping[str, Any]A dict-like object to format.
Returns
strThe string with formatted values interpolated.
def keycall(key: str, getter: Callable[[str], Any]) -> PotentialCallWrapper: (source)

Check to see if key ends with parentheses ("()"); if not, wrap up the result of get in a PotentialCallWrapper. Otherwise, call the result of get first, before wrapping it up.

Parameters
key:strThe last dotted segment of a formatting key, as parsed by Formatter.vformat, which may end in ().
getter:Callable[[str], Any]A function which takes a string and returns some other object, to be formatted and stringified for a log.
Returns
PotentialCallWrapperA PotentialCallWrapper that will wrap up the result to allow for subsequent usages of parens to defer execution to log-format time.
def _formatEvent(event: LogEvent) -> str: (source)

Formats an event as a string, using the format in event["log_format"].

This implementation should never raise an exception; if the formatting cannot be done, the returned string will describe the event generically so that a useful message is emitted regardless.

Parameters
event:LogEventA logging event.
Returns
strA formatted string.
def _formatSystem(event: LogEvent) -> str: (source)

Format the system specified in the event in the "log_system" key if set, otherwise the "log_namespace" and "log_level", joined by a "#". Each defaults to "-" is not set. If formatting fails completely, "UNFORMATTABLE" is returned.

Parameters
event:LogEventThe event containing the system specification.
Returns
strA formatted string representing the "log_system" key.
def _formatTraceback(failure: Failure) -> str: (source)

Format a failure traceback, assuming UTF-8 and using a replacement strategy for errors. Every effort is made to provide a usable traceback, but should not that not be possible, a message and the captured exception are logged.

Parameters
failure:FailureThe failure to retrieve a traceback from.
Returns
strThe formatted traceback.