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'schannelslist 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
RedactingProcessorConfigthere 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
¶
Every declared channel: the default, the listed, then those named by handlers.
nested_handlers
property
¶
Handlers kept off every channel's stack: those named by another, or marked nested.
top_level_handlers
property
¶
Handlers on the channel stacks, highest priority first, ties in declaration order.
from_mapping
classmethod
¶
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:
-
InvalidConfigurationError–If the data does not fit, naming where.
-
UnknownHandlerError–If a wrapper or processor names a missing handler.
-
CircularHandlerReferenceError–If wrappers nest each other in a loop.
-
UnknownChannelError–If a processor targets a missing channel.
with_channels ¶
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 ¶
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 ¶
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 ¶
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 ¶
Check every service id the configuration names exists in the container.