Freedesktop Notifications binds for python-sdbus

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

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
Return type


async close_notification(notif_id)

Close notification by id.


notif_id (int) – Notification id to close.

Return type


async get_capabilities()

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.


List of capabilities

Return type


async get_server_information()

Returns notification server information.


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)

Create new notification.

Only summary argument is required.

  • 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. List index becomes action id.

  • 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.


New notification id.

Return type


action_invoked: Tuple[int, int]

D-Bus signal

Signal when user invokes one of the actions specified.

First element of tuple is notification id.

Second element is the index of the action invoked. Matches the index of passed list of actions.

notification_closed: Tuple[int, int]

D-Bus signal

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.

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.

  • 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')


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

Return type