xtr_remote_event ¶
Events received from another system, handed to the consumer registered under their name.
An event from elsewhere — a delivery report, a payment notice, a message from a provider — is one value type here: the name of where it came from, an id, and the payload as it arrived. A consumer is registered under that name, and the event reaches it directly or through a message bus. A mail provider's reports have types of their own derived from it, carrying as fields the facts every provider reports.
ConsumerInterface ¶
Bases: Protocol
Does whatever this application does with the events of a source.
One method, returning nothing: a consumer is the end of the line, not a
step in a chain. Which sources it answers for is not its business either —
that is declared beside the class with as_remote_event_consumer, so one
consumer can serve several sources, and a source can be moved to another
consumer without either of them changing.
Async because consuming is where the work is: a row written, a mail sent, a call back to the sender.
ConsumerLocator ¶
ConsumerLocator(consumers: Mapping[str, ConsumerInterface] | ServiceProviderInterface[ConsumerInterface])
Bases: ServiceProviderInterface['ConsumerInterface']
Hands over the consumer of a source, by the name the source is known under.
Over consumers already built, or over a container's locator that builds each one — with its dependencies — when an event for it first arrives. The handler takes this rather than either, so where the consumers come from is the application's business and not the handler's.
Hand over consumers, by name.
get
async
¶
Return the consumer of the source name.
Raises:
-
LogicError–If there is none.
AbstractMailerEvent
dataclass
¶
AbstractMailerEvent(name: str, id: str, payload: dict[str, object], *, date: datetime, recipient_email: str = '', metadata: dict[str, object] = dict[str, object](), tags: tuple[str, ...] = ())
Bases: RemoteEvent
The facts every mail provider's report carries, on top of the three of any event.
Providers report the same facts under different keys and in different
shapes — a timestamp here, a date string there, the address as
recipient or as email. A payload converter reads them into these
fields once, so a consumer handles every provider's reports without knowing
which provider sent them; whatever else the provider said stays in
payload.
Abstract: a report is about either a delivery or an engagement, and this
class only holds what the two share. Building it rather than a type derived
from it raises TypeError, as building an abstract class does.
What it adds is passed by keyword, so the three inherited fields keep their
positions and a field with a default never has to come before one without.
Frozen like the base, with the same reach: the freeze binds metadata,
not the mapping behind it.
Each type derived from it registers the name it is written under, so a report crosses a message bus as its own type; this one registers none, since no value of it is ever built.
Attributes:
-
date(datetime) –When the provider says it happened, which is not when the report arrived: providers retry and batch their reports. A
datetime, written with its offset: one in a named zone comes back in that offset, and one in the hour the clocks repeat is refused when written, so give it in UTC as providers report it. -
recipient_email(str) –The address the report is about, or
""when the provider did not say. -
metadata(dict[str, object]) –The values the mail was sent with for the application's own use, as the provider hands them back — what ties a report to the application's records. JSON data, as the payload is.
-
tags(tuple[str, ...]) –The labels the mail was sent with.
MailerDeliveryEvent
dataclass
¶
MailerDeliveryEvent(name: str, id: str, payload: dict[str, object], *, date: datetime, recipient_email: str = '', metadata: dict[str, object] = dict[str, object](), tags: tuple[str, ...] = (), reason: str = '')
Bases: AbstractMailerEvent
Where a message stands on its way to its recipient, as its provider reports it.
name is one of the constants below, whatever word the provider used, so
a consumer matches on the constants and works with every provider.
Written under "mailer_delivery" wherever a field declares
:class:~xtr_remote_event.RemoteEvent, and read back as this type.
Attributes:
-
reason(str) –Why it happened, in the provider's words — the receiving server's answer to a bounce, for one — or
""when it gave none.
DROPPED
class-attribute
¶
The provider refused the message, or will not try to deliver it.
DELIVERED
class-attribute
¶
The recipient's server accepted the message.
DEFERRED
class-attribute
¶
Delivery failed for now; the provider will try again.
BOUNCE
class-attribute
¶
The recipient's server refused the message for good.
MailerEngagementEvent
dataclass
¶
MailerEngagementEvent(name: str, id: str, payload: dict[str, object], *, date: datetime, recipient_email: str = '', metadata: dict[str, object] = dict[str, object](), tags: tuple[str, ...] = ())
Bases: AbstractMailerEvent
What the recipient did with a message, as far as its provider could tell.
name is one of the constants below, whatever word the provider used, so
a consumer matches on the constants and works with every provider.
Written under "mailer_engagement" wherever a field declares
:class:~xtr_remote_event.RemoteEvent, and read back as this type.
A provider only sees what its tracking shows — an open through an image it serves, a click through a link it rewrote — so read these as signals rather than proof: a mail client that blocks images opens unseen, and a scanner that follows links clicks unasked.
UNSUBSCRIBE
class-attribute
¶
The recipient asked for no more mail.
PayloadConverterInterface ¶
Bases: Protocol
Reads one sender's payload as an event of a name and an id.
This is where a sender's vocabulary is translated and nowhere else: the name a consumer is declared under is decided here, so adding a sender is writing one converter rather than touching whatever dispatches events.
It takes the payload already decoded — reading the bytes, and deciding whether they are to be trusted at all, belongs to whatever received them — and it is synchronous, because translating a mapping reaches for nothing.
convert ¶
RemoteEvent
dataclass
¶
What arrived from elsewhere: where it came from, which event it is, and its body.
Three fields and no behaviour, on purpose. Whatever read the event has already answered the only two questions this library needs — which source this is, and which of that source's events — and everything past them differs with every sender, so it stays in the payload for the consumer that understands it.
Frozen, because an event is a record of something that already happened.
What the freeze protects is the three bindings: no consumer can point an
event it was handed at a different source, id or payload. It does not reach
into what they hold — payload is an ordinary dict — so a consumer that
writes into the payload does change the body every later consumer reads,
and nothing here prevents it. Treat the payload as read-only, and build a
value of your own from it when something has to change.
The base of a class hierarchy, so an event of a class derived from it
travels as that class wherever a field declares RemoteEvent — in a
message on a bus, above all. Each value is written with its
class's name under "$type", and read back only as a class of this
hierarchy that registered that name: this one is "remote_event". A
source worth naming gets a type of its own over the same three fields,
registered with :func:~xtr_serializer.discriminator_name where it is
defined::
@discriminator_name("payment_captured")
@dataclass(frozen=True, slots=True)
class PaymentCaptured(RemoteEvent):
amount: Decimal
A derived class without a name is refused when it is written, rather than written as this one.
Attributes:
-
name(str) –The source this came from — the name a consumer is declared under, and what decides who is handed the event.
-
id(str) –What the sender calls this event, so one arriving twice can be recognised as the same one.
-
payload(dict[str, object]) –The body as it arrived, read no further than the two fields above, and to be read rather than written: the freeze binds this field, not the dict behind it. It holds JSON data — strings, numbers, booleans,
None, lists and dicts of them; a value of any other type belongs in a field of a derived class, which declares its type.