desktop_notifier.main

Asynchronous desktop notification API

Classes

DesktopNotifier

Cross-platform desktop notification emitter

Module Contents

class desktop_notifier.main.DesktopNotifier(app_name='Python', app_icon=DEFAULT_ICON, notification_limit=None)

Cross-platform desktop notification emitter

Uses different backends depending on the platform version and available services. All implementations will dispatch notifications without an event loop but will require a running event loop to execute callbacks when the end user interacts with a notification. On Linux, an asyncio event loop is required. On macOS, a CFRunLoop in the main thread is required. Packages such as rubicon.objc can be used to integrate asyncio with a CFRunLoop.

Callbacks to handle user interactions with a notification can be specified either at the class level, where they take the notification identifier as input, or directly on the notification itself. The latter will take precedence if set.

Note that handlers that are directly set on the notification are tied to Python notification instance and therefore the app’s lifecycle. Handlers that are set on the class level may run also for interactions with a notification while the app was not running, if DesktopNotifier is instantiated at app startup.

Parameters:

  • app_name (str) – Name to identify the application in the notification center. On Linux, this should correspond to the application name in a desktop entry. On macOS, this argument is ignored and the app is identified by the bundle ID of the sending program (e.g., Python).

  • app_icon (desktop_notifier.common.Icon | None) – Default icon to use for notifications. This should be a desktop_notifier.base.Icon instance referencing either a file or a named system icon. str or pathlib.Path are also accepted but deprecated.

  • notification_limit (int | None)

property app_name: str

The application name

Return type:

str

property app_icon: desktop_notifier.common.Icon | None

The application icon

Return type:

desktop_notifier.common.Icon | None

async request_authorisation()

Requests authorisation to send user notifications. This will be automatically called for you when sending a notification for the first time. It also can be called manually to request authorisation in advance.

On some platforms such as macOS and iOS, a prompt will be shown to the user when this method is called for the first time. This method does nothing on platforms where user authorisation is not required.

Returns:

Whether authorisation has been granted.

Return type:

bool

async has_authorisation()

Returns whether we have authorisation to send notifications.

Return type:

bool

async send_notification(notification)

Sends a desktop notification.

This method does not raise an exception when scheduling the notification fails but logs warnings instead.

Note that even a successfully scheduled notification may not be displayed to the user, depending on their notification center settings (for instance if “do not disturb” is enabled on macOS).

Parameters:

notification (desktop_notifier.common.Notification) – The notification to send.

Returns:

An identifier for the scheduled notification.

Return type:

str

async send(title, message, urgency=Urgency.Normal, icon=None, buttons=(), reply_field=None, on_dispatched=None, on_clicked=None, on_dismissed=None, attachment=None, sound=None, thread=None, timeout=-1)

Sends a desktop notification

This is a convenience function which creates a desktop_notifier.base.Notification with the provided arguments and then calls send_notification().

Returns:

An identifier for the scheduled notification.

Parameters:
Return type:

str

async get_current_notifications()

Returns identifiers of all currently displayed notifications for this app.

Return type:

list[str]

async clear(identifier)

Removes the given notification from the notification center.

Parameters:

identifier (str) – Notification identifier.

Return type:

None

async clear_all()

Removes all currently displayed notifications for this app from the notification center.

Return type:

None

async get_capabilities()

Returns which functionality is supported by the implementation.

Return type:

frozenset[desktop_notifier.common.Capability]

property on_dispatched: Callable[[str], Any] | None

A method to call when a notification is sent to the notifications server

The method must take the notification identifier as a single argument.

If the notification itself already specifies an on_dispatched handler, it will be used instead of the class-level handler.

Return type:

Callable[[str], Any] | None

property on_clicked: Callable[[str], Any] | None

A method to call when a notification is clicked

The method must take the notification identifier as a single argument.

If the notification itself already specifies an on_clicked handler, it will be used instead of the class-level handler.

Return type:

Callable[[str], Any] | None

property on_dismissed: Callable[[str], Any] | None

A method to call when a notification is dismissed

The method must take the notification identifier as a single argument.

If the notification itself already specifies an on_dismissed handler, it will be used instead of the class-level handler.

Return type:

Callable[[str], Any] | None

property on_button_pressed: Callable[[str, str], Any] | None

A method to call when one of the notification’s buttons is clicked

The method must take the notification identifier and the button identifier as arguments.

If the notification button itself already specifies an on_pressed handler, it will be used instead of the class-level handler.

Return type:

Callable[[str, str], Any] | None

property on_replied: Callable[[str, str], Any] | None

A method to call when a user responds through the reply field of a notification

The method must take the notification identifier and input text as arguments.

If the notification’s reply field itself already specifies an on_replied handler, it will be used instead of the class-level handler.

Return type:

Callable[[str, str], Any] | None