Skip to content

xtr_logging.bundle

The xtr-dependency-injection bundle for xtr-logging.

LoggingConfig

Bases: Struct

The channels, handlers and processors of an application.

Checked as it is made: every handler a wrapper names must exist, wrappers must not nest each other in a loop, and a processor may only target a channel or handler that exists.

Attributes:

  • handlers (dict[str, HandlerConfig]) –

    Named handlers, in declaration order. Wrappers name the handlers they wrap; those leave every channel's stack.

  • channels (tuple[str, ...]) –

    Channels beyond :attr:default_channel. Channels named in a handler's channels list are declared too.

  • processors (tuple[ProcessorConfig, ...]) –

    Processors and where they run. By default one redacting processor, masking secret keys, URL credentials and secret query values; a configuration naming its own processors replaces it, so list a RedactingProcessorConfig there to keep it.

  • default_channel (str) –

    The channel a logger is on when none is asked for.

  • capture (CaptureConfig | None) –

    Send the standard library's logging into channels, and only there. Off when omitted.

all_channels property

all_channels: tuple[str, ...]

Every declared channel: the default, the listed, then those named by handlers.

nested_handlers property

nested_handlers: frozenset[str]

Handlers kept off every channel's stack: those named by another, or marked nested.

top_level_handlers property

top_level_handlers: tuple[str, ...]

Handlers on the channel stacks, highest priority first, ties in declaration order.

from_mapping classmethod

from_mapping(data: Mapping[str, object]) -> LoggingConfig

Read configuration from plain data — parsed TOML, JSON or YAML.

Values are not coerced: "3" is not a number. Levels are written by name ("error") or value (400).

Raises:

with_channels

with_channels(*channels: str) -> LoggingConfig

Return a copy that declares channels as well.

A channel already declared — listed, the default one, or named by a handler — is not added twice, and a copy with nothing to add is this very config. This is how a bundle gives itself a channel from prepend_extension::

builder.prepend_extension_config(LoggingConfig, lambda c: c.with_channels("mail"))

with_handler

with_handler(name: str, handler: HandlerConfig) -> LoggingConfig

Return a copy that holds handler under name as well.

A name the application already gave a handler is left to the application's: the copy is this very config. This is how a bundle adds a handler of its own from prepend_extension::

builder.prepend_extension_config(
    LoggingConfig, lambda c: c.with_handler("audit", ServiceHandlerConfig(id="audit"))
)

LoggingBundle

LoggingBundle()

Bases: Bundle[LoggingConfig]

Turns a :class:LoggingConfig into a logger per channel in the container.

Start empty; per-kernel state is populated during build/load_extension.

build

build(builder: ContainerBuilder) -> None

Register attribute autoconfiguration for @as_processor classes and functions.

A class becomes a service — its constructor injected — whose instance is attached; a function is the processor itself, attached as it is.

load_extension

load_extension(config: LoggingConfig, services: ServiceConfigurator, builder: ContainerBuilder) -> None

Register the :class:LoggerFactory, a :class:Services, every logger, and the log unit.

:class:LogUnitParticipant makes every unit of work the container opens a log unit of its own; the log unit and the log context are registered as what a new connection starts without.

process

process(builder: ContainerBuilder) -> None

Check every service id the configuration names exists in the container.