"""This is a pure-python replacement for notify-python, using python-dbus
to communicate with the notifications server directly. It's compatible with
Python 2 and 3, and its callbacks can work with Gtk 3 or Qt 4 applications.
To use it, first call ``notify2.init('app name')``, then create and show notifications::
n = notify2.Notification("Summary",
"Some body text",
"notification-message-im" # Icon name
)
n.show()
API docs are `available on ReadTheDocs <https://notify2.readthedocs.org/en/latest/>`_,
or you can refer to docstrings.
Based on the notifications spec at:
http://developer.gnome.org/notification-spec/
Porting applications from pynotify
----------------------------------
There are a few differences from pynotify you should be aware of:
- If you need callbacks from notifications, notify2 must know about your event
loop. The simplest way is to pass 'glib' or 'qt' as the ``mainloop`` parameter
to ``init``.
- The methods ``attach_to_widget`` and ``attach_to_status_icon`` are not
implemented. You can calculate the location you want the notification to
appear and call ``Notification``.
- ``set_property`` and ``get_property`` are not implemented. The summary, body
and icon are accessible as attributes of a ``Notification`` instance.
- Various methods that pynotify Notification instances got from gobject do not
exist, or only implement part of the functionality.
Several pynotify functions, especially getters and setters, are only supported
for compatibility. You are encouraged to use more direct, Pythonic alternatives.
"""
import dbus
__version__ = '0.3.1'
# Constants
EXPIRES_DEFAULT = -1
EXPIRES_NEVER = 0
URGENCY_LOW = 0
URGENCY_NORMAL = 1
URGENCY_CRITICAL = 2
urgency_levels = [URGENCY_LOW, URGENCY_NORMAL, URGENCY_CRITICAL]
# Initialise the module (following pynotify's API) -----------------------------
initted = False
appname = ""
_have_mainloop = False
class UninittedError(RuntimeError):
"""Error raised if you try to communicate with the server before calling
:func:`init`.
"""
pass
class UninittedDbusObj(object):
def __getattr__(self, name):
raise UninittedError("You must call notify2.init() before using the "
"notification features.")
dbus_iface = UninittedDbusObj()
[docs]def init(app_name, mainloop=None):
"""Initialise the D-Bus connection. Must be called before you send any
notifications, or retrieve server info or capabilities.
To get callbacks from notifications, DBus must be integrated with a mainloop.
There are three ways to achieve this:
- Set a default mainloop (dbus.set_default_main_loop) before calling init()
- Pass the mainloop parameter as a string 'glib' or 'qt' to integrate with
those mainloops. (N.B. passing 'qt' currently makes that the default dbus
mainloop, because that's the only way it seems to work.)
- Pass the mainloop parameter a DBus compatible mainloop instance, such as
dbus.mainloop.glib.DBusGMainLoop().
If you only want to display notifications, without receiving information
back from them, you can safely omit mainloop.
"""
global appname, initted, dbus_iface, _have_mainloop
if mainloop == 'glib':
from dbus.mainloop.glib import DBusGMainLoop
mainloop = DBusGMainLoop()
elif mainloop == 'qt':
from dbus.mainloop.qt import DBusQtMainLoop
# For some reason, this only works if we make it the default mainloop
# for dbus. That might make life tricky for anyone trying to juggle two
# event loops, but I can't see any way round it.
mainloop = DBusQtMainLoop(set_as_default=True)
bus = dbus.SessionBus(mainloop=mainloop)
dbus_obj = bus.get_object('org.freedesktop.Notifications',
'/org/freedesktop/Notifications')
dbus_iface = dbus.Interface(dbus_obj,
dbus_interface='org.freedesktop.Notifications')
appname = app_name
initted = True
if mainloop or dbus.get_default_main_loop():
_have_mainloop = True
dbus_iface.connect_to_signal('ActionInvoked', _action_callback)
dbus_iface.connect_to_signal('NotificationClosed', _closed_callback)
return True
def is_initted():
"""Has init() been called? Only exists for compatibility with pynotify.
"""
return initted
def get_app_name():
"""Return appname. Only exists for compatibility with pynotify.
"""
return appname
def uninit():
"""Undo what init() does."""
global initted, dbus_iface, _have_mainloop
initted = False
_have_mainloop = False
dbus_iface = UninittedDbusObj()
# Retrieve basic server information --------------------------------------------
[docs]def get_server_caps():
"""Get a list of server capabilities.
These are short strings, listed `in the spec <http://people.gnome.org/~mccann/docs/notification-spec/notification-spec-latest.html#commands>`_.
Vendors may also list extra capabilities with an 'x-' prefix, e.g. 'x-canonical-append'.
"""
return [str(x) for x in dbus_iface.GetCapabilities()]
[docs]def get_server_info():
"""Get basic information about the server.
"""
res = dbus_iface.GetServerInformation()
return {'name': str(res[0]),
'vendor': str(res[1]),
'version': str(res[2]),
'spec-version': str(res[3]),
}
# Action callbacks -------------------------------------------------------------
notifications_registry = {}
def _action_callback(nid, action):
nid, action = int(nid), str(action)
try:
n = notifications_registry[nid]
except KeyError:
#this message was created through some other program.
return
n._action_callback(action)
def _closed_callback(nid, reason):
nid, reason = int(nid), int(reason)
try:
n = notifications_registry[nid]
except KeyError:
#this message was created through some other program.
return
n._closed_callback(n)
del notifications_registry[nid]
def no_op(*args):
"""No-op function for callbacks.
"""
pass
# Controlling notifications ----------------------------------------------------
ActionsDictClass = dict # fallback for old version of Python
try:
from collections import OrderedDict
ActionsDictClass = OrderedDict
except ImportError:
pass
[docs]class Notification(object):
"""A notification object.
summary : str
The title text
message : str
The body text, if the server has the 'body' capability.
icon : str
Path to an icon image, or the name of a stock icon. Stock icons available
in Ubuntu are `listed here <https://wiki.ubuntu.com/NotificationDevelopmentGuidelines#How_do_I_get_these_slick_icons>`_.
You can also set an icon from data in your application - see
:meth:`set_icon_from_pixbuf`.
"""
id = 0
timeout = -1 # -1 = server default settings
_closed_callback = no_op
def __init__(self, summary, message='', icon=''):
self.summary = summary
self.message = message
self.icon = icon
self.hints = {}
self.actions = ActionsDictClass()
self.data = {} # Any data the user wants to attach
[docs] def show(self):
"""Ask the server to show the notification.
Call this after you have finished setting any parameters of the
notification that you want.
"""
nid = dbus_iface.Notify(appname, # app_name (spec names)
self.id, # replaces_id
self.icon, # app_icon
self.summary, # summary
self.message, # body
self._make_actions_array(), # actions
self.hints, # hints
self.timeout, # expire_timeout
)
self.id = int(nid)
if _have_mainloop:
notifications_registry[self.id] = self
return True
[docs] def update(self, summary, message="", icon=None):
"""Replace the summary and body of the notification, and optionally its
icon. You should call :meth:`show` again after this to display the
updated notification.
"""
self.summary = summary
self.message = message
if icon is not None:
self.icon = icon
[docs] def close(self):
"""Ask the server to close this notification."""
if self.id != 0:
dbus_iface.CloseNotification(self.id)
[docs] def set_hint(self, key, value):
"""n.set_hint(key, value) <--> n.hints[key] = value
See `hints in the spec <http://people.gnome.org/~mccann/docs/notification-spec/notification-spec-latest.html#hints>`_.
Only exists for compatibility with pynotify.
"""
self.hints[key] = value
set_hint_string = set_hint_int32 = set_hint_double = set_hint
[docs] def set_hint_byte(self, key, value):
"""Set a hint with a dbus byte value. The input value can be an
integer or a bytes string of length 1.
"""
self.hints[key] = dbus.Byte(value)
[docs] def set_urgency(self, level):
"""Set the urgency level to one of URGENCY_LOW, URGENCY_NORMAL or
URGENCY_CRITICAL.
"""
if level not in urgency_levels:
raise ValueError("Unknown urgency level specified", level)
self.set_hint_byte("urgency", level)
[docs] def set_category(self, category):
"""Set the 'category' hint for this notification.
See `categories in the spec <http://people.gnome.org/~mccann/docs/notification-spec/notification-spec-latest.html#categories>`_.
"""
self.hints['category'] = category
[docs] def set_timeout(self, timeout):
"""Set the display duration in milliseconds, or one of the special
values EXPIRES_DEFAULT or EXPIRES_NEVER. This is a request, which the
server might ignore.
Only exists for compatibility with pynotify; you can simply set::
n.timeout = 5000
"""
if not isinstance(timeout, int):
raise TypeError("timeout value was not int", timeout)
self.timeout = timeout
def get_timeout(self):
"""Return the timeout value for this notification.
Only exists for compatibility with pynotify; you can inspect the
timeout attribute directly.
"""
return self.timeout
[docs] def add_action(self, action, label, callback, user_data=None):
"""Add an action to the notification.
Check for the 'actions' server capability before using this.
action : str
A brief key.
label : str
The text displayed on the action button
callback : callable
A function taking at 2-3 parameters: the Notification object, the
action key and (if specified) the user_data.
user_data :
An extra argument to pass to the callback.
"""
self.actions[action] = (label, callback, user_data)
def _make_actions_array(self):
"""Make the actions array to send over DBus.
"""
arr = []
for action, (label, callback, user_data) in self.actions.items():
arr.append(action)
arr.append(label)
return arr
def _action_callback(self, action):
"""Called when the user selects an action on the notification, to
dispatch it to the relevant user-specified callback.
"""
try:
label, callback, user_data = self.actions[action]
except KeyError:
return
if user_data is None:
callback(self, action)
else:
callback(self, action, user_data)
[docs] def connect(self, event, callback):
"""Set the callback for the notification closing; the only valid value
for event is 'closed' (the parameter is kept for compatibility with pynotify).
The callback will be called with the :class:`Notification` instance.
"""
if event != 'closed':
raise ValueError("'closed' is the only valid value for event", event)
self._closed_callback = callback
def set_data(self, key, value):
"""n.set_data(key, value) <--> n.data[key] = value
Only exists for compatibility with pynotify.
"""
self.data[key] = value
def get_data(self, key):
"""n.get_data(key) <--> n.data[key]
Only exists for compatibility with pynotify.
"""
return self.data[key]
[docs] def set_icon_from_pixbuf(self, icon):
"""Set a custom icon from a GdkPixbuf.
"""
struct = (
icon.get_width(),
icon.get_height(),
icon.get_rowstride(),
icon.get_has_alpha(),
icon.get_bits_per_sample(),
icon.get_n_channels(),
dbus.ByteArray(icon.get_pixels())
)
self.hints['icon_data'] = struct
[docs] def set_location(self, x, y):
"""Set the notification location as (x, y), if the server supports it.
"""
if (not isinstance(x, int)) or (not isinstance(y, int)):
raise TypeError("x and y must both be ints", (x,y))
self.hints['x'] = x
self.hints['y'] = y