GioNotify

Very simple asynchronous desktop notifications with hint and actions support that does NOT depend on libnotify, pydbus, dbus-python, pynotify or any other python DBus/notifications bindings but instead uses pure PyGObject. It is intended to be as simple as possible. It uses the default timeout and each subsequent notification replaces the previous. Which should cover most casual use cases. If you require more advanced features you should look into Gio.Notification.

see notifications spec

Functions/Methods:

async_init:

async_init(app_name, callback)

Used to asynchronously initialize GioNotify.(Must be called 1st and callback must return before any other Methods are called or signals connected.)

see org.freedesktop.Notifications.GetCapabilities, org.freedesktop.Notifications.GetServerInformation and Hints

• parameters:

  • app_name - String: You application's name.(Can be an empty string.)

  • callback - Function/Method: The callback to be called once initialization has completed. A dictionary of strings of the server info and a list of strings of the server capabilities are passed to the callback.

    • Note: Use the capabilities and server info to decide what to do with hints. For example different server spec versions use slightly different hint names and different servers may support vendor specific hints.

• returns:

  • a GioNotify instance.

Example:

    self.notification = GioNotify.async_init('My App Name', self.on_init_finish)

    def on_init_finish(self, server_info, capabilities):
        print('Server information:')
        for key, value in server_info.items():
            print(key, value)
        print('\n')
        print('Server Capabilities:')
        for capability in capabilities:
            print(capability)

Output on Fedora 24 GNOME:

Server information:
spec_version 1.2
vendor GNOME
name gnome-shell
version 3.20.3

Server Capabilities:
actions
body
body-markup
icon-static
persistence
sound

sync_init:

sync_init(app_name)

Used to synchronously initialize GioNotify.(Must be called 1st before any other Methods are called or signals connected.)

• parameters:

  • app_name - String: You application's name.(Can be an empty string.)

• returns:

  • a GioNotify instance.

Example:

    try:
        self.notification = GioNotify.sync_init('My App Name')
    except Exception as e:
        self.notification = None
        print('Oh Snap!!! This went wrong: {}'.format(e))  

• Note: Useful when you need initialization to block, for example, for use in a try, except block.

show_new:

show_new(summary, body, icon)

Show a new notification. Each subsequent notification replaces the previous.

see org.freedesktop.Notifications.Notify and icons-and-images

• parameters:

  • summary - String: The title of the notification.

  • body - String: The subtitle of the notification.

  • icon - String: An icon name or URI of an image file to be displayed. Can be an empty string indicating no icon.

    • Note: The icon/image used in the notification can also be set as a hint. But it must be remembered that hints are persistent so you may want to clear/overwrite said hint unless you want to use the same image over again.

Example:

    self.notification.show_new('This is the summary.', 'This is the body.', 'dialog-information')

Example 2 , using a pixbuf as the notification icon:

• Note: An icon name or image URI is prefereed to coverting a pixbuf into raw image data. As per GdkPixbuf.Pixbuf.get_pixels "This function will cause an implicit copy of the pixbuf data if the pixbuf was created from read-only data." Also note that the 'image-data' hint name varies by spec version.

    self.new_notification('This is the summary.', 'This is the body.', self.my_awesome_pixbuf_icon)

    def new_notification(self, summary, body, pixbuf_icon):
        self.set_pixbuf_as_notification_icon(pixbuf_icon)
        self.notification.show_new(summary, body, '')

    def set_pixbuf_as_notification_icon(self, pixbuf_icon):
        raw_image_data = GLib.Variant('(iiibiiay)',   
                                      (pixbuf_icon.props.width,
                                       pixbuf_icon.props.height,
                                       pixbuf_icon.props.rowstride,
                                       pixbuf_icon.props.has_alpha,
                                       pixbuf_icon.props.bits_per_sample,
                                       pixbuf_icon.props.n_channels,
                                       pixbuf_icon.get_pixels(),
                                      ),
        )

        self.notification.set_hint('image-data', raw_image_data)

close:

close()

Manually close the notification.

see org.freedesktop.Notifications.CloseNotification

• parameters:
  • None

Example:

    self.notification.close()

add_action:

add_action(action_id, label, callback)

Adds Action Buttons to the notification if the server supports Actions.

see org.freedesktop.Notifications.GetCapabilities

• parameters:

  • action_id - String: The action_id(or icon to be displayed if the server supports action-icons).

  • label - String: To be displayed in the Action Button.

  • callback - Function/Method: Callback to be called when the Action Button is clicked.

Example:

    self.notification.add_action('media-playback-pause', 'Pause', self.pause)

clear_actions:

clear_actions()

Clears all actions. Actions are persistent across notifications. Before new actions are added the previous actions may need to be cleared.

• parameters:
  • None

Example:

    self.notification.clear_actions()

set_hint:

set_hint(key, value)

Set notification hints. Hints are persistent and generally static with the exception of the hints used to set the icon/image. For the most part they only need to be set once.

see Hints

• parameters:

  • key - String: The hint name.

  • value - GLib.Variant or None: A GLib.Variant value matching the hint name to set the hint or None to clear the hint.

Example:

    self.notification.set_hint('category', GLib.Variant('s', 'x-gnome.music'))

Properties:

capabilities:

see org.freedesktop.Notifications.GetCapabilities

• return type:

  • List: A list of strings of the server's capabilities.

Example:

    caps = self.notification.capabilities
    self.supports_action_icons = 'action-icons' in caps
    self.supports_actions = 'actions' in caps
    self.supports_body_markup = 'body-markup' in caps

server_information:

see org.freedesktop.Notifications.GetServerInformation

• return type:

  • Dict: A dict of strings containing the server's information.

Example:

    server_info = self.notification.server_information
    self.server_name = server_info['name']
    self.server_vendor = server_info['vendor']
    self.server_version = server_info['version']
    self.server_spec_version = server_info['spec_version']

Signals:

action-invoked:

see org.freedesktop.Notifications.ActionInvoked

• signal type:

  • String: The action_id of the action that was invoked.

Example:

    self.notification.connect('action-invoked', self.on_action_invoked)

    def on_action_invoked(self, obj, action_id):
        print(action_id)

closed:

see org.freedesktop.Notifications.NotificationClosed

• signal type:

  • Enum: The reason the notification was closed.

Example:

    self.notification.connect('closed', self.on_closed)

    def on_closed(self, obj, closed_reason):
        if closed_reason is GioNotify.Closed.REASON_EXPIRED:
            print('The notification expired.')
        elif closed_reason is GioNotify.Closed.REASON_DISMISSED:
            print('The notification was dismissed by the user.')
        elif closed_reason is GioNotify.Closed.REASON_CLOSEMETHOD:
            print('The notification was closed by a call to CloseNotification.')
        elif closed_reason is GioNotify.Closed.REASON_UNDEFINED:
            print('Undefined/reserved reasons.')

Or

    def on_closed(self, obj, closed_reason):
        print(closed_reason.explanation)