Python library for cross-platform desktop notifications
Project description
Desktop Notifier
desktop-notifier
is a Python library for cross-platform desktop notifications.
Currently supported platforms are:
- Linux via the dbus service org.freedesktop.Notifications
- macOS via the Notification Center framework
Features
- Clickable notifications (requires platform support)
- Notifications with buttons (requires platform support)
- Asyncio integration to execute callbacks on user interaction
- Limit maximum number of notification shown in the notification history
- Pure Python dependencies only, no extension modules
Installation
From PyPI:
pip3 install -U desktop-notifier
Usage
Basic usage only requires the user to specify a notification title and message:
from desktop_notifier import DesktopNotifier
notifier = DesktopNotifier()
notifier.send(title="Hello world!", message="Notification body")
By default, "Python" will be used as the app name for all notification. Advanced usage allows specifying the app name, notification urgency, app icon, buttons and callbacks:
from desktop_notifier import DesktopNotifier, NotificationLevel
notifier = DesktopNotifier(app_name="Sample App", notification_limit=10)
notifier.send(
title="Hello from Python!",
message="A horrible exception occured",
urgency=NotificationLevel.Critical,
icon="/path/to/icon.png",
action=lambda: print("notification clicked"),
buttons={
"Button 1": lambda: print("Button 1 clicked"),
"Button 2": lambda: print("Button 2 clicked")
},
)
Note that some platforms may not support all options. For instance, some Linux Desktop environments may not support notifications with buttons. On macOS, the app icon and name are always set to the application which calls the code. This will be Python when used interactively or any app name when run from a frozen and signed app bundle. Any options or configurations which are not supported by the platform will be silently ignored.
Execution of callbacks requires a running event loop. On Linux, it requires a running asyncio loop and on macOS it requires a running CFRunLoop. You can use rubicon-objc to integrate a Core Foundation CFRunLoop with asyncio:
import asyncio
from rubicon.objc.eventloop import EventLoopPolicy
# Install the event loop policy
asyncio.set_event_loop_policy(EventLoopPolicy())
# Get an event loop, and run it!
loop = asyncio.get_event_loop()
loop.run_forever()
Full documentation can be found at https://rubicon-objc.readthedocs.io/en/latest/how-to/async.html.
Notes on macOS
On macOS 10.14 and higher, the implementation uses the UNUserNotificationCenter
instead of the deprecated NSUserNotificationCenter
. UNUserNotificationCenter
restricts sending desktop notifications to signed frameworks or app bundles. This means
that notifications will only work if Python has been installed as a Framework and
properly signed. This is the case when using the installer from python.org but not for
homebrew installations.
If you are planning to use this library in an app bundle, you must sign the app bundle to send notifications, either with an Apple Developer certificate or ad-hoc for local usage.
Requirements
- macOS 10.13 or higher
- Linux desktop environment providing a dbus desktop notifications service
Dependencies
- dbus-next on Linux
- rubicon-objc on macOS
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for desktop_notifier-1.1.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 36c96794c29118b682deaf5a5f8d167c114637577b71bea8974805aff36eebc8 |
|
MD5 | 1a388bf4f496ff1c58cc29f4d1db6a1d |
|
BLAKE2b-256 | 52b43595ea9efd3a7998e456306a29b2f1add77dd9d5545c3871ef2e21ec354a |