Freedesktop Notifications binds for python-sdbus

This package contains python-sdbus binds for Freedesktop notifications standard.

• Examples
  • Sending notification using blocking API
  • Sending notification using async API
  • Sending notification and waiting for user interaction

FreedesktopNotifications is the proxy automatically connects.

NotificationsInterface is the interface definition class if you want to implement your own notification daemon.

class sdbus_async.notifications.NotificationsInterface

async close_notification(notif_id)

D-Bus Method

Close notification by id.

Parameters:

notif_id (int) – Notification id to close.

Return type:

None

async get_capabilities()

D-Bus Method

Returns notification daemon capabilities.

List of capabilities:

• “action-icons” - Supports using icons instead of text for displaying actions.

• “actions” - The server will provide the specified actions to the user.

• “body” - Supports body text.

• “body-hyperlinks” - The server supports hyperlinks in the notifications.

• “body-images” - The server supports images in the notifications.

• “body-markup” - Supports markup in the body text.

• “icon-multi” - The server will render an animation of all the frames in a given image array.

• “icon-static” - Supports display of exactly 1 frame of any given image array.

• “persistence” - The server supports persistence of notifications.

• “sound” - The server supports sounds on notifications.

Returns:

List of capabilities

Return type:

List[str]

async get_server_information()

D-Bus Method

Returns notification server information.

Returns:

Tuple of server name, server vendor, version, notifications specification version

Return type:

Tuple[str, str, str, str]

async notify(app_name='', replaces_id=0, app_icon='', summary='', body='', actions=[], hints={}, expire_timeout=-1)

D-Bus Method

Create new notification.

Only summary argument is required.

Parameters:

• app_name (str) – Application that sent notification. Optional.

• replaces_id (int) – Optional notification id to replace.

• app_icon (str) – Optional application icon name.

• summary (str) – Summary of notification.

• body (str) – Optional body of notification.

• actions (List[str]) – Optional list of actions presented to user. Should be sent in pairs of strings that represent action key identifier and a localized string to be displayed to user.

• hints (Dict[str,Tuple[str,Any]]) – Extra options such as sounds that can be passed. See create_hints().

• expire_timeout (int) – Optional notification expiration timeout in milliseconds. -1 means dependent on server setting, 0 is never expire.

Returns:

New notification id.

Return type:

int

action_invoked

D-Bus signal

Python type: Tuple[int, str]

D-Bus type: us

Signal when user invokes one of the actions specified.

First element of tuple is notification id.

Second element is the key identifier of the action invoked.

notification_closed

D-Bus signal

Python type: Tuple[int, int]

D-Bus type: uu

Signal when notification is closed.

First element of the tuple is notification id.

Second element is the reason which can be:

• 1 - notification expired

• 2 - notification was dismissed by user

• 3 - notification was closed by call to close_notification()

• 4 - undefined/reserved reasons.

activation_token

D-Bus signal

Python type: Tuple[int, str]

D-Bus type: us

Signal carrying window system token.

Emitted before action_invoked.

Carries windowing system token like X11 startup id or Wayland adctivation token.

First element of tuple is notification id.

Second element is the key identifier of the action invoked.

create_hints(use_action_icons=None, category=None, desktop_entry_name=None, image_data_tuple=None, image_path=None, is_resident=None, sound_file_path=None, sound_name=None, suppress_sound=None, is_transient=None, xy_pos=None, urgency=None)

Create hints dictionary for notify().

All parameters are optional.

Parameters:

• use_action_icons (bool) – When set, a server that has the “action-icons” capability will attempt to interpret any action identifier as a named icon.

• category (str) – The type of notification. (what types there are?)

• desktop_entry_name (str) – This specifies the name of the desktop filename representing the calling program. An example would be “rhythmbox” from “rhythmbox.desktop”.

• image_data_tuple (Tuple[int,int,int,bool,int,int,Union[bytes,bytearray]]) – This is a raw data image format which describes the width, height, rowstride, has alpha, bits per sample, channels and image data respectively.

• image_path (Union[str,Path]) – Path to notification image. (alternative to desktop_entry_name)

• is_resident (bool) – When set the server will not automatically remove the notification when an action has been invoked.

• sound_file_path (Union[str,Path]) – The path to a sound file to play when the notification pops up.

• sound_name (str) – A themeable named sound to play. Similar to icon-name, only for sounds. An example would be “message-new-instant”.

• suppress_sound (bool) – Causes the server to suppress playing any sounds when this notification is displayed.

• is_transient (bool) – When set the server will treat the notification as transient and by-pass the server’s persistence capability.

• xy_pos (Tuple[int,int]) – Specifies the X and Y location on the screen that the notification should point to.

• urgency (int) – The urgency level. 0 low, 1 normal, 2 critical.

Return type:

Dict[str, Tuple[str, Any]]

class sdbus_async.notifications.FreedesktopNotifications(bus=None)

Dbus interface object path and service name is predetermined. (at 'org.freedesktop.Notifications', '/org/freedesktop/Notifications')

Parameters:

bus (SdBus) – Optional dbus connection. If not passed the default dbus will be used.