tags: - developer - classes description: Core class descriptions for the core classes of Supernotify for Home Assistant
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 |
|---|---|
inclusion_mode | The TYPE: |
target_categories | The target categories this transport understands, independent of any delivery. TYPE: |
inclusion_mode property ¶
The inclusion an auto-configured delivery for this transport should use.
Explicit-only by default: most transports need a chat_id/channel/device_id the notification author must supply, have targets too opaque or ambiguous to map to a recipient/entity, or a channel too intrusive to fire on every notification. Override to return [INCLUSION_DEFAULT] for the few transports that can reasonably fire on every notification out of the box (e.g. email, mobile_push).
Pulled out as a separate property so can be reported in the Transport Configuration section of the Developer documentation
target_categories property ¶
The target categories this transport understands, independent of any delivery.
A plain string names a category directly (e.g. ATTR_EMAIL); an TargetEntityCategory declares that the entity_id category is accepted, but only for entities matching its domain/platform constraints. Empty by default - a transport that doesn't declare anything here relies entirely on Delivery.select_targets()'s other qualification paths (its own name, its transport's name, or a delivery's own OPTION_TARGET_CATEGORIES override), which is the deliberate design for generic, a bring-your-own-categories transport. Queried via Delivery.target_categories, not directly - a Transport never needs to know about delivery-level config, only the reverse.
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"
custom_components.supernotify.model.TransportConfig ¶
custom_components.supernotify.delivery.DeliveryRegistry ¶
| METHOD | DESCRIPTION |
|---|---|
async_refresh_entity | Re-publish one delivery or transport binary_sensor now, by its unique_id |
initialize_transport_deliveries | Validate and initialize deliveries at startup for this transport |
legacy_entities | Every registered delivery and transport binary_sensor - used by supernotify.refresh_entities. |
register_entity | Called by a delivery or transport binary_sensor's async_added_to_hass(). |
resolve_name | Backward compatibility for the original 'DEFAULT_x' auto-configured naming, |
unload_unused_transports | Drop any transport that ended up with no delivery at all - explicit or auto-generated. |
unregister_entity | Called by a delivery or transport binary_sensor's async_will_remove_from_hass(). |
| ATTRIBUTE | DESCRIPTION |
|---|---|
implicit_deliveries | Deliveries switched on all the time via implicit inclusion TYPE: |
implicit_deliveries property ¶
Deliveries switched on all the time via implicit inclusion
async_refresh_entity(unique_id) ¶
Re-publish one delivery or transport binary_sensor now, by its unique_id
initialize_transport_deliveries(context, transport) async ¶
Validate and initialize deliveries at startup for this transport
legacy_entities() ¶
Every registered delivery and transport binary_sensor - used by supernotify.refresh_entities.
register_entity(unique_id, entity) ¶
Called by a delivery or transport binary_sensor's async_added_to_hass().
resolve_name(name) ¶
Backward compatibility for the original 'DEFAULT_x' auto-configured naming, long since replaced by plain transport names: a reference to the old 'DEFAULT_x' form resolves to the current 'x' delivery, if that's what actually exists now.
unload_unused_transports() ¶
Drop any transport that ended up with no delivery at all - explicit or auto-generated.
Deliberately deferred until both initialize_transport_deliveries() (explicit) and build_standard_deliveries() (implicit) have run, rather than decided per-transport up front: whether a transport is worth having can only be known once the full, resolved set of deliveries exists - for a transport like generic (bring-your-own-action, entirely delivery-driven), there's no transport-level state to check in advance at all.
unregister_entity(unique_id) ¶
Called by a delivery or transport binary_sensor's async_will_remove_from_hass().