xtr_event_dispatcher.bundle ¶
The xtr-dependency-injection bundle for xtr-event-dispatcher.
DISPATCHER_TAG
module-attribute
¶
The tag a dispatcher the container hands listeners to carries.
The dispatcher is registered as EventDispatcherInterface under its name as
the qualifier — None for the default one — with
:func:~xtr_event_dispatcher.bundle.event_dispatcher_factory; listeners join
it by naming it in their dispatcher attribute.
LISTENER_TAG
module-attribute
¶
The tag a listener service carries, its attributes those of @as_event_listener.
SUBSCRIBER_TAG
module-attribute
¶
The tag a subscriber service carries; its one attribute is dispatcher.
EVENT_CHANNEL
module-attribute
¶
The logging channel a traced dispatcher writes to.
EventDispatcherBundle ¶
Bases: Bundle[EventDispatcherConfig]
Registers the event dispatchers, and every declared listener and subscriber on them.
Start with no function listener and the default configuration.
prepend_extension ¶
When logging is active, add the event channel to its config.
build ¶
Register the listeners and subscribers the scan finds, and the pass handing them over.
The pass runs after every bundle's process hook, so a listener a
bundle tags there joins its dispatcher too.
load_extension ¶
load_extension(config: EventDispatcherConfig, services: ServiceConfigurator, builder: ContainerBuilder) -> None
Register a dispatcher per name, traced in debug mode, and the console command.
The command joins in debug mode only, when a console bundle is active.
boot
async
¶
Build every dispatcher, so a function listener the container cannot fill fails here.
EventDispatcherConfig
dataclass
¶
EventDispatcherConfig(event_aliases: Mapping[str | type, str | type] = dict[str | type, str | type](), dispatchers: tuple[str, ...] = (), trace: bool | None = None)
How the bundle builds the container's event dispatchers.
Buildable with no arguments: an application listing the bundle without configuring it gets one dispatcher holding every listener its scan finds.
Attributes:
-
event_aliases(Mapping[str | type, str | type]) –Event names — or classes — that listeners declare, mapped to the event they really listen to. Lets a library offer a short name for one of its events; another bundle adds its own with :meth:
with_event_aliases. -
dispatchers(tuple[str, ...]) –Dispatchers besides the default one, each registered under its name as the qualifier. A listener joins one with
@as_event_listener(dispatcher="audit"). -
trace(bool | None) –Wrap every dispatcher in a :class:
~xtr_event_dispatcher.debug.TraceableEventDispatcher.Nonetraces when the kernel is in debug mode.
aliases ¶
Return the event aliases with every class replaced by its event name.
with_event_aliases ¶
Return a copy that maps aliases as well.
An alias already mapped keeps its event — the application's choice
stands, whatever spelling either used — an application mapping a class
wins over a bundle respelling the same event as its name — and a copy
with nothing to add is this very config. This is how a bundle offers
names for its events from prepend_extension::
builder.prepend_extension_config(
EventDispatcherConfig, lambda c: c.with_event_aliases({"order.placed": OrderPlaced})
)
Raises:
-
InvalidArgumentError–When an alias or its event is not a name.
ListenerMap ¶
Event name -> (priority, listener) pairs, in the order they run.
What :class:~xtr_event_dispatcher.bundle.RegisterListenersPass sets as
every tagged dispatcher's listeners argument, worked out while the
container is built; each entry becomes a real listener only when the
dispatcher is built, and a service one only when an event reaches it.
A plain holder, not a mapping: the container resolves %name%
references in the mappings and dataclasses it is given as arguments, and
an event name is not one.
Hold by_event.
with_listeners_of ¶
Return a copy that also runs other's listeners of events.
Both sets interleave by priority; at equal priority this map's run first. How a dispatcher takes the listeners another one has for the events that bubble up to it — the security bundle gives every firewall's dispatcher the main dispatcher's listeners of the security events.
RegisterListenersPass ¶
Gives every dispatcher its listeners, ordered by priority and before/after.
A dispatcher is a service tagged event_dispatcher.dispatcher — the
bundle's own, and any another bundle registers. The pass reads the
services tagged event_dispatcher.listener and
event_dispatcher.subscriber and the functions carrying
@as_event_listener, checks each — its event, its method, its
dispatcher, its ordering — and sets every dispatcher's
:class:ListenerMap. It also makes each dispatcher reachable by name
under the contract's EventDispatcherInterface and
ListenerIntrospectionInterface. A mistake fails the build rather than
the first event.
:class:~xtr_event_dispatcher.bundle.EventDispatcherBundle registers it
behind every bundle's process hook, so a listener another bundle tags
there is registered too.
Read function listeners from functions, which the scan fills before the pass runs.
process ¶
Set the listener map of every tagged dispatcher.
Raises:
-
InvalidArgumentError–When a service tagged as a dispatcher is not registered as
EventDispatcherInterface. -
InvalidListenerError–When a listener cannot be registered, or listens on a dispatcher that does not exist.
-
InvalidSubscriberError–When a subscriber's declaration cannot be read.
traceable_event_dispatcher_factory ¶
Return the factory of a :class:TraceableEventDispatcher decorating a dispatcher.
Register it decorating the dispatcher's key, tagged kernel.reset so
each unit of work starts its trace afresh. logged writes the trace to
the "event" channel; ask for it only when the logging bundle is
active.