# ``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.
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 | `_formatEvent` | Formats an event as a string, using the format in `event["log_format"]`.
Function | `_formatSystem` | No summary
Function | `_formatTraceback` | No summary

def formatUnformattableEvent(event, error): (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, mapping): (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 _formatEvent(event): (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): (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): (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.