desktop_notifier.main¶
Asynchronous desktop notification API
Classes¶
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
orpathlib.Path
are also accepted but deprecated.notification_limit (int | None)
- 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:
- async has_authorisation()¶
Returns whether we have authorisation to send notifications.
- Return type:
- 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:
- 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 callssend_notification()
.- Returns:
An identifier for the scheduled notification.
- Parameters:
title (str)
message (str)
urgency (desktop_notifier.common.Urgency)
icon (desktop_notifier.common.Icon | None)
buttons (Sequence[desktop_notifier.common.Button])
reply_field (desktop_notifier.common.ReplyField | None)
on_dispatched (Callable[[], Any] | None)
on_clicked (Callable[[], Any] | None)
on_dismissed (Callable[[], Any] | None)
attachment (desktop_notifier.common.Attachment | None)
sound (desktop_notifier.common.Sound | None)
thread (str | None)
timeout (int)
- Return type:
- async get_current_notifications()¶
Returns identifiers of all currently displayed notifications for this app.
- 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:
- 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.
- 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.