xtr_notifier ¶
Notifications sent to chat, SMS and push channels.
A notification says what happened and how much it matters. The notifier picks the channels it goes to — from the notification itself or from a policy keyed by its importance — and each channel hands a message to a transport configured by DSN, or to a message bus.
AdminRecipientsProviderInterface ¶
Chatter ¶
Chatter(transport: TransportInterface, message_bus: MessageBusInterface | None = None, event_dispatcher: EventDispatcherInterface | None = None)
Bases: MessageSender, ChatterInterface
Sends chat messages through the chat transports, or queues them on a message bus.
Chatter(transport) sends at once; Chatter(transport, message_bus)
dispatches each message to the bus, whose handler sends it later.
ChatterInterface ¶
Bases: Protocol
Sends a chat message the application built itself — or queues it for later.
Use it when the message, not a notification, is what the code has: a reply in a thread, a message with provider options. A notification goes through the notifier instead, which picks the channels.
Notifier ¶
Notifier(channels: Mapping[str, ChannelInterface] | ServiceProviderInterface[ChannelInterface], channel_policy: ChannelPolicyInterface | None = None, admin_recipients: Sequence[RecipientInterface] = ())
Bases: NotifierInterface, AdminRecipientsProviderInterface
Sends each notification to each recipient, on the channels it calls for.
The channels come from the notification — get_channels(recipient) —
or, when it names none, from the channel policy for its importance. A
channel name may carry a transport after a slash: "chat/slack" sends on
the chat channel through the slack transport.
Every channel of a recipient is checked — it exists, it can reach the recipient — before any of them is sent on, so a misconfigured notification fails whole rather than half sent.
The channels are looked up by name, in a mapping or in a
:class:~xtr_service_contracts.ServiceProviderInterface — a container's
locator, which builds only the channels a notification uses.
Send on channels, picked by channel_policy when a notification names none.
Parameters:
-
channels(Mapping[str, ChannelInterface] | ServiceProviderInterface[ChannelInterface]) –The channels, by name (
"chat","sms","push"). -
channel_policy(ChannelPolicyInterface | None, default:None) –What picks the channels of a notification that names none;
Nonerefuses such a notification. -
admin_recipients(Sequence[RecipientInterface], default:()) –The administrators of the application.
admin_recipients
property
¶
The administrators, in the order they were given and added.
add_admin_recipient ¶
Add recipient to the administrators.
send
async
¶
Send notification to each of recipients, or to nobody in particular.
Raises:
-
LogicError–If the channels cannot be determined, or one does not exist, cannot reach the recipient, or is
smswith no recipient. -
InvalidArgumentError–If the channel policy defines nothing for the notification's importance.
NotifierInterface ¶
Bases: Protocol
Sends a notification to its recipients, on the channels it calls for.
send
async
¶
Send notification to each of recipients — to nobody in particular when none.
Implementations raise :class:~xtr_notifier.exception.LogicError when a
channel cannot be determined, does not exist, or cannot reach a recipient.
Texter ¶
Texter(transport: TransportInterface, message_bus: MessageBusInterface | None = None, event_dispatcher: EventDispatcherInterface | None = None)
Bases: MessageSender, TexterInterface
Sends SMS and push messages through the texter transports, or queues them on a bus.
Texter(transport) sends at once; Texter(transport, message_bus)
dispatches each message to the bus, whose handler sends it later.
TexterInterface ¶
Bases: Protocol
Sends an SMS or a push message the application built itself — or queues it.
Use it when the message, not a notification, is what the code has: a one-time code to a phone number, a push with provider options. A notification goes through the notifier instead, which picks the channels.
Transport ¶
Transport(factories: Iterable[TransportFactoryInterface] = (), discovery: TransportFactoryDiscovery | None = None)
Turns DSN strings into transports, through the factories serving their schemes.
One DSN builds one transport; DSNs joined by || build a
:class:FailoverTransport, and by && a :class:RoundRobinTransport::
transport = Transport(
discovery=TransportFactoryDiscovery(
TransportFactoryDiscovery.CHATTER_GROUP, http_client=client
)
).from_string("slack://TOKEN@default?channel=ops || telegram://TOKEN@default")
A scheme is looked up in the factories given first, in order, then among those the discovery finds installed. A chatter and a texter each have a builder of their own, over their own group, so a chat provider never serves the texter's DSNs.
Build through factories, then through the ones discovery finds.
Parameters:
-
factories(Iterable[TransportFactoryInterface], default:()) –Factories tried first, in order — an application's own, or a provider's that needs more than discovery hands it.
-
discovery(TransportFactoryDiscovery | None, default:None) –Where to look for a scheme no factory given serves;
Noneuses the given factories only.
from_strings ¶
Build a transport per named DSN, picked per message by name.
Raises:
-
InvalidArgumentError–If a DSN cannot be read.
-
UnsupportedSchemeError–If no factory serves a DSN's scheme.
from_string ¶
Build the transport dsn describes — one, a failover, or a round robin.
Raises:
-
InvalidArgumentError–If a DSN cannot be read.
-
UnsupportedSchemeError–If no factory serves a DSN's scheme.
from_dsn_object ¶
Build the transport a parsed dsn describes.
Raises:
-
UnsupportedSchemeError–If no factory serves the scheme. It names the provider library to install when the scheme is a known one.