Add on_cleared event

This event is fired when a notification was closed without user interaction, e.g. because the notification timed out (DBus only, and only if supported by the notifications server; undetectable by capabilities), or because the notification was closed by another process (DBus only).

Author: PhrozenByte

README.md

@@ -91,9 +91,11 @@ async def main() -> None:
         reply_field=ReplyField(
             on_replied=lambda text: print("Brutus replied:", text),
         ),
+        on_cleared=lambda: print("Notification timed out"),
         on_clicked=lambda: print("Notification clicked"),
         on_dismissed=lambda: print("Notification dismissed"),
         sound=DEFAULT_SOUND,
+        timeout=10,
     )
 
     # Run the event loop forever to respond to user interactions with the notification.

examples/eventloop.py

@@ -27,9 +27,11 @@ async def main() -> None:
             button_title="Send",
             on_replied=lambda text: print("Brutus replied:", text),
         ),
+        on_cleared=lambda: print("Notification timed out"),
         on_clicked=lambda: print("Notification clicked"),
         on_dismissed=lambda: print("Notification dismissed"),
         sound=DEFAULT_SOUND,
+        timeout=10,
     )
 
     # Run the event loop forever to respond to user interactions with the notification.

examples/eventloop_handlers.py

@@ -11,6 +11,10 @@
     asyncio.set_event_loop_policy(EventLoopPolicy())
 
 
+def on_cleared(identifier: str) -> None:
+    print(f"Notification '{identifier}' was cleared without user interaction")
+
+
 def on_clicked(identifier: str) -> None:
     print(f"Notification '{identifier}' was clicked")
 
@@ -29,6 +33,7 @@ def on_replied(identifier: str, reply: str) -> None:
 
 async def main() -> None:
     notifier = DesktopNotifier(app_name="Sample App")
+    notifier.on_cleared = on_cleared
     notifier.on_clicked = on_clicked
     notifier.on_dismissed = on_dismissed
     notifier.on_button_pressed = on_button_pressed
@@ -47,6 +52,7 @@ async def main() -> None:
             button_title="Send",
         ),
         sound=DEFAULT_SOUND,
+        timeout=10,
     )
 
     # Run the event loop forever to respond to user interactions with the notification.

examples/synchronous.py

@@ -23,7 +23,9 @@
         button_title="Send",
         on_replied=lambda text: print("Brutus replied:", text),
     ),
+    on_cleared=lambda: print("Notification timed out"),
     on_clicked=lambda: print("Notification clicked"),
     on_dismissed=lambda: print("Notification dismissed"),
     sound=DEFAULT_SOUND,
+    timeout=10,
 )

src/desktop_notifier/backends/base.py

@@ -28,6 +28,7 @@ def __init__(self, app_name: str) -> None:
         self.app_name = app_name
         self._notification_cache: dict[str, Notification] = dict()
 
+        self.on_cleared: Callable[[str], Any] | None = None
         self.on_clicked: Callable[[str], Any] | None = None
         self.on_dismissed: Callable[[str], Any] | None = None
         self.on_button_pressed: Callable[[str, str], Any] | None = None
@@ -142,6 +143,14 @@ async def get_capabilities(self) -> frozenset[Capability]:
         """
         ...
 
+    def handle_cleared(
+        self, identifier: str, notification: Notification | None = None
+    ) -> None:
+        if notification and notification.on_cleared:
+            notification.on_cleared()
+        elif self.on_cleared:
+            self.on_cleared(identifier)
+
     def handle_clicked(
         self, identifier: str, notification: Notification | None = None
     ) -> None:

src/desktop_notifier/backends/dbus.py

@@ -249,6 +249,8 @@ def _on_closed(self, nid: int, reason: int) -> None:
 
         if reason == NOTIFICATION_CLOSED_DISMISSED:
             self.handle_dismissed(identifier, notification)
+        else:
+            self.handle_cleared(identifier, notification)
 
     async def get_capabilities(self) -> frozenset[Capability]:
         if not self.interface:
@@ -260,6 +262,7 @@ async def get_capabilities(self) -> frozenset[Capability]:
             Capability.TITLE,
             Capability.TIMEOUT,
             Capability.URGENCY,
+            Capability.ON_CLEARED,
         }
 
         # Capabilities supported by some notification servers.

src/desktop_notifier/backends/winrt.py

@@ -255,11 +255,11 @@ def _on_dismissed(
 
         notification = self._clear_notification_from_cache(sender.tag)
 
-        if (
-            dismissed_args
-            and dismissed_args.reason == ToastDismissalReason.USER_CANCELED
-        ):
-            self.handle_dismissed(sender.tag, notification)
+        if dismissed_args:
+            # ToastDismissalReason.APPLICATION_HIDDEN and ToastDismissalReason.TIMED_OUT
+            # both just indicate that the toast was sent to the notifications center
+            if dismissed_args.reason == ToastDismissalReason.USER_CANCELED:
+                self.handle_dismissed(sender.tag, notification)
 
     def _on_failed(
         self, sender: ToastNotification | None, failed_args: ToastFailedEventArgs | None

src/desktop_notifier/common.py

@@ -221,6 +221,9 @@ class Notification:
     """Text field shown on an interactive notification. This can be used for example
     for messaging apps to reply directly from the notification."""
 
+    on_cleared: Callable[[], Any] | None = None
+    """Method to call when the notification is cleared without user interaction"""
+
     on_clicked: Callable[[], Any] | None = None
     """Method to call when the notification is clicked"""
 
@@ -289,6 +292,10 @@ class Capability(Enum):
     ATTACHMENT = auto()
     """Supports notification attachments. Allowed file types vary by platform."""
 
+    ON_CLEARED = auto()
+    """Supports distinguishing between an user closing a notification, and clearing a
+    notification programmatically, and consequently supports on-cleared callbacks"""
+
     ON_CLICKED = auto()
     """Supports on-clicked callbacks"""
 

src/desktop_notifier/main.py

@@ -216,6 +216,7 @@ async def send(
         icon: Icon | None = None,
         buttons: Sequence[Button] = (),
         reply_field: ReplyField | None = None,
+        on_cleared: Callable[[], Any] | None = None,
         on_clicked: Callable[[], Any] | None = None,
         on_dismissed: Callable[[], Any] | None = None,
         attachment: Attachment | None = None,
@@ -239,6 +240,7 @@ async def send(
             icon=icon,
             buttons=tuple(buttons),
             reply_field=reply_field,
+            on_cleared=on_cleared,
             on_clicked=on_clicked,
             on_dismissed=on_dismissed,
             attachment=attachment,
@@ -275,6 +277,23 @@ async def get_capabilities(self) -> frozenset[Capability]:
             self._capabilities = await self._backend.get_capabilities()
         return self._capabilities
 
+    @property
+    def on_cleared(self) -> Callable[[str], Any] | None:
+        """
+        A method to call when a notification is cleared without user interaction
+        (e.g. after a timeout, or if cleared by another process)
+
+        The method must take the notification identifier as a single argument.
+
+        If the notification itself already specifies an on_cleared handler, it will be
+        used instead of the class-level handler.
+        """
+        return self._backend.on_cleared
+
+    @on_cleared.setter
+    def on_cleared(self, handler: Callable[[str], Any] | None) -> None:
+        self._backend.on_cleared = handler
+
     @property
     def on_clicked(self) -> Callable[[str], Any] | None:
         """

src/desktop_notifier/sync.py

@@ -88,6 +88,7 @@ def send(
         icon: Icon | None = None,
         buttons: Sequence[Button] = (),
         reply_field: ReplyField | None = None,
+        on_cleared: Callable[[], Any] | None = None,
         on_clicked: Callable[[], Any] | None = None,
         on_dismissed: Callable[[], Any] | None = None,
         attachment: Attachment | None = None,
@@ -103,6 +104,7 @@ def send(
             icon=icon,
             buttons=tuple(buttons),
             reply_field=reply_field,
+            on_cleared=on_cleared,
             on_clicked=on_clicked,
             on_dismissed=on_dismissed,
             attachment=attachment,