repository·main·Indexed 41 days ago
https://github.com/samschott/desktop-notifierA Python library for sending cross-platform desktop notifications on Linux, macOS, iOS, and Windows. Version 6.2.0 supports asynchronous notifications via the DesktopNotifier class, featuring advanced capabilities such as clickable buttons, reply fields, callbacks for notification lifecycle events, and file attachments.
MacOS, Windows, and most Linux notification servers support executing Python callbacks when a notification is clicked (on_clicked) or dismissed (on_dismissed).
Requirement: To ensure these callbacks are actually executed, you must have a running event loop in your Python application to handle the incoming interactions.
Attachments allow you to include media in notifications. Supported types and limitations vary:
Supports local files with the following limits:
You can add buttons to notifications to allow user interaction via callbacks. However, the number of supported buttons is limited by the platform:
Note: If you specify more buttons than the platform supports, any additional buttons will be silently ignored.
On macOS, executing callbacks requires a running CFRunLoop. To integrate asyncio with the required Core Foundation loop, use rubicon-objc and set the EventLoopPolicy.
import asyncio
from rubicon.objc.eventloop import EventLoopPolicy
# Install the event loop policy
asyncio.set_event_loop_policy(EventLoopPolicy())To use the asynchronous API effectively and ensure callbacks execute correctly on macOS, you must have a running CFRunLoop. You can integrate asyncio with CFRunLoop using the EventLoopPolicy from the rubicon-objc library. Since desktop-notifier already uses rubicon-objc to interface with Cocoa APIs, installing this policy does not add new external dependencies to your project.
On Linux, a standard asyncio event loop is sufficient, but macOS requires this specific policy to prevent blocking IO from Cocoa APIs.
import asyncio
from rubicon.objc.eventloop import EventLoopPolicy
# Install the event loop policy
asyncio.set_event_loop_policy(EventLoopPolicy())Desktop Notifier is a Python library for sending desktop notifications.
Install the package using pip:
pip install desktop-notifierTo send a notification, import the library and use the notification functions. (Note: Refer to the specific API documentation for detailed method signatures).
Install the desktop-notifier library from PyPI using pip to enable cross-platform desktop notifications on Linux, macOS, iOS, and Windows.
pip3 install -U desktop-notifierIf you are developing a Gtk application on Gnome, you can integrate the asyncio event loop with the Gtk main loop using the gbulb library. While this is not required for the full functionality of desktop-notifier, it can be a convenient way to manage concurrency within a Gtk environment.
# Use gbulb to integrate asyncio with Gtk
# (Requires installing gbulb)The DesktopNotifierBackend provides hooks for responding to user interactions with notifications. You can define these at two levels:
backend.on_clicked = my_callback). These are triggered if the specific Notification object does not have its own individual callback defined.Notification object (e.g., notification.on_clicked = my_callback). These take precedence over global backend callbacks.Available Event Handlers:
on_dispatched: Triggered when a notification is successfully sent.on_clicked: Triggered when a user clicks the notification.on_dismissed: Triggered when a user dismisses the notification.on_button_pressed(identifier: str, button_identifier: str): Triggered when a specific button on a notification is pressed.on_replied(identifier: str, reply_text: str): Triggered when a user submits a text reply to a notification.A Notification can be customized using several supporting classes and types to control its appearance and interactivity:
Button: Add interactive buttons to a notification.ReplyField: Add a text input field for user replies.Urgency: Set the importance level of the notification.Icon: Specify a custom icon for the notification.Sound: Specify a custom sound to play.Attachment: Attach files to the notification.Capability: Check for supported features on the current platform.The project uses FileResource (and its subclasses Icon, Sound, and Attachment) to handle media. A resource must be initialized with either a local path (as a pathlib.Path) or a uri (as a str). Providing both or neither will raise a RuntimeError.
from pathlib import Path
from desktop_notifier import Icon, Sound, Attachment
# Using a local path
my_icon = Icon(path=Path("/path/to/icon.png"))
# Using a URI
my_sound = Sound(uri="file:///path/to/sound.wav")
# Using a system name (for Sound/Icon)
my_system_sound = Sound(name="default")You can handle user interactions in two ways:
DesktopNotifier instance. They act as defaults for all notifications sent by that instance. They receive the notification identifier as an argument.Notification object (or via the send() method). These take precedence over class-level handlers and are tied to the specific Python instance of that notification.Available Callbacks:
on_dispatched(notification_id: str): Called when the notification is sent to the system.on_clicked(notification_id: str): Called when the user clicks the notification.on_dismissed(notification_id: str): Called when the user dismisses the notification.on_button_pressed(notification_id: str, button_id: str): Called when a specific button is clicked.on_replied(notification_id: str, text: str): Called when a user submits text via a ReplyField.# Class-level handler
notifier.on_clicked = lambda nid: print(f"Clicked: {nid}")
# Notification-level handler (takes precedence)
await notifier.send(
title="Specific Task",
message="Click me",
on_clicked=lambda nid: print("Clicked specific notification")
)