xtr-remote-event
Events received from another system, as one value type, handed to the consumer registered under their source's name — directly or through a message bus.
Why?
An event from elsewhere — a delivery report, a payment notice, a message from a provider — arrives in whatever shape its sender chose. Once it is read, though, what the application does with it is always the same: hand it to the code that handles events from that sender.
This package is that last step, and nothing else: one value type for the event, a one-method contract for the consumer, a decorator naming which sources a consumer answers for, and a message so the work happens on a worker rather than in the request that received it.
Install
uv add xtr-remote-event # the event, the consumer contract, the decorator
uv add xtr-remote-event xtr-dependency-injection # + the container, for the RemoteEventBundle
The container is not a dependency: the bundle is used when xtr-dependency-injection is installed beside the package, never as an extra, and the event, the consumers and the message work without it, as the Quick start shows. xtr-serializer is: it is what carries an event as its own class.
Quick start
A consumer is a class with one method, declared with the name of the source whose events it answers for:
import asyncio
from xtr_remote_event import ConsumerLocator, RemoteEvent, as_remote_event_consumer
@as_remote_event_consumer("acme")
class AcmeConsumer:
async def consume(self, event: RemoteEvent) -> None:
print(f"{event.name} {event.id} {event.payload}")
async def main() -> None:
consumers = ConsumerLocator({"acme": AcmeConsumer()})
consumer = await consumers.get("acme")
await consumer.consume(RemoteEvent("order.paid", "evt_1", {"total": 4200}))
asyncio.run(main())
A RemoteEvent is three fields and no behaviour: name (the source, and what decides who is
handed it), id (what the sender calls this event) and payload (the body as it arrived). It
is frozen, so no consumer can rebind name, id or payload on the event; payload is an
ordinary dict, though, and the next consumer is handed the same event, so every consumer must treat
the payload as read-only.
Events of your own
RemoteEvent is the base of a class hierarchy, declared with xtr-serializer's
@discriminator_map(). Derive a class for a source worth naming, and register the name its
values are written under:
from dataclasses import dataclass, field
from xtr_remote_event import RemoteEvent
from xtr_serializer import ZonedDateTime, discriminator_name
@dataclass(frozen=True, slots=True)
class Recipient:
address: str
@discriminator_name("delivery_report")
@dataclass(frozen=True, slots=True)
class DeliveryReport(RemoteEvent):
delivered_at: ZonedDateTime
recipient: Recipient
tags: tuple[str, ...] = ()
metadata: dict[str, str] = field(default_factory=dict[str, str])
Wherever a field declares RemoteEvent — the event in ConsumeRemoteEventMessage, the one in
xtr-webhook's SendWebhookMessage — a DeliveryReport is written with "$type": "delivery_report" beside its fields, and read back a DeliveryReport: its dates, its nested
Recipient, its tuple and its dict as they left. A plain RemoteEvent is written under
"remote_event". A webhook's HTTP body is the event's payload alone, so a receiver over HTTP
gets a plain RemoteEvent — see xtr-webhook's
Known limitations.
- Register the name where the class is defined, at import: a name is refused once a type holding the hierarchy has been used, so the module must be imported before the first message holding an event is sent or read. Choose a name that stays when the class moves.
- A derived class with no name is refused when it is written —
MessageEncodingFailedErrorfrom the bus — rather than written as its base and read back without its fields. payloadholds JSON data as it arrived. A value of any other type, a date above all, belongs in a field of a derived class, which declares its type; inpayloadit is refused when written.- A datetime field keeps its offset; one that must keep its zone, and tell the two hours apart on
the night the clocks go back, is declared
ZonedDateTime. - What is read is untrusted: a tag no class of the hierarchy registered — an unknown name, the
name of a class of another hierarchy, no tag at all — is refused, and so is a value that does
not fit the class its tag names. On a bus that is the messenger's
MessageDecodingFailedError, which never repeats what it was handed.
Consumers
as_remote_event_consumer writes the declaration onto the class itself, so whatever gathers
consumers finds it where it finds the class — a container's scan sees it, and a test that
declares one leaves nothing behind. Stack it for a consumer serving several sources:
@as_remote_event_consumer("stripe")
@as_remote_event_consumer("stripe-test")
class PaymentConsumer:
async def consume(self, event: RemoteEvent) -> None: ...
Read it back with remote_event_consumers_declared_on(cls) from xtr_remote_event.decorator,
which returns the names in the order they were written. Only what was written on that class —
never a base's, so a subclass answers for nothing until it is decorated too.
An empty name, or a class with no consume(), is refused with InvalidArgumentError where the
declaration is written rather than when the first event arrives.
A ConsumerLocator hands consumers over by source name. Build it over consumers you already
have, or over anything implementing ServiceProviderInterface — which is what the bundle gives
it, so each consumer is built with its dependencies only when an event for it first arrives.
Asking for a source nothing is registered under raises LogicError.
Through the message bus
ConsumeRemoteEventMessage(type, event) is what turns receiving an event into consuming it:
whatever read the event answers its sender at once, and the work happens wherever the message is
routed. ConsumeRemoteEventHandler looks the consumer up and hands it the event.
from xtr_messenger import HandlersLocator, MessageBusConfig, MessageBusFactory, TransportConfig
from xtr_remote_event import ConsumerLocator
from xtr_remote_event.messenger import ConsumeRemoteEventHandler, ConsumeRemoteEventMessage
handlers = HandlersLocator()
_ = handlers.register(
ConsumeRemoteEventMessage,
ConsumeRemoteEventHandler(ConsumerLocator({"acme": AcmeConsumer()})),
)
bus = MessageBusFactory(
MessageBusConfig(
transports={"sync": TransportConfig("sync://")},
routing={ConsumeRemoteEventMessage: "sync"},
),
handlers=handlers,
).bus()
_ = await bus.dispatch(ConsumeRemoteEventMessage("acme", RemoteEvent("order.paid", "evt_1", {})))
The message's type is separate from event.name, so whatever read the event can decide which
consumer it belongs to without rewriting the event. Route the message to "sync://" to handle
it in the dispatching process, or to a broker transport to handle it on a worker; the message
carries the event rather than an id, because nothing has stored it yet — a consumer that wants
it kept is the one that stores it. The event crosses a broker as its own class — see
Events of your own.
In a wired application the bundle registers the handler, so dispatching the message never meets the bus's no-handler error.
Converting payloads
PayloadConverterInterface is where one sender's vocabulary is translated and nowhere else:
adding a sender is writing one converter rather than touching whatever dispatches events.
from collections.abc import Mapping
from xtr_remote_event import PayloadConverterInterface, RemoteEvent
from xtr_remote_event.exception import ParseError
class AcmeConverter(PayloadConverterInterface):
def convert(self, payload: Mapping[str, object]) -> RemoteEvent:
kind = payload.get("kind")
if not isinstance(kind, str):
raise ParseError('The payload has no "kind" naming the event.')
return RemoteEvent(kind, str(payload["id"]), dict(payload))
It takes the payload already decoded and is synchronous: reading the bytes, and deciding whether they are to be trusted at all, belongs to whatever received them — xtr-webhook for one.
Mailer events
Every mail provider reports what became of the messages it was handed — accepted, delivered, bounced, opened, clicked — each in its own words. Two event types give those reports the same fields whichever provider sent them, so a provider's converter builds one and a consumer of mail reports is written once:
MailerDeliveryEvent— where a message stands on its way to its recipient.nameis one of its constantsRECEIVED,DROPPED,DELIVERED,DEFERREDorBOUNCE, andreasonis the provider's explanation,""when it gave none.MailerEngagementEvent— what the recipient did with it:OPEN,CLICK,SPAMorUNSUBSCRIBE.
Both derive from AbstractMailerEvent, a RemoteEvent with four more fields, passed by
keyword: date (when the provider says it happened, and required), recipient_email,
metadata (the values the mail was sent with, as the provider hands them back) and tags.
Building AbstractMailerEvent itself raises TypeError.
from datetime import UTC, datetime
from xtr_remote_event import MailerDeliveryEvent, RemoteEvent
event: RemoteEvent = MailerDeliveryEvent(
MailerDeliveryEvent.BOUNCE,
"msg_42",
{"event": "failed", "severity": "permanent"},
date=datetime(2026, 1, 1, 9, 30, tzinfo=UTC),
recipient_email="jane@example.com",
metadata={"order_id": "7"},
tags=("receipt",),
reason="550 No such user",
)
if isinstance(event, MailerDeliveryEvent) and event.name == MailerDeliveryEvent.BOUNCE:
print(f"{event.recipient_email} bounced: {event.reason}")
They are frozen like the event they derive from, and the freeze reaches as far: it binds
metadata, not the mapping behind it.
Both are events of their own, registered as "mailer_delivery" and
"mailer_engagement": in ConsumeRemoteEventMessage on a serializing transport each comes back
of its own type, every field as it left. date is a plain datetime, so it keeps its offset
but not a zone's name, and one in the hour the clocks repeat is refused when written — give it in
UTC, as providers report it. metadata holds JSON data, as payload does.
Known limitations
- Every class registered under
RemoteEventis part of one schema. One class pydantic cannot build — a field typedDatePoint(declare itdatetime), an annotation imported only underTYPE_CHECKING— makes every message declaringRemoteEventrefused, and the error names neither the class nor the field.
Use in an application
Everything adding this package to an application on xtr-dependency-injection takes — and, read backwards, what removing it undoes.
- Install —
uv add xtr-remote-event xtr-dependency-injection: the bundle needs the container installed beside it, never as an extra. There are no extras. - Recipe —
uv run xtr-recipes recipes:syncdoes the Activate step below: it listsRemoteEventBundle. There is nothing else for it to write — no configuration module, no environment variable, no ignore line. It prints the steps to declare your consumers and to routeConsumeRemoteEventMessage, neither of which a recipe can make for you. - Activate —
RemoteEventBundle: {"all": True}inBUNDLESin<app>/config/bundles.py, imported fromxtr_remote_event.bundle. The xtr-webhook bundle requires this one, and a sync lists it whether or not webhook is installed. - Brings along — the messenger bundle, always: the handler is registered on its bus; and the serializer bundle through it, which writes the message.
- Configure — nothing.
RemoteEventConfigtakes no value, because which consumer answers for which source is declared beside the class that consumes — see Kernel / bundle. - Environment — nothing.
- Ignore — nothing.
- Remove — drop the
BUNDLESentry, thenuv remove xtr-remote-event— unless xtr-webhook is installed, which depends on it. - Check —
debug:bundlesshowsremote_eventaslistedandactive.
Kernel / bundle
With xtr-dependency-injection installed beside the package — it is
not a dependency, and nothing outside xtr_remote_event.bundle needs it — list the bundle:
# app/config/bundles.py
from xtr_remote_event.bundle import RemoteEventBundle
BUNDLES = {RemoteEventBundle: {"all": True}}
There is no config/packages/remote_event.py to write. The bundle finds every class declared with
@as_remote_event_consumer when the container is built, registers each one as a single service
— once, however many sources it declared, so what it remembers between events does not depend
on which name the event arrived under — and registers ConsumeRemoteEventHandler over a
ConsumerLocator backed by the container.
A consumer is a service like any other, so it asks for what it needs:
# app/consumer/payment_consumer.py
from xtr_remote_event import RemoteEvent
from xtr_remote_event.decorator import as_remote_event_consumer
@as_remote_event_consumer("acme")
class PaymentConsumer:
def __init__(self, orders: OrderRepository) -> None:
self._orders = orders
async def consume(self, event: RemoteEvent) -> None:
await self._orders.mark_paid(event.payload["order_id"])
Each is built — with its dependencies — only when an event for its source first arrives. To consume on a worker rather than in the process that received the event, route the message in the messenger configuration:
# app/config/packages/messenger.py
from xtr_dependency_injection import configure, env
from xtr_messenger import MessageBusConfig, TransportConfig
from xtr_remote_event.messenger import ConsumeRemoteEventMessage
@configure
def messenger() -> MessageBusConfig:
return MessageBusConfig(
transports={"events": TransportConfig(env("MESSENGER_DSN"))},
routing={ConsumeRemoteEventMessage: "events"},
)
The zero-config path registers the locator and the handler, declares no consumer and touches no I/O.
Errors
Everything this library raises derives from RemoteEventError, with one exception: the TypeError raised when AbstractMailerEvent itself is built, a programming error like building any abstract type.
| Error | Raised when |
|---|---|
InvalidArgumentError |
a value cannot be used — an empty consumer name, a class with no consume(); also a ValueError |
ParseError |
a converter cannot read a payload as an event — the sender's doing, so tell the sender |
LogicError |
nothing is registered for a source, or what is registered is not a consumer; also a RuntimeError |
TypeError |
AbstractMailerEvent itself is built — a programming error, as with any abstract type; not a RemoteEventError — "AbstractMailerEvent" is abstract: build a "MailerDeliveryEvent" or a "MailerEngagementEvent" instead. |
An event that cannot be written or read is refused by what carries it, not here: on a bus,
MessageEncodingFailedError and MessageDecodingFailedError from xtr-messenger.
Development
Developed in the python-xtr monorepo, under
packages/xtr-remote-event; run the commands below from there. The
python-xtr-remote-event 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-remote-event 6.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xtr_remote_event-6.3.0.tar.gz | 31.4 kB | With provenance | Details for xtr_remote_event-6.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xtr_remote_event-6.3.0-py3-none-any.whl | Python 3 | none | any | Details for xtr_remote_event-6.3.0-py3-none-any.whl |
Total release size: 70.4 kB
Release files / xtr_remote_event-6.3.0.tar.gz
| Download URL | xtr_remote_event-6.3.0.tar.gz |
|---|---|
| Size | 31.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e30bb09b62ba497cb349b322c699be9385ddcd4a8b7cfcfd94f53c3e377fe8a9
|
|
BLAKE2b-256 checksum How to use checksums |
393d49b0e73d4c01e4aa5aa8c3ca8abf5d2cb92cf2d0055b9fc88d855f984859
|
| 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 Nov 9, 2026.
Transparency logRelease files / xtr_remote_event-6.3.0-py3-none-any.whl
| Download URL | xtr_remote_event-6.3.0-py3-none-any.whl |
|---|---|
| Size | 39.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e77521bf1fc8ef2120f4013eb40f016a95350b1243dde16bc131486c4ea0a7e5
|
|
BLAKE2b-256 checksum How to use checksums |
b88149f292de4bfa44ec00c2f85d60841853dd5718306ce883c076205265647f
|
| 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 Nov 9, 2026.
Transparency logSecurity for xtr-remote-event 6.3.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.
Attestation for xtr_remote_event-6.3.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 Nov 9, 2026.
Transparency logA 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.