notification — Notifications on iOS

The notification module allows you to schedule notification messages that are shown in the iOS Notification Center. Scheduled notifications are delivered even when your script (or even the entire app) is no longer running.

It is also possible to attach a URL to a notification. The URL gets launched when the notification is activated (i.e. tapped in Notification Center or on the lock screen). Notifications can also contain multiple buttons that launch different URLs.

Typically, a notification is scheduled for a certain date/time in the future, but you can also schedule location-based notifications that get triggered when you enter or leave a specified geographic location (e.g. home/work).

All notifications you can schedule with this module are local notifications. Remote (push) notifications are not supported.

Functions

notification.schedule(message=None, delay=0, sound_name=None, action_url=None, title=None, subtitle=None, attachments=None, trigger=None, actions=None, identifier=None)

Schedule a notification with the given options.

The return value is a string that can be used as an identifier to e.g. cancel the notification later.

Parameters:

• message: The main text of the notification
• delay: The time when the notification gets delivered, in seconds from now
• sound_name: The name of the built-in sound effect or sound file name that should be played when the notification is delivered. You can pass None (the default) for silent notifications or ‘default’ for the default notification sound.
• action_url: The URL that gets launched when the notification is tapped
• title: The title of the notification that gets displayed above the message
• subtitle: The subtitle of the notification
• attachments: A list of files that should be attached to the notification (e.g. images) – note that these files are copied immediately, so you cannot make changes to any attachments afterwards.
• trigger: A dictionary for more complex triggers than the simple delay parameter allows (see below)
• actions: Definitions for custom action buttons that are attached to the notification. Each action can launch a different URL or script. Notification actions get shown either when you drag down a notification banner from the top of the screen, by 3D Touch (on supported devices), or by tapping and holding the notification (on devices that don’t support 3D Touch). See below for details on how to define custom actions.
• identifier: An optional string that gets used as the notification’s identifier. If a notification with the same identifier is already scheduled, it gets replaced by the new notification.

Date and location triggers:

If you need more complex notification triggers than the simple delay parameter, you can pass a dict as the trigger parameter. This trigger can contain various options that define either a calendar- or location-based notification trigger. Supported keys for calendar-based notifications are: 'repeats', 'year', 'quarter', 'month', 'day', 'weekday', 'weekday_ordinal', 'week_of_month', 'week_of_year', 'hour', 'minute', 'second' – you don’t have to specify all of these keys, just use the date/time components you need for your use case. Repeating notifications cannot repeat more often than once per minute.

Supported keys for location-based notification triggers are: 'latitude', 'longitude', 'radius' (meters, default=100), 'entry', 'exit', 'repeats'. The 'entry' (notify when reaching the location) and 'exit' (notify when leaving the location) options should be True or False. By default, both are true. Location-based notifications require that the app is authorized to access your location (you’ll be prompted automatically, and you can change it in the Settings app under Privacy).

Custom notification actions:

The actions parameter allows you to pass a list of actions that are shown as buttons when the notification is activated (e.g. by 3D Touch from the lock screen on supported devices). actions should be a list of `dict`s that may contain the following keys:

• 'title' – The title of the button
• 'url' or 'action_url' – The URL that gets launched when the button is tapped. If this is a pythonista:// URL that runs a script, the script runs in the background, unless the 'foreground' key is set to True.
• 'foreground' – See `'action_url'
• 'destructive' – Changes the button’s appearance to indicate a destructive action (the text color becomes red)
• 'text_input' – When set to True, this action causes a text field to appear within the notification interface. To use the entered text, put a {text_input} placeholder somewhere in this action’s URL (set via 'url' key). If you use a pythonista:// URL to launch a script with this action, you can use the entered text as the URL’s args parameter, and access it in the script via sys.argv. Example: pythonista3://MyScript.py?action=run&args={text_input}.
• 'text_input_button_title' – Specifies the title of the “OK” button when 'text_input' is True
• 'text_input_placeholder' – Specifies the placeholder text when 'text_input' is True

notification.cancel(identifier)

Cancel a notification that was previously scheduled.

The notification_id parameter is a string that was either retrieved via get_scheduled() or returned from the schedule() function.

notification.cancel_all()

Cancel all previously scheduled notifications.

notification.get_scheduled()

Return a list of scheduled notification identifiers.

The entries in the list are UUID strings that can be used for the cancel() function.

notification.remove_delivered(identifier)

Remove a specific notification that was already delivered from Notification Center. Note: This is done automatically when the user activates a notification.

notification.remove_all_delivered()

Remove all notifications that were already delivered from Notification Center. Note: This only affects the notifications of this app.