Transport Classes¶
Info
See the Class Diagram for how these relate to each other.
custom_components.supernotify.transport.Transport ¶
Base class for delivery transports.
Sub classes integrste with Home Assistant notification services or alternative notification mechanisms.
| METHOD | DESCRIPTION |
|---|---|
build_standard_deliveries | Build every 'standard' (auto-generatable) delivery this transport contributes, |
deliver | Delivery implementation |
initialize | Async post-construction initialization |
is_viable | Whether this transport currently has what it needs to auto-configure a delivery. |
log_delivery_failure | Log a delivery failure, passing the exception caught in the caller's except block. |
log_delivery_recovered | Call on a successful delivery - logs once if this transport was previously |
simplify | Simplify text for delivery transports with speaking or plain text interfaces. |
validate_action | Override in subclass if transport has fixed action or doesn't require one |
| ATTRIBUTE | DESCRIPTION |
|---|---|
fallback_target_categories | Target categories this transport will claim once nothing more specific did - TYPE: |
other_target_categories | Target categories this transport understands well enough to build a full envelope TYPE: |
target_categories | The target categories this transport understands, independent of any delivery - TYPE: |
unique_target_categories | Target categories nothing else could claim - a value shape/prefix unique to this TYPE: |
fallback_target_categories property ¶
Target categories this transport will claim once nothing more specific did - e.g. notify_entity's bare notify.* domain match, after html5/alexa_devices' own platform-scoped (and therefore unique) matches on the same domain get first refusal.
Also drives implicit selection, like unique_target_categories, but ranked to lose selection-order ties to a delivery selected via a unique match (see default_selection_rank()).
other_target_categories property ¶
Target categories this transport understands well enough to build a full envelope from, but that are too ambiguous to drive auto-selection on their own - several transports competing for the same bare entity domain (media_player, matched by kodi/tts/the media transport/alexa_media_player/chime), where an entity alone doesn't say which one of them was actually meant.
target_categories property ¶
The target categories this transport understands, independent of any delivery - the union of unique_target_categories, fallback_target_categories and other_target_categories, for envelope-building (Delivery.target_categories/ Delivery.select_targets()). Selection itself only ever looks at the first two.
unique_target_categories property ¶
Target categories nothing else could claim - a value shape/prefix unique to this transport (e.g. ATTR_EMAIL), or an entity domain+platform combination unique to it.
This is what drives implicit selection (Notification.select_deliveries()): a delivery whose transport declares one of these, and whose category is actually present in the notification's target or an available recipient's own capabilities, becomes an auto-selection candidate - the same way giving an email address has always implied the email delivery. Empty by default; a transport with nothing here is never implicitly selected on its own, only by an explicit call/scenario/recipient ask.
build_standard_deliveries(hass_api) ¶
Build every 'standard' (auto-generatable) delivery this transport contributes, keyed by name: its own default (keyed by self.name) plus any extras.
Only ever called once is_viable() has returned True for the same hass_api - callers must check that first. Most overrides trust this and skip re-checking their own viability condition; the exception is a transport whose viability can only be discovered by doing the very lookup this method needs anyway (see is_viable()'s docstring) - those keep their own guard and still return an empty dict, simply because there's nothing to gain by trusting the caller there.
deliver(envelope, debug_trace=None) abstractmethod async ¶
Delivery implementation
envelope (Envelope): envelope to be delivered
debug_trace (DebugTrace): debug info collector
initialize() async ¶
Async post-construction initialization
is_viable(hass_api) ¶
Whether this transport currently has what it needs to auto-configure a delivery.
Default implementation just defers to build_standard_deliveries() and checks for a non-empty result - correct for any transport, but builds (and discards) the DeliveryConfigs to answer what's otherwise a yes/no question. Override with a standalone check (matching build_standard_deliveries()'s own condition) in a transport where that's cheap and doesn't require mutating self.delivery_defaults to find out - most transports that gate purely on hass_api state (a config entry, a registered service, discovered entities) can. Skip the override where viability can only be discovered by doing the same service/entity lookup build_standard_deliveries() itself needs to build the config (e.g. discord, pushover, sms - discovering which service is available - or email, which also decides how to send based on what's found).
log_delivery_failure(err, message, *args) ¶
Log a delivery failure, passing the exception caught in the caller's except block.
Logged at ERROR (with traceback) the first time this transport becomes unavailable, then downgraded to DEBUG for consecutive failures until it recovers - avoids spamming the log every notification while an external service/device stays down. Call alongside record_error(), which keeps tracking the lifetime error count regardless of log level.
log_delivery_recovered() ¶
Call on a successful delivery - logs once if this transport was previously flagged unavailable, then clears the flag.
simplify(text, strip_urls=False) ¶
Simplify text for delivery transports with speaking or plain text interfaces.
Spoken transports can be handed SSML, which the voice assistant parses itself. Simplification removes angle brackets, so applying it to SSML turns the markup into words the assistant reads out loud. When a spoken transport is given SSML, the tags are left alone and only the text around them is simplified, so emoji, URLs and symbols are still cleaned up.
validate_action(action) ¶
Override in subclass if transport has fixed action or doesn't require one
custom_components.supernotify.model.DeliveryConfig ¶
custom_components.supernotify.model.DeliveryCustomization ¶
custom_components.supernotify.delivery.DeliveryProvenance ¶
Bases: StrEnum
flowchart TD
custom_components.supernotify.delivery.DeliveryProvenance[DeliveryProvenance]
click custom_components.supernotify.delivery.DeliveryProvenance href "" "custom_components.supernotify.delivery.DeliveryProvenance"