notify2 API documentation

notify2 is - or was - a package to display desktop notifications on Linux. Those are the little bubbles which tell a user about e.g. new emails.

notify2 is deprecated. Here are some alternatives:

  • desktop_notify is a newer module doing essentially the same thing.
  • If you’re writing a GTK application, you may want to use GNotification (intro, Python API).
  • For simple cases, you can run notify-send as a subprocess. The py-notifier package provides a simple Python API around this, and can also display notifications on Windows.

notify2 is a replacement for pynotify which can be used from different GUI toolkits and from programs without a GUI. The API is largely the same as that of pynotify, but some less important parts are left out.

Notifications are sent to a notification daemon over D-Bus, according to the Desktop notifications spec, and the server is responsible for displaying them to the user. So your application has limited control over when and how a notification appears.

notify2.init(app_name, mainloop=None)[source]

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.

notify2.get_server_caps()[source]

Get a list of server capabilities.

These are short strings, listed in the spec. Vendors may also list extra capabilities with an ‘x-‘ prefix, e.g. ‘x-canonical-append’.

notify2.get_server_info()[source]

Get basic information about the server.

Creating and showing notifications

class notify2.Notification(summary, message='', icon='')[source]

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. You can also set an icon from data in your application - see set_icon_from_pixbuf().
show()[source]

Ask the server to show the notification.

Call this after you have finished setting any parameters of the notification that you want.

update(summary, message='', icon=None)[source]

Replace the summary and body of the notification, and optionally its icon. You should call show() again after this to display the updated notification.

close()[source]

Ask the server to close this notification.

Extra parameters

class notify2.Notification[source]
set_urgency(level)[source]

Set the urgency level to one of URGENCY_LOW, URGENCY_NORMAL or URGENCY_CRITICAL.

set_timeout(timeout)[source]

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
set_category(category)[source]

Set the ‘category’ hint for this notification.

See categories in the spec.

set_location(x, y)[source]

Set the notification location as (x, y), if the server supports it.

set_icon_from_pixbuf(icon)[source]

Set a custom icon from a GdkPixbuf.

set_hint(key, value)[source]

n.set_hint(key, value) <–> n.hints[key] = value

See hints in the spec.

Only exists for compatibility with pynotify.

set_hint_byte(key, value)[source]

Set a hint with a dbus byte value. The input value can be an integer or a bytes string of length 1.

Callbacks

To receive callbacks, you must have set a D-Bus event loop when you called init().

class notify2.Notification[source]
connect(event, callback)[source]

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 Notification instance.

add_action(action, label, callback, user_data=None)[source]

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.

Constants

notify2.URGENCY_LOW
notify2.URGENCY_NORMAL
notify2.URGENCY_CRITICAL

Urgency levels to pass to Notification.set_urgency().

notify2.EXPIRES_DEFAULT
notify2.EXPIRES_NEVER

Special expiration times to pass to Notification.set_timeout().

Indices and tables