Skip to content

tags: - developer - classes description: Recipients and Scenario classes in Supernotify for Home Assistant

Recipients and Scenario Classes

Info

See the Class Diagram for how these relate to each other.

custom_components.supernotify.scenario.Scenario

METHOD DESCRIPTION
attributes

Return scenario attributes
contents

Archive friendly view of scenario
evaluate

Evaluate scenario conditions
trace

Trace scenario condition execution
validate

Validate Home Assistant conditiion definition at initiation
ATTRIBUTE DESCRIPTION
is_manual

A scenario with no conditions, which only applies when its manual state is on

TYPE: bool

is_manual property

A scenario with no conditions, which only applies when its manual state is on

attributes(include_condition=True, include_trace=False)

Return scenario attributes

contents(minimal=False, **_kwargs)

Archive friendly view of scenario

evaluate(condition_variables)

Evaluate scenario conditions

trace(condition_variables) async

Trace scenario condition execution

validate(valid_action_group_names=None) async

Validate Home Assistant conditiion definition at initiation

custom_components.supernotify.people.Recipient

Recipient to distinguish from the native HA Person.

The "future native entity use" this class was once staged for (BinarySensorDeviceClass, EntityCategory, etc.) has arrived as SupernotifyRecipientBinarySensor in binary_sensor.py - a wrapper Entity holding a reference to a Recipient, the same composition already used for RecipientNotifyEntity above, rather than this plain domain object inheriting from Entity.

METHOD DESCRIPTION
attributes

For exposure as entity state
disabling_delivery_names

Explicitly overriding enabled state
enabling_delivery_names

Explicitly overriding enabled state

attributes()

For exposure as entity state

disabling_delivery_names()

Explicitly overriding enabled state

enabling_delivery_names()

Explicitly overriding enabled state

custom_components.supernotify.people.RecipientNotifyEntity

Bases: NotifyEntity


              flowchart TD
              custom_components.supernotify.people.RecipientNotifyEntity[RecipientNotifyEntity]

              

              click custom_components.supernotify.people.RecipientNotifyEntity href "" "custom_components.supernotify.people.RecipientNotifyEntity"

Expose a single recipient as its own notify.recipient_<name> entity.

Sent as an ordinary target on the main supernotify action, just like any other entity - Notification recognizes it as one of supernotify's own published recipient notify entities and resolves it to this recipient, still going through the full default-recipient delivery pipeline (occupancy, scenarios, personal delivery overrides, dedupe, snooze) rather than a literal, unscoped target override. Per HA's notify entity service schema, only message/title are ever passed in here - no data/target.

METHOD DESCRIPTION
__init__

Initialize the recipient notify entity.
async_send_message

Send a message to this recipient.
record_notification

Record that this recipient was notified via supernotify.notify's main pipeline
ATTRIBUTE DESCRIPTION
extra_state_attributes

Only populated on the pre-2026.3 fallback path - see record_notification().

TYPE: dict[str, Any] | None

extra_state_attributes property

Only populated on the pre-2026.3 fallback path - see record_notification().

__init__(unique_id, recipient, engine)

Initialize the recipient notify entity.

async_send_message(message, title=None) async

Send a message to this recipient.

record_notification(context=None)

Record that this recipient was notified via supernotify.notify's main pipeline (any target - person_id, email, mobile device...), not just via a direct call to this notify.recipient_ entity. Called from Notification.record_result().

Delegates to NotifyEntity.async_record_notification() when available - the same HA-native method html5/mobile_app call on a direct notify.recipient service call - so state reflects the most recent delivery via either path. On HA versions before 2026.3 that method doesn't exist (see the docstring on self._last_notified in init), so this falls back to the pre-refactor design: a separate extra_state_attributes attribute, restored manually in async_added_to_hass() below. Either way, a message routed through supernotify.notify's main pipeline (the common case) never invokes this entity's own async_send_message() - see convert_notify_entities() in notification.py, which short-circuits that target straight to a person_id to avoid calling back into this same entity in a loop - so without this explicit call, delivery via that pipeline would never be reflected here at all.

context is the calling HA service context, if any, so the state change is attributed to the action call (or automation, or user) that caused it, in the logbook and history, just as it would be for a direct notify.recipient_ service call.

custom_components.supernotify.model.RecipientType

Bases: StrEnum


              flowchart TD
              custom_components.supernotify.model.RecipientType[RecipientType]

              

              click custom_components.supernotify.model.RecipientType href "" "custom_components.supernotify.model.RecipientType"

custom_components.supernotify.model.ConditionVariables dataclass

Variables presented to all condition evaluations

Attributes

applied_scenarios (list[str]): Scenarios that have been applied
required_scenarios (list[str]): Scenarios that must be applied
constrain_scenarios (list[str]): Only scenarios in this list, or in explicit apply_scenarios, can be applied
notification_priority (str): Priority of the notification
notification_message (str): Message of the notification
notification_title (str): Title of the notification
occupancy (list[str]): List of occupancy scenarios
notification_data (dict[str,Any]): Additional data passed on notify action call

custom_components.supernotify.people.PeopleRegistry

METHOD DESCRIPTION
async_refresh_entity

Re-publish one recipient's binary_sensor now
mobile_devices_for_person

Auto detect mobile_app targets for a person.
recipient_entities

Every registered recipient binary_sensor - used by supernotify.refresh_entities.
register_entity

Called by SupernotifyRecipientBinarySensor.async_added_to_hass().
unregister_entity

Called by SupernotifyRecipientBinarySensor.async_will_remove_from_hass().

async_refresh_entity(name)

Re-publish one recipient's binary_sensor now

mobile_devices_for_person(person_entity_id)

Auto detect mobile_app targets for a person.

Targets not currently validated as async registration may not be complete at this stage

person_entity_id (str): _description_

list: mobile target actions for this person

recipient_entities()

Every registered recipient binary_sensor - used by supernotify.refresh_entities.

register_entity(name, entity)

Called by SupernotifyRecipientBinarySensor.async_added_to_hass().

unregister_entity(name)

Called by SupernotifyRecipientBinarySensor.async_will_remove_from_hass().

custom_components.supernotify.scenario.ScenarioRegistry

METHOD DESCRIPTION
async_refresh_entity

Re-publish one scenario's binary_sensor now, whether or not periodic refresh is on
async_refresh_scenario_states

Ask each affected scenario's binary_sensor entity to re-read and re-publish its state.
register_entity

Called by SupernotifyScenarioBinarySensor.async_added_to_hass().
scenario_has_state

Whether a scenario has any state to report - anything that hasn't opted out with
scenario_is_on

is_on for SupernotifyScenarioBinarySensor - None maps to STATE_UNKNOWN.
unregister_entity

Called by SupernotifyScenarioBinarySensor.async_will_remove_from_hass().

async_refresh_entity(name)

Re-publish one scenario's binary_sensor now, whether or not periodic refresh is on

async_refresh_scenario_states(*args)

Ask each affected scenario's binary_sensor entity to re-read and re-publish its state.

Triggered by the 1-minute timer (time/date scenarios and any dependency not captured by entity extraction) and by state changes of the scenarios' condition entities (immediate reactivity). The entity's own is_on property (via scenario_is_on() above) does the actual (pure, in-memory) evaluation on read; this only decides which entities need to refresh, and is a no-op for a scenario with no entity registered yet (e.g. before the binary_sensor platform has finished loading).

register_entity(name, entity)

Called by SupernotifyScenarioBinarySensor.async_added_to_hass().

scenario_has_state(scenario)

Whether a scenario has any state to report - anything that hasn't opted out with expose_state. That is the evaluated state of its conditions if it has any, otherwise a manual state that something outside Supernotify sets, see Scenario.manual_active.

scenario_is_on(scenario)

is_on for SupernotifyScenarioBinarySensor - None maps to STATE_UNKNOWN.

unregister_entity(name)

Called by SupernotifyScenarioBinarySensor.async_will_remove_from_hass().