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[di]" # + the bundle
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.
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.
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.
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[di]". There are no other 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>/bundles.py, imported fromxtr_remote_event.bundle— or nothing to do when xtr-webhook's bundle is listed, which requires this one. - Brings along — the messenger bundle, always: the handler is registered on its bus.
- 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
# app/bundles.py
from xtr_remote_event.bundle import RemoteEventBundle
BUNDLES = {RemoteEventBundle: {"all": True}}
There is no config/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/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.
| 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 |
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 4.0.3
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-4.0.3.tar.gz | 20.9 kB | With provenance | Details for xtr_remote_event-4.0.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xtr_remote_event-4.0.3-py3-none-any.whl | Python 3 | none | any | Details for xtr_remote_event-4.0.3-py3-none-any.whl |
Total release size: 50.3 kB
Release files / xtr_remote_event-4.0.3.tar.gz
| Download URL | xtr_remote_event-4.0.3.tar.gz |
|---|---|
| Size | 20.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5ff3886ea33d914982471de2f1c32f692d0b04a713e5933cd7368d89d900d6b2
|
|
BLAKE2b-256 checksum How to use checksums |
ede3ccef23758614c59a6229fdcbaa07a8d6357876bdc0e14d4db09b5c2ebb20
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 15, 2026.
Transparency logRelease files / xtr_remote_event-4.0.3-py3-none-any.whl
| Download URL | xtr_remote_event-4.0.3-py3-none-any.whl |
|---|---|
| Size | 29.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d86507791a0eaba9e6155445e00865907a2fcd8d4cb568f48dc7f232ca794c21
|
|
BLAKE2b-256 checksum How to use checksums |
e32dcbb934ba11daf27ee4ddd33a298a9a8ee7ee503c2d836b2c1d8ddf8db0d2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 15, 2026.
Transparency logSecurity for xtr-remote-event 4.0.3
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-4.0.3.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 15, 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.