Add on_dispatched event

This event is fired when a notification was sent to the notifications server. This is less useful as class-level callback, but very useful with `Notification`, because it allows for a better separation of concerns (separates creating and sending notifications).

Author: PhrozenByte

README.md

@@ -91,6 +91,7 @@ async def main() -> None:
         reply_field=ReplyField(
             on_replied=lambda text: print("Brutus replied:", text),
         ),
+        on_dispatched=lambda: print("Notification showing"),
         on_clicked=lambda: print("Notification clicked"),
         on_dismissed=lambda: print("Notification dismissed"),
         sound=DEFAULT_SOUND,

examples/eventloop.py

@@ -27,6 +27,7 @@ async def main() -> None:
             button_title="Send",
             on_replied=lambda text: print("Brutus replied:", text),
         ),
+        on_dispatched=lambda: print("Notification showing"),
         on_clicked=lambda: print("Notification clicked"),
         on_dismissed=lambda: print("Notification dismissed"),
         sound=DEFAULT_SOUND,

examples/eventloop_handlers.py

@@ -11,6 +11,10 @@
     asyncio.set_event_loop_policy(EventLoopPolicy())
 
 
+def on_dispatched(identifier: str) -> None:
+    print(f"Notification '{identifier}' is showing now")
+
+
 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_dispatched = on_dispatched
     notifier.on_clicked = on_clicked
     notifier.on_dismissed = on_dismissed
     notifier.on_button_pressed = on_button_pressed

examples/synchronous.py

@@ -23,6 +23,7 @@
         button_title="Send",
         on_replied=lambda text: print("Brutus replied:", text),
     ),
+    on_dispatched=lambda: print("Notification showing"),
     on_clicked=lambda: print("Notification clicked"),
     on_dismissed=lambda: print("Notification dismissed"),
     sound=DEFAULT_SOUND,

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_dispatched: 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
@@ -67,6 +68,8 @@ async def send(self, notification: Notification) -> None:
             logger.debug("Notification sent: %s", notification)
             self._notification_cache[notification.identifier] = notification
 
+            self.handle_dispatched(notification.identifier, notification)
+
     def _clear_notification_from_cache(self, identifier: str) -> Notification | None:
         """
         Removes the notification from our cache. Should be called by backends when the
@@ -142,6 +145,14 @@ async def get_capabilities(self) -> frozenset[Capability]:
         """
         ...
 
+    def handle_dispatched(
+        self, identifier: str, notification: Notification | None = None
+    ) -> None:
+        if notification and notification.on_dispatched:
+            notification.on_dispatched()
+        elif self.on_dispatched:
+            self.on_dispatched(identifier)
+
     def handle_clicked(
         self, identifier: str, notification: Notification | None = None
     ) -> None:

src/desktop_notifier/backends/dbus.py

@@ -260,6 +260,7 @@ async def get_capabilities(self) -> frozenset[Capability]:
             Capability.TITLE,
             Capability.TIMEOUT,
             Capability.URGENCY,
+            Capability.ON_DISPATCHED,
         }
 
         # Capabilities supported by some notification servers.

src/desktop_notifier/backends/macos.py

@@ -398,6 +398,7 @@ async def get_capabilities(self) -> frozenset[Capability]:
             Capability.MESSAGE,
             Capability.BUTTONS,
             Capability.REPLY_FIELD,
+            Capability.ON_DISPATCHED,
             Capability.ON_CLICKED,
             Capability.ON_DISMISSED,
             Capability.SOUND,

src/desktop_notifier/backends/winrt.py

@@ -298,6 +298,7 @@ async def get_capabilities(self) -> frozenset[Capability]:
             Capability.ICON,
             Capability.BUTTONS,
             Capability.REPLY_FIELD,
+            Capability.ON_DISPATCHED,
             Capability.ON_CLICKED,
             Capability.ON_DISMISSED,
             Capability.THREAD,

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_dispatched: Callable[[], Any] | None = None
+    """Method to call when the notification was sent to the notifications server for display"""
+
     on_clicked: Callable[[], Any] | None = None
     """Method to call when the notification is clicked"""
 
@@ -289,6 +292,9 @@ class Capability(Enum):
     ATTACHMENT = auto()
     """Supports notification attachments. Allowed file types vary by platform."""
 
+    ON_DISPATCHED = auto()
+    """Supports on-dispatched 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_dispatched: 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_dispatched=on_dispatched,
             on_clicked=on_clicked,
             on_dismissed=on_dismissed,
             attachment=attachment,
@@ -275,6 +277,22 @@ async def get_capabilities(self) -> frozenset[Capability]:
             self._capabilities = await self._backend.get_capabilities()
         return self._capabilities
 
+    @property
+    def on_dispatched(self) -> Callable[[str], Any] | None:
+        """
+        A method to call when a notification is sent to the notifications server
+
+        The method must take the notification identifier as a single argument.
+
+        If the notification itself already specifies an on_dispatched handler, it will
+        be used instead of the class-level handler.
+        """
+        return self._backend.on_dispatched
+
+    @on_dispatched.setter
+    def on_dispatched(self, handler: Callable[[str], Any] | None) -> None:
+        self._backend.on_dispatched = 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_dispatched: 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_dispatched=on_dispatched,
             on_clicked=on_clicked,
             on_dismissed=on_dismissed,
             attachment=attachment,

tests/test_api.py

@@ -57,6 +57,7 @@ async def test_send(notifier: DesktopNotifier) -> None:
             button_title="Send",
             on_replied=lambda text: print("Brutus replied:", text),
         ),
+        on_dispatched=lambda: print("Notification showing"),
         on_clicked=lambda: print("Notification clicked"),
         on_dismissed=lambda: print("Notification dismissed"),
         sound=DEFAULT_SOUND,

tests/test_callbacks.py

@@ -28,6 +28,23 @@ async def check_supported(notifier: DesktopNotifier, capability: Capability) ->
         pytest.skip(f"{notifier} not supported by backend")
 
 
+@pytest.mark.asyncio
+async def test_dispatched_callback_called(notifier: DesktopNotifier) -> None:
+    class_handler = Mock()
+    notification_handler = Mock()
+    notifier.on_dispatched = class_handler
+    notification = Notification(
+        title="Julius Caesar",
+        message="Et tu, Brute?",
+        on_dispatched=notification_handler,
+    )
+
+    await notifier.send_notification(notification)
+
+    class_handler.assert_not_called()
+    notification_handler.assert_called_once()
+
+
 @pytest.mark.asyncio
 async def test_clicked_callback_called(notifier: DesktopNotifier) -> None:
     await check_supported(notifier, Capability.ON_CLICKED)
@@ -135,6 +152,17 @@ async def test_replied_callback_called(notifier: DesktopNotifier) -> None:
     notification_handler.assert_called_with("A notification response")
 
 
+@pytest.mark.asyncio
+async def test_dispatched_fallback_handler_called(notifier: DesktopNotifier) -> None:
+    class_handler = Mock()
+    notifier.on_dispatched = class_handler
+    notification = Notification(title="Julius Caesar", message="Et tu, Brute?")
+
+    identifier = await notifier.send_notification(notification)
+
+    class_handler.assert_called_with(identifier)
+
+
 @pytest.mark.asyncio
 async def test_clicked_fallback_handler_called(notifier: DesktopNotifier) -> None:
     await check_supported(notifier, Capability.ON_CLICKED)