desktop_notifier.main

This module handles desktop notifications and supports multiple backends, depending on the platform.

Module Contents

Classes

Urgency	Enumeration of notification levels
Button	A button for interactive notifications
ReplyField	A reply field for interactive notifications
Notification	A desktop notification
DesktopNotifier	Cross-platform desktop notification emitter

class desktop_notifier.main.DesktopNotifier(app_name='Python', app_icon=PYTHON_ICON_PATH, 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, a 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.

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 (pathlib.Path | str | None) – Default icon to use for notifications. This should be either a URI string, a pathlib.Path path, or a name in a freedesktop.org-compliant icon theme. If None, the icon of the calling application will be used if it can be determined. On macOS, this argument is ignored and the app icon is identified by the bundle ID of the sending program (e.g., Python).

• notification_limit (int | None) – Maximum number of notifications to keep in the system’s notification center. This may be ignored by some implementations.

property app_name: str

The application name

Return type:

str

property current_notifications: List[desktop_notifier.base.Notification]

A list of all currently displayed notifications for this app

Return type:

List[desktop_notifier.base.Notification]

app_icon: str | None

_run_coro_sync(coro)

Runs the given coroutine and returns the result synchronously. This is used as a wrapper to conveniently convert the async API calls to synchronous ones.

Parameters:

coro (Coroutine[None, None, T]) –

Return type:

T

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 takes a fully constructed Notification instance as input. Use send() to provide separate notification properties such as title, message, etc., instead.

Parameters:

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

Return type:

desktop_notifier.base.Notification

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

Sends a desktop notification.

Some arguments may be ignored, depending on the backend.

This method will always return a base.Notification instance and will not raise an exception when scheduling the notification fails. If the notification was scheduled successfully, its identifier will be set to the platform’s native notification identifier. Otherwise, the identifier will be None.

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:

• title (str) – Notification title.

• message (str) – Notification message.

• urgency (desktop_notifier.base.Urgency) – Notification level: low, normal or critical. This may be interpreted differently by some implementations, for instance causing the notification to remain visible for longer, or may be ignored.

• icon (pathlib.Path | str | None) – Optional URI string, pathlib.Path or icon name to use. If given, this will replace the icon specified by app_icon. Will be ignored on macOS.

• buttons (Sequence[desktop_notifier.base.Button]) – A list of buttons with callbacks for the notification.

• reply_field (desktop_notifier.base.ReplyField | None) – Optional reply field to show with the notification. Can be used for instance in chat apps.

• on_clicked (Callable[[], Any] | None) – Optional callback to call when the notification is clicked. The callback will be called without any arguments. This is ignored by some implementations.

• on_dismissed (Callable[[], Any] | None) – Optional callback to call when the notification is dismissed. The callback will be called without any arguments. This is ignored by some implementations.

• attachment (pathlib.Path | str | None) – Optional URI string or pathlib.Path for an attachment to the notification such as an image, movie, or audio file. A preview of this may be displayed together with the notification. Different platforms and Linux notification servers support different types of attachments. Please consult the platform support section of the documentation.

• sound (bool) – Whether to play a sound when the notification is shown. The platform’s default sound will be used, where available.

• thread (str | None) – An identifier to group related notifications together. This is ignored on Linux.

• timeout (int) – The duration (in seconds) for which the notification is shown unless dismissed. Only supported on Linux. Default is -1 which implies OS-specified.

Returns:

The scheduled notification instance.

Return type:

desktop_notifier.base.Notification

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

Synchronous call of send(), for use without an asyncio event loop.

Returns:

The scheduled notification instance.

Parameters:

• title (str) –

• message (str) –

• urgency (desktop_notifier.base.Urgency) –

• icon (pathlib.Path | str | None) –

• buttons (Sequence[desktop_notifier.base.Button]) –

• reply_field (desktop_notifier.base.ReplyField | None) –

• on_clicked (Callable[[], Any] | None) –

• on_dismissed (Callable[[], Any] | None) –

• attachment (pathlib.Path | str | None) –

• sound (bool) –

• thread (str | None) –

• timeout (int) –

Return type:

desktop_notifier.base.Notification

async clear(notification)

Removes the given notification from the notification center.

Parameters:

notification (desktop_notifier.base.Notification) – Notification to clear.

Return type:

None

async clear_all()

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

Return type:

None