Skip to content

xtr_event_dispatcher.bundle

The xtr-dependency-injection bundle for xtr-event-dispatcher.

DISPATCHER_TAG module-attribute

DISPATCHER_TAG = 'event_dispatcher.dispatcher'

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

LISTENER_TAG = 'event_dispatcher.listener'

The tag a listener service carries, its attributes those of @as_event_listener.

SUBSCRIBER_TAG module-attribute

SUBSCRIBER_TAG = 'event_dispatcher.subscriber'

The tag a subscriber service carries; its one attribute is dispatcher.

EVENT_CHANNEL module-attribute

EVENT_CHANNEL = 'event'

The logging channel a traced dispatcher writes to.

EventDispatcherBundle

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

prepend_extension(builder: ContainerBuilder) -> None

When logging is active, add the event channel to its config.

build

build(builder: ContainerBuilder) -> None

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

boot() -> None

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.

EventDispatcherConfig(
    event_aliases={"order.placed": OrderPlaced},
    dispatchers=("audit",),
)

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. None traces when the kernel is in debug mode.

aliases

aliases() -> dict[str, str]

Return the event aliases with every class replaced by its event name.

with_event_aliases

with_event_aliases(aliases: Mapping[str | type, str | type]) -> EventDispatcherConfig

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:

ListenerMap

ListenerMap(by_event: Mapping[str, tuple[tuple[int, ListenerReference], ...]])

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

with_listeners_of(other: ListenerMap, events: Iterable[str | type]) -> ListenerMap

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

RegisterListenersPass(functions: Sequence[tuple[Callable[..., object], EventListenerDeclaration]])

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

process(builder: ContainerBuilder) -> None

Set the listener map of every tagged dispatcher.

Raises:

traceable_event_dispatcher_factory

traceable_event_dispatcher_factory(*, logged: bool) -> Callable[..., TraceableEventDispatcher]

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.