desktop_notifier.common¶

This module defines base classes for desktop notifications.

Attributes¶

`DEFAULT_ICON`	Python icon
`DEFAULT_SOUND`	Default system notification sound

Exceptions¶

AuthorisationError

Raised when we are not authorised to send notifications

Classes¶

`FileResource`	A file resource represented by a URI or path
`Resource`	A resource represented by a resource name, URI or path
`Icon`	An icon represented by an icon name, URI or path
`Attachment`	An attachment represented by a URI or path
`Sound`	A sound represented by a sound name, URI or path
`Urgency`	Enumeration of notification levels
`Button`	A button for interactive notifications
`ReplyField`	A text field for interactive notifications
`Notification`	A desktop notification
`Capability`	Notification capabilities that can be supported by a platform

Module Contents¶

class desktop_notifier.common.FileResource¶

A file resource represented by a URI or path

Only one of path or uri can be set.

path: pathlib.Path | None = None¶: Path to a local file

uri: str | None = None¶: URI reference to a file

as_uri()¶

Returns the represented resource as a URI string

Return type:: str

as_path()¶

Returns the represented resource as a Path

Note that any information about the URI scheme is lost on conversion.

Return type:: pathlib.Path

class desktop_notifier.common.Resource¶

Bases: FileResource

A resource represented by a resource name, URI or path

Only one of path, uri or name can be set.

name: str | None = None¶: Name of the system resource

is_named()¶

Returns whether the instance was initialized with name

Return type:: bool

is_file()¶

Returns whether the instance was initialized with path or uri

Return type:: bool

class desktop_notifier.common.Icon¶

Bases: Resource

An icon represented by an icon name, URI or path

class desktop_notifier.common.Attachment¶

Bases: FileResource

An attachment represented by a URI or path

class desktop_notifier.common.Sound¶

Bases: Resource

A sound represented by a sound name, URI or path

desktop_notifier.common.DEFAULT_ICON: Icon¶: Python icon

desktop_notifier.common.DEFAULT_SOUND: Sound¶: Default system notification sound

exception desktop_notifier.common.AuthorisationError¶

Bases: Exception

Raised when we are not authorised to send notifications

class desktop_notifier.common.Urgency¶

Bases: enum.Enum

Enumeration of notification levels

The interpretation and visuals depend on the platform.

Critical = 'critical'¶: For critical errors.

Normal = 'normal'¶: Default platform notification level.

Low = 'low'¶: Low priority notification.

class desktop_notifier.common.Button¶

A button for interactive notifications

title: str¶: The localized button title

on_pressed: Callable[[], Any] | None = None¶: Method to call when the button is pressed

identifier: str = ''¶: A unique identifier to use in callbacks to specify with button was clicked

class desktop_notifier.common.ReplyField¶

A text field for interactive notifications

title: str = 'Reply'¶: A title for the field itself. On macOS, this will be the title of a button to show the field.

button_title: str = 'Send'¶: The title of the button to send the reply

on_replied: Callable[[str], Any] | None = None¶: Method to call when the ‘reply’ button is pressed

class desktop_notifier.common.Notification¶

A desktop notification

Some properties of a notification may be ignored or interpreted differently depending on the platform.

Callbacks for interactions will be executed on the Python process that scheduled the notification and only as long as the DesktopNotifier instance that scheduled the notification still exists.

Install handlers on the DesktopNotifier instance itself to respond to interactions with notification from your app while it was not running.

title: str¶: Notification title

message: str¶: Notification message

urgency: Urgency¶: Notification urgency. Can determine stickiness, notification appearance and break through silencing.

icon: Icon | None = None¶: Icon to use for the notification

buttons: tuple[Button, Ellipsis] = ()¶: Buttons shown on an interactive notification

reply_field: ReplyField | None = None¶: Text field shown on an interactive notification. This can be used for example for messaging apps to reply directly from the notification.

on_dispatched: Callable[[], Any] | None = None¶: Method to call when the notification was sent to the notifications server for display

on_clicked: Callable[[], Any] | None = None¶: Method to call when the notification is clicked

on_dismissed: Callable[[], Any] | None = None¶: Method to call when the notification is dismissed

attachment: Attachment | None = None¶: A file attached to the notification which may be displayed as a preview

sound: Sound | None = None¶: A sound to play on notification

thread: str | None = None¶: An identifier to group related notifications together, e.g., from a chat space

timeout: int = -1¶: Duration in seconds for which the notification is shown

identifier: str = ''¶: A unique identifier for this notification. Generated automatically if not passed by the client.

class desktop_notifier.common.Capability¶

Bases: enum.Enum

Notification capabilities that can be supported by a platform

APP_NAME¶: Supports setting a custom app name

TITLE¶: Supports setting a notification title

MESSAGE¶: Supports setting a notification message

URGENCY¶: Supports different urgency levels

ICON¶: Supports custom notification icons

ICON_FILE¶: Supports setting a custom icon from a user-provided file

ICON_NAME¶: Supports setting a named system icon as notification icon

BUTTONS¶: Supports at least two notification buttons

REPLY_FIELD¶: Supports reply fields

ATTACHMENT¶: Supports notification attachments. Allowed file types vary by platform.

ON_DISPATCHED¶: Supports on-dispatched callbacks

ON_CLICKED¶: Supports on-clicked callbacks

ON_DISMISSED¶: Supports on-dismissed callbacks

SOUND¶: Supports custom notification sounds

SOUND_FILE¶: Supports setting a custom sound from a user-provided file

SOUND_NAME¶: Supports setting a named system sound as notification sound

THREAD¶: Supports grouping notifications by topic thread

TIMEOUT¶: Supports notification timeouts