Skip to main content

xtr-event-dispatcher-contracts

The event dispatching contract, and nothing else — so a library that emits events installs nothing else.

python 3.11+ asyncio core dependencies: 0 typed license MIT

Why?

A library that announces what happened — an order placed, a message consumed — should not decide who hears it. It takes an event dispatcher, hands it an event object, and leaves the listeners to the application that wires it. That needs the contract, not a dispatcher:

  • 📣 EventDispatcherInterface — await dispatcher.dispatch(event), and the event comes back.
  • 🛑 Event / StoppableEventInterface — an event any listener can stop.
  • 🔎 ListenerIntrospectionInterface — which listeners an event has, and in which order.
  • 🧷 Listener and event_name_of() — what a listener is called with, and the name an event is known by.
  • 🪶 No dependencies.
from dataclasses import dataclass

from xtr_event_dispatcher_contracts import Event, EventDispatcherInterface


@dataclass(frozen=True)
class MessageConsumed(Event):
    message_id: str


class Worker:
    def __init__(self, events: EventDispatcherInterface) -> None:
        self._events = events

    async def handled(self, message_id: str) -> None:
        await self._events.dispatch(MessageConsumed(message_id))

Install

uv add xtr-event-dispatcher-contracts

Requires Python 3.11+.

Who installs what

Depends on
A library that emits events xtr-event-dispatcher-contracts at runtime.
An application xtr-event-dispatcher, which implements this contract and wires listeners from a container.

xtr-event-dispatcher re-exports Event, StoppableEventInterface, ListenerIntrospectionInterface, Listener and event_name_of rather than redefining them, so a library written against this package and an application using that one share the same objects. Its own EventDispatcherInterface extends the one here with registering listeners.

The contract

class EventDispatcherInterface(Protocol):
    async def dispatch(self, event: T, event_name: str | type | None = None) -> T: ...
  • Names. Events are keyed by name: a string, or a class standing for "<module>.<qualname>" (event_name_of). Without a name, an event is dispatched under its class's.
  • Order. Listeners run highest priority first, one after the other, each awaited before the next. An exception a listener raises reaches the caller unchanged.
  • Stopping. An event that is a StoppableEventInterface stops reaching listeners once one stops it. Event is the base class that does this, frozen dataclasses included: event.stop_propagation().
  • Listeners (Listener) are called with the event, its name and the dispatcher — as many of the three as they take, by position; an awaitable result is awaited.

ListenerIntrospectionInterface reads listeners without registering any: get_listeners(name) in running order (or every event's, given no name), get_listener_priority(name, listener), has_listeners(name=None).

Development

Developed in the python-xtr monorepo, under packages/xtr-event-dispatcher-contracts; run the commands below from there. The python-xtr-event-dispatcher-contracts repository is a read-only copy, so send issues and pull requests to the monorepo.

uv sync
uv run ruff check && uv run ruff format --check && uv run basedpyright && uv run ty check && uv run pytest

License

MIT — see LICENSE.

Metadata

Release files for xtr-event-dispatcher-contracts 5.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xtr-event-dispatcher-contracts 5.2.0
File Size Uploaded Provenance Actions
xtr_event_dispatcher_contracts-5.2.0.tar.gz 8.2 kB With provenance Details for xtr_event_dispatcher_contracts-5.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xtr-event-dispatcher-contracts 5.2.0
File Interpreter ABI Platform Actions
xtr_event_dispatcher_contracts-5.2.0-py3-none-any.whl Python 3 none any Details for xtr_event_dispatcher_contracts-5.2.0-py3-none-any.whl

Total release size: 18.5 kB

Release files / xtr_event_dispatcher_contracts-5.2.0.tar.gz

Download URL xtr_event_dispatcher_contracts-5.2.0.tar.gz
Size 8.2 kB
Tags Source
SHA-256 checksum
How to use checksums
072052499c3cd9300105a51b7544c599486705c18f019d34dcbca0ddd8869142
BLAKE2b-256 checksum
How to use checksums
60b6c54953a89b44b18ebb6bb22f3fd54b84f4e7052b870c99f9a351e61fd800
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Release files / xtr_event_dispatcher_contracts-5.2.0-py3-none-any.whl

Download URL xtr_event_dispatcher_contracts-5.2.0-py3-none-any.whl
Size 10.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
19be9d4a11262c3e97bc454bee57c6ca147e05636586b56e4de8f5f52fabedbd
BLAKE2b-256 checksum
How to use checksums
38c9ee969563a87c2ea63ab2585908b31e041e7bd380f334d4d03641e31a4102
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Security for xtr-event-dispatcher-contracts 5.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for xtr_event_dispatcher_contracts-5.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page