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
None
- async close_notification(notif_id)¶
Close notification by id.
- Parameters
notif_id (int) – Notification id to close.
- Return type
None
- 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.
- Returns
List of capabilities
- Return type
List[str]
- async get_server_information()¶
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)¶
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. 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.
- Returns
New notification id.
- Return type
int
- 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.
- 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.
- Return type
None