Go to the latest version of this document.

# ``twisted`.`logger`.`_format``

module documentation
(source)

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:`LogEvent` | A logging event.
error:`BaseException` | The formatting error.

Returns
`str` | A 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:`str` | A PEP-3101 format string.
mapping:`Mapping[str, Any]` | A `dict`-like object to format.

Returns
`str` | The 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:`str` | The last dotted segment of a formatting key, as parsed by `string.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
`PotentialCallWrapper` | A `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:`LogEvent` | A logging event.

Returns
`str` | A 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:`LogEvent` | The event containing the system specification.

Returns
`str` | A 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:`Failure` | The failure to retrieve a traceback from.

Returns
`str` | The formatted traceback.