1. Pure Python code base without compiled extension modules. Plyer is the only library which fulfilled this requirement.
2. Ability to show buttons and react to user interactions. This requires integration with an event loop such as asyncio, the Glib main loop or Core Foundation’s CFRunLoop. To my knowledge, none of the existing Python libraries supports this.
3. Ability to manage and remove already sent notifications.
4. Use up-to-date platform APIs: All of the Python libraries currently use the deprecated NSUserNotificationCenter API on macOS.

I therefore ended up writing my own module and eventually spun it off as a separate library desktop-notifier. This post gives a brief introduction to native platforms APIs and the choices which I had to make when writing an abstraction layer.

Platform APIs

Let’s start with introducing the different platforms to see what we’ll need to work with.

Linux

Most Linux desktop environments, including Gnome and KDE, implement the Desktop Notifications Specification. It defines a basic DBus API to send desktop notifications and all implementations must support basic features such as showing an app icon, a title and a message. Anything beyond that, notably buttons (or “actions” in the language of the spec) may or may not be supported with varying limitations. The documentation is riddled with statements such as

Clients should try and avoid making assumptions about the presentation and abilities of the notification server.

At least we have a single, convenient API to work with and an easy way to query the capabilities of a notification server. Python also has several DBus libraries that integrate with common event loops and some don’t even require compiled extension modules.

Many Python packages which don’t want to use the DBus API directly instead rely on the notify-send command line tool, available with most distributions. Since this requires calling an external executable, it is not possible to listen to DBus signals and react to user interactions with the notification when using notify-send.

macOS

The macOS API has been transitioning over the past few releases from the now deprecated NSUserNotificationCenter to the more modern UNUserNotificationCenter library.

The former was introduced in OS X Mountain Lion and is currently still available in macOS 11. The latter is available on both macOS and iOS and introduces new capabilities such as an unlimited number of buttons, previews of notification attachments and providing completely custom views. You can therefore show almost any user interface inside a desktop notification, for instance a full game of Flappy Bird 🐥

Because both iOS and macOS give users fine-grained control over which apps are allowed to send which types of desktop notifications, only signed app bundles or frameworks can send notifications. This prevents a (potentially compromised) app from impersonating any other app or circumventing the user’s settings.

This introduces some difficulties when sending notifications from a Python interpreter. In practice, the UNUserNotificationCenter API can only be used from a signed framework build of Python, as available from python.org, but not from a regular build as provided for instance by Homebrew. In addition, notifications will always appear to come from “Python” unless the module has been bundled and distributed as a standalone app.

The UNUserNotificationCenter library can be accessed via ctypes or more conveniently by using a Python to Objective-C bridge such as PyObjC or Rubicon Objective-C.

Windows

Windows, with its history of different GUI libraries, is a bit more complicated. Good old win32 provides the Shell_NotifyIconW API which can accessed over FFI / ctypes and can even show modern “toast” notifications on Windows 10. It is however limited to just showing an icon, a title and a message. Popular Python packages such as win10toast use this approach.

Richer features such as image previews, interactive buttons, etc, are currently only available through the Windows Runtime APIs which can only be access using pre-compiled Python packages such as Python/WinRT.

Python implementation

Dealing with those very different native APIs, I was faced with a number of choices for the abstraction layer:

Sync vs async

On the surface, this seems like an easy choice. A synchronous API can be called from any function and does not require spinning an event loop. It is therefore more convenient to the user of the library. When looking at the problem more closely, through, many native API are actually asynchronous. This certainly holds for the DBus API. UNUnserNotificationCenter similarly exposes mostly asynchronous methods that take a callable “completion handler” as an argument which will be called with a result after the async call has completed (e.g., after the notification has been scheduled). In addition, dealing with user interactions requires spinning an event loop anyways. An asynchronous API is therefore the more natural choice.

Supported features

We have seen previously that the available features vary significantly between platforms, desktop environments and different APIs on the same platform. Do we want to support only the smallest common denominator of features? Or can we live with a “leaky” abstraction which exposes features that might not work on some platforms? And how do we handle unsupported options?

I decided to live with a leaky abstraction and to ignore any provided arguments such as buttons, custom icons or sounds, when not supported by a platform. Instead of raising an exception, we will only emit a warning.

An overview of supported features in the desktop-notifier library is given here.

Event loop intgeration

We know that some form of event loop integration will be necessary to handle user interaction. Do we want to integrate directly with platform-native event loops such Apple’s CFRunLoop on or the GLib main loop in Gtk?

I opted for the easier but less convenient solution of only supporting Python’s asyncio event loop. Users can then choose to integrate the asyncio event loop directly with native event loops themselves if required. On macOS or iOS, this can be done using Rubicon Objective-C:

import asyncio
from rubicon.objc.eventloop import EventLoopPolicy

# Install the event loop policy
asyncio.set_event_loop_policy(EventLoopPolicy())

Integration with the Glib main loop can be done using asyncio-glib:

import asyncio
import asyncio_glib

# Install the event loop policy
asyncio.set_event_loop_policy(asyncio_glib.GLibEventLoopPolicy())

Native bridges

I chose python-dbus-next as a DBus library because of the excellent asyncio integration and because of pure Python 3 code base.

Similarly, I opted for Rubicon Objective-C as a bridge to Objective-C because it written purely in Python and because it is much more convenient than using ctypes directly.

desktop-notifier currently does not support Windows, partially because I am still undecided whether to rely on extension modules or just use ctypes and sacrifice functionality. However, an implementation using Python/WinRT is currently in development.

Example usage

The final library with all of its features and limitations is documented here. It enables you to send a simple desktop notification with buttons, a reply field and callbacks with just a few lines of code:

The above examples uses the following code:

import asyncio
import platform
from desktop_notifier import DesktopNotifier, Button, ReplyField


notifier = DesktopNotifier()


async def main():

    await notifier.send(
        title="Julius Caesar",
        message="Et tu, Brute?",
        buttons=[
            Button(
                title="Mark as read",
                on_pressed=lambda: print("Marked as read"),
            ),
        ],
        reply_field=ReplyField(
            title="Reply",
            button_title="Send",
            on_replied=lambda text: print("Brutus replied:", text),
        ),
        on_clicked=lambda: print("Opening chat app"),
    )


if platform.system() == "Darwin":

    # Integrate with CFRunLoop.
    from rubicon.objc.eventloop import EventLoopPolicy

    asyncio.set_event_loop_policy(EventLoopPolicy())


# Schedule main function and run event loop.
loop = asyncio.get_event_loop()
loop.create_task(main())
loop.run_forever()

If you like the approach taken by this library and would like to help with developing the Windows backend, do get in touch!

Maestral uses click, which is part of the pallets project, to generate its command line interface (CLI). Click makes it easy to create nested commands, generates well-formatted help pages, and supports lazy loading of subcommands at runtime. It also provides a few utilities for interactive command line tools such as basic prompts and progress bars.

For a sync client, it is sometimes convenient to allow for more complex inputs. The selective sync dialog for instance provides a list of folders which checkboxes to include or exclude them from syncing:

This dialog is shown both when setting up a new account and on-demand from the settings pane.

Such a “multiple selection” interface is more difficult to achieve in the command line. Before version 1.3.0, we would iterate over all top level folders and prompt the user whether to include each of them individually. This could quickly become a very tedious task for a large number of top-level folders.

Wouldn’t it be much nicer to provide a similar interface as the GUI does, with a scrollable list of folders and checkboxes?

Choose which folders to include  [move: ↑↓ | pick: → | unpick: ←]
  [ ] Invoices
> [x] Refurbishing project
  [x] Summer 2018 pictures
  [x] Summer 2019 pictures

This is rhetoric question, of course it would! This example demonstrates that interactive prompts are more than a fancy gimmick. They can enable entirely new types of user interfaces in the command line and vastly simplify the user interaction.

Implementing this from scratch would be well beyond the scope of this project but it turns out that there are already a number of Python libraries which do exactly that. I’ll give a brief overview over the main choices here and explain why I decided to use survey, an arguably lesser known option.

Prompt Toolkit

Prompt Toolkit is the Python standard for interactive command line tools. It is battle-tested, powerful, versatile and supports a wide range of platforms. It can be used to build entire interactive consoles and is used for instance for the well known IPython console. The authors advertise that it is lightweight and this is certainly true for the provided feature set.

Because Prompt Toolkit is a general purpose library, it would still require a lot of work to write the actual prompts needed for our CLI. Furthermore, despite its small size for the provided feature set, it does require at least 10 MB of memory at runtime.

PyInquirer

PyInquirer is based on Prompt Toolkit and provides common prompts needed for Maestral out-of-the-box. It makes a few questionable style choices by default but those are a matter of taste and can be customised. Its major downside for adoption by Maestral is again the “large” Prompt Toolkit dependency.

Bullet

With 0.7 MB of memory usage at runtime, bullet is properly lightweight for our purposes. Its claim of providing “beautiful” prompts is questionable but this can again be customised. However, at the time of writing, it only accepts ASCII input. This blocks its adaption by Maestral which regularly deals with file names that contain non-ASCII characters.

Survey

After almost giving up on the convenience of interactive dialogs, I came across survey. Survey is closely modelled after the similarly named GoLang library that is used for instance in the excellent GitHub command line tool.

Here is an example of a prompt with default styling:

This will look very familiar to you if you have been using Maestral’s CLI, we practially do not apply any custom styling to the excellent defaults.

Survey also qualifies as lightweight. It does import Python’s relatively heavy asyncio module. However, because Maestral imports asyncio independently anyways, the total memory usage increases only by 0.5 MB.

Maestral uses interactive prompts for other commands beside the setup dialog. For instance, the diff and restore commands can both provide a list of past file versions when no version number is given as an argument. Those lists are fetched from Dropbox servers on-demand. The same workflow previously required two commands: First fetch all revisions numbers for a file with the history command and then pass a revision number as an argument to diff or restore. Having interactive dialogs enables us to remove the first step.

Have a look at the documentation to see what is possible with Survey and try it out if you like what you see!

The next blog post will cover Python libraries to send desktop notifications, another rabbit-hole of popular packages which don’t quite do the job…