Skip to content

xtr_event_dispatcher_contracts

The event dispatching contract: what code that emits events depends on, and nothing more.

Code that announces something happened — an order placed, a message consumed — should not decide who hears it. It takes an :class:EventDispatcherInterface and hands it an event object; the application decides which listeners run, in which order, and whether any of them stops the rest. Depending on this package costs a library nothing but the contract.

@dataclass(frozen=True)
class OrderPlaced(Event):
    order_id: int


await dispatcher.dispatch(OrderPlaced(42))
  • :class:EventDispatcherInterface — dispatch an event.
  • :class:Event / :class:StoppableEventInterface — an event a listener can stop.
  • :class:ListenerIntrospectionInterface — which listeners an event has.
  • :data:Listener and :func:event_name_of — what a listener is called with, and the name an event is known by.

xtr-event-dispatcher implements it, and re-exports every symbol here so the two are never two different objects.

Listener

Listener = Callable[..., object]

A callable run when an event it listens to is dispatched.

A dispatcher calls it with the event, the name the event was dispatched under, and the dispatcher itself — as many of the three, in that order, as it takes positionally; a listener caring only about the event takes one. What it returns is ignored, except that an awaitable is awaited before the next listener runs, so a listener is a plain function or an async def alike.

Event

An event any listener can stop, so the listeners after it are skipped.

Carries no data itself: derive from it and add what the listeners need, usually as a dataclass. It satisfies :class:~xtr_event_dispatcher_contracts.stoppable_event_interface.StoppableEventInterface without deriving from it, so a class of events stays a plain class.

@dataclass(frozen=True)
class OrderPlaced(Event):
    order_id: int


def reject_fraud(event: OrderPlaced) -> None:
    if is_fraudulent(event.order_id):
        event.stop_propagation()

is_propagation_stopped

is_propagation_stopped() -> bool

Tell whether a listener has stopped this event.

stop_propagation

stop_propagation() -> None

Skip every listener that has not run yet for this event.

Works on a frozen dataclass too: stopping is about the dispatch, not a change to the data the event carries.

EventDispatcherInterface

Bases: Protocol

Announces that something happened, leaving who reacts to the application.

The type code that emits events should depend on. It says nothing about how listeners are registered — that belongs to whoever builds the dispatcher — so a library announcing its lifecycle takes this and never learns what listens.

dispatch async

dispatch(event: EventT, event_name: str | type | None = None) -> EventT

Run every listener of the event, highest priority first, and return the event.

Listeners run one after the other, each awaited before the next. When the event is a :class:~xtr_event_dispatcher_contracts.stoppable_event_interface.StoppableEventInterface, no listener runs once it reports being stopped. An exception a listener raises reaches the caller unchanged, and the listeners after it do not run.

Parameters:

  • event (EventT) –

    What happened, handed to every listener. Listeners may record their outcome on it, which is why it is returned.

  • event_name (str | type | None, default: None ) –

    The name to dispatch under, or a class standing for its name (see :func:~xtr_event_dispatcher_contracts.event_name_of.event_name_of). None dispatches under the name of event's class.

Returns:

  • EventT –

    event itself.

ListenerIntrospectionInterface

Bases: Protocol

Reads the listeners of a dispatcher without registering any.

For code that needs to know who listens — a debugging tool, a dispatcher wrapping another — but has no business adding or removing listeners. Wherever an event name is taken, a class stands for its name (see :func:~xtr_event_dispatcher_contracts.event_name_of.event_name_of).

get_listeners

get_listeners(event_name: None = None) -> dict[str, list[Listener]]
get_listeners(event_name: str | type) -> list[Listener]
get_listeners(event_name: str | type | None = None) -> dict[str, list[Listener]] | list[Listener]

Return the listeners of one event in the order they run, or of every event.

Parameters:

  • event_name (str | type | None, default: None ) –

    The event to read. None reads every event that has a listener, mapping each name to its listeners.

get_listener_priority

get_listener_priority(event_name: str | type, listener: Listener) -> int | None

Return the priority listener runs at for the event.

Returns:

  • int | None –

    The priority, or None when the event has no such listener.

has_listeners

has_listeners(event_name: str | type | None = None) -> bool

Tell whether the event — or, given None, any event — has a listener.

StoppableEventInterface

Bases: Protocol

An event a listener can mark as handled, so the listeners after it are skipped.

A dispatcher asks before calling each listener, and stops at the first True. How the event gets stopped is the event's business; :class:~xtr_event_dispatcher_contracts.event.Event offers :meth:~xtr_event_dispatcher_contracts.event.Event.stop_propagation.

is_propagation_stopped

is_propagation_stopped() -> bool

Tell whether the listeners still to run should be skipped.