desktop_notifier.main
#
This module handles desktop notifications and supports multiple backends, depending on the platform.
Module Contents#
Classes#
|
Enumeration of notification levels |
|
A button for interactive notifications |
|
A reply field for interactive notifications |
|
A desktop notification |
Cross-platform desktop notification emitter |
- class desktop_notifier.main.DesktopNotifier(app_name='Python', app_icon=PYTHON_ICON_PATH, notification_limit=None)[source]#
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 current_notifications: List[desktop_notifier.base.Notification][source]#
A list of all currently displayed notifications for this app
- Return type:
- _run_coro_sync(coro)[source]#
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()[source]#
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()[source]#
Returns whether we have authorisation to send notifications.
- Return type:
- async send_notification(notification)[source]#
Sends a desktop notification.
This method takes a fully constructed
Notification
instance as input. Usesend()
to provide separate notification properties such astitle
,message
, etc., instead.- Parameters:
notification (desktop_notifier.base.Notification) – The notification to send.
- Return type:
- 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)[source]#
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, itsidentifier
will be set to the platform’s native notification identifier. Otherwise, theidentifier
will beNone
.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 byapp_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:
- 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)[source]#
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:
- async clear(notification)[source]#
Removes the given notification from the notification center.
- Parameters:
notification (desktop_notifier.base.Notification) – Notification to clear.
- Return type:
None