Skip to content

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

Bases: Protocol

Names the administrators of the application, to send its own failures to.

A failed queued message, for one, is reported to them; a notifier without administrators reports it to nobody in particular.

admin_recipients property

admin_recipients: Sequence[RecipientInterface]

The administrators, in the order they were configured.

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.

send async

send(message: MessageInterface) -> SentMessage | None

Send message now and report it, or queue it and return None.

supports

supports(message: MessageInterface) -> bool

Tell whether a configured transport sends message.

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; None refuses such a notification.

  • admin_recipients (Sequence[RecipientInterface], default: () ) –

    The administrators of the application.

admin_recipients property

admin_recipients: tuple[RecipientInterface, ...]

The administrators, in the order they were given and added.

add_admin_recipient

add_admin_recipient(recipient: RecipientInterface) -> None

Add recipient to the administrators.

send async

send(notification: Notification, *recipients: RecipientInterface) -> None

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 sms with 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: Notification, *recipients: RecipientInterface) -> None

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.

send async

send(message: MessageInterface) -> SentMessage | None

Send message now and report it, or queue it and return None.

supports

supports(message: MessageInterface) -> bool

Tell whether a configured transport sends message.

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; None uses the given factories only.

from_strings

from_strings(dsns: Mapping[str, str]) -> Transports

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

from_string(dsn: str) -> TransportInterface

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

from_dsn_object(dsn: Dsn) -> TransportInterface

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.