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:
Listenerand :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 ¶
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()
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
¶
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).Nonedispatches under the name ofevent's class.
Returns:
-
EventT–eventitself.
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).
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 ¶
Tell whether the listeners still to run should be skipped.