desktop_notifier.base#

This module defines base classes for desktop notifications. All platform implementations must inherit from DesktopNotifierBase.

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

DesktopNotifierBase

Base class for desktop notifier implementations

Functions#

resource_path(package, resource)

Attributes#

desktop_notifier.base.resource_path(package, resource)[source]#
Parameters:
  • package (str) –

  • resource (str) –

Return type:

ContextManager[pathlib.Path]

desktop_notifier.base.logger[source]#
desktop_notifier.base.PYTHON_ICON_PATH[source]#
exception desktop_notifier.base.AuthorisationError[source]#

Bases: Exception

Raised when we are not authorised to send notifications

class desktop_notifier.base.Urgency[source]#

Bases: enum.Enum

Enumeration of notification levels

The interpretation and visuals will depend on the platform.

Critical = 'critical'[source]#

For critical errors.

Normal = 'normal'[source]#

Default platform notification level.

Low = 'low'[source]#

Low priority notification.

class desktop_notifier.base.Button(title, on_pressed=None)[source]#

A button for interactive notifications

Parameters:
  • title (str) – The button title.

  • on_pressed (Callable[[], Any] | None) – Callback to invoke when the button is pressed. This is called without any arguments.

class desktop_notifier.base.ReplyField(title='Reply', button_title='Send', on_replied=None)[source]#

A reply field for interactive notifications

Parameters:
  • title (str) – A title for the field itself. On macOS, this will be the title of a button to show the field.

  • button_title (str) – The title of the button to send the reply.

  • on_replied (Callable[[str], Any] | None) – Callback to invoke when the button is pressed. This is called without any arguments.

class desktop_notifier.base.Notification(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]#

A desktop notification

Parameters:
  • title (str) – Notification title.

  • message (str) – Notification message.

  • urgency (Urgency) – Notification level: low, normal or critical.

  • icon (str | None) – URI for an icon to use for the notification or icon name.

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

  • reply_field (ReplyField | None) – An optional reply field/

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

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

  • sound (bool) – Whether to play a sound when the notification is shown.

  • thread (str | None) – An identifier to group related notifications together.

  • timeout (int) – Duration for which the notification in shown.

  • attachment (str | None) –

Attachment:

URI for an attachment to the notification.

property identifier: str | int | None[source]#

An platform identifier which gets assigned to the notification after it was sent. This may be a str or int.

Return type:

str | int | None

class desktop_notifier.base.DesktopNotifierBase(app_name='Python', notification_limit=None)[source]#

Base class for desktop notifier implementations

Parameters:
  • app_name (str) – Name to identify the application in the notification center.

  • notification_limit (int | None) – Maximum number of notifications to keep in the system’s notification center.

property current_notifications: List[Notification][source]#

A list of all notifications which currently displayed in the notification center

Return type:

List[Notification]

abstract async request_authorisation()[source]#

Request authorisation to send notifications.

Returns:

Whether authorisation has been granted.

Return type:

bool

abstract async has_authorisation()[source]#

Returns whether we have authorisation to send notifications.

Return type:

bool

async send(notification)[source]#

Sends a desktop notification. Some arguments may be ignored, depending on the implementation. This is a wrapper method which mostly performs housekeeping of notifications ID and calls _send() to actually schedule the notification. Platform implementations must implement _send().

Parameters:

notification (Notification) – Notification to send.

Return type:

None

_clear_notification_from_cache(notification)[source]#

Removes the notification from our cache. Should be called by backends when the notification is closed.

Parameters:

notification (Notification) –

Return type:

None

abstract async _send(notification, notification_to_replace)[source]#

Method to send a notification via the platform. This should be implemented by subclasses.

Implementations must raise an exception when the notification could not be delivered. If the notification could be delivered but not fully as intended, e.g., because associated resources could not be loaded, implementations should emit a log message of level warning.

Parameters:
  • notification (Notification) – Notification to send.

  • notification_to_replace (Notification | None) – Notification to replace, if any.

Returns:

The platform’s ID for the scheduled notification.

Return type:

str | int

async clear(notification)[source]#

Removes the given notification from the notification center. This is a wrapper method which mostly performs housekeeping of notifications ID and calls _clear() to actually clear the notification. Platform implementations must implement _clear().

Parameters:

notification (Notification) – Notification to clear.

Return type:

None

abstract async _clear(notification)[source]#

Removes the given notification from the notification center. Should be implemented by subclasses.

Parameters:

notification (Notification) – Notification to clear.

Return type:

None

async clear_all()[source]#

Clears all notifications from the notification center. This is a wrapper method which mostly performs housekeeping of notifications ID and calls _clear_all() to actually clear the notifications. Platform implementations must implement _clear_all().

Return type:

None

abstract async _clear_all()[source]#

Clears all notifications from the notification center. Should be implemented by subclasses.

Return type:

None