Recipe - Pyscript¶

Purpose¶

Call Supernotify from Pyscript python code, check what was delivered, react to notification and mobile action events, and get autocompletion for the supernotify actions in an IDE.

Implementation¶

Pyscript exposes every Home Assistant action as a python function, so supernotify.notify is called directly with the same fields as the notify action. All the fields are plain keyword arguments, however they are grouped in the Developer Tools form.

Example Code¶

Send a notification¶

@state_trigger("binary_sensor.driveway_detector == 'on'")
def driveway_alert():
    supernotify.notify(
        title="Driveway",
        message="Vehicle detected on the driveway",
        priority="high",
        apply_scenarios=["cctv", "driveway"],
        camera_entity_id="camera.driveway",
        media={"camera_ptz_preset": "driveway_entrance"},
        actions=[{"action_url_title": "Go to Camera", "action_url": "http://10.4.6.43/cameras/driveway/view"}],
    )

Check the outcome¶

Add return_response=True to get the notification back as a dictionary, including which deliveries were made. With dry_run="simulate" nothing is sent, so a script can be tried out safely.

@service
def test_driveway_alert():
    result = supernotify.notify(
        message="Vehicle detected on the driveway",
        delivery=["mobile_push", "alexa_announce"],
        dry_run="simulate",
        return_response=True,
    )
    log.info(f"Supernotify outcome: {result['outcome']}")

The enquire_* actions, such as supernotify.enquire_last_notification or supernotify.enquire_active_scenarios, only work with return_response=True.

React to notifications¶

A supernotify_notification event is fired for each notification sent, with notification_id, summary, outcome and deliveries.

@event_trigger("supernotify_notification", "outcome != 'SUCCESS'")
def notification_problem(notification_id=None, summary=None, outcome=None, **kwargs):
    log.warning(f"Notification {notification_id} ({summary}) ended as {outcome}")

Handle mobile actions¶

Mobile actions arrive as the usual Home Assistant mobile_app_notification_action event.

@event_trigger("mobile_app_notification_action", "action == 'OPEN_GATE'")
def open_gate(**kwargs):
    cover.open_cover(entity_id="cover.driveway_gate")

IDE Autocompletion¶

Pyscript can generate IDE helper stubs for all the actions in an installation, including Supernotify's. Run the pyscript.generate_stubs action, point the IDE at <config>/pyscript/modules, and import the stub at the top of a script:

from stubs.pyscript_generated import supernotify

Pyscript ignores this import at runtime. The names of the deliveries configured are included in the stub, so run pyscript.generate_stubs again after changing them.

Typed helpers¶

The stub can only describe media, delivery_control, actions, data and the responses as Any, since Home Assistant actions don't publish the shape of object fields. A typed python helper module for Pyscript, with definitions for these, could be provided if there is interest - ask for it with a feature request on GitHub Discussions.