Support `on_timeout` callback for Linux and Windows backends

[gaesa]

The library currently exposes callbacks for on_dispatched, on_clicked, and on_dismissed, but there is no callback for “notification timed out”. I would like to propose adding a new callback: on_timeout, parallel to on_dismissed.

Linux (Freedesktop)

The Freedesktop notification spec distinguishes:

• Dismissed (2) — closed explicitly by the user
• Expired (1) — closed automatically due to timeout

The current DBus backend already defines NOTIFICATION_CLOSED_EXPIRED = 1, but the value is unused.

The code path in _on_closed only handles the dismissed case:

if reason == NOTIFICATION_CLOSED_DISMISSED:
    self.handle_dismissed(identifier)

In recent versions of KDE (confirmed on Plasma 6.4.5 and 6.5.2), each notification whose action list is non-empty and even in length was immediately cleared when the client process exited. This behavior was not observed on Plasma 6.0.3, 6.2.1, or 6.3.4. (The condition—non-empty action list of even length—was introduced in this change.)

So not handling the expired case has practical consequences:

• When a client process exits, its DBus connection is closed.
• Any active notifications associated with that client disappear immediately.
• Therefore, it is necessary to wait until the notification has actually timed out.
• Without on_timeout being exposed, this cannot be implemented correctly.
• Simply doing asyncio.sleep(timeout) (or similar) is unreliable: hovering over the notification pauses and resets the timeout in many DE. The process may therefore exit while the notification is still fully visible, causing it to vanish instantly.

Even without the actions issue, this feature is still valuable in certain scenarios.

Windows (WinRT Toast)

Windows Toast also distinguishes two close reasons:

• UserCanceled: current on_dismissed
• TimedOut: currently ignored by the backend

But currently _on_dismissed only handles ToastDismissalReason.USER_CANCELED

Although Windows toast notifications survive process exit, supporting TimedOut is still natural, trivial, and harmless — it provides consistent behaviour across platforms.

MacOS

Very hard to implement, the documentation of Apple is unclear, and it remains to be seen how much rubicon-objc can accomplish, maybe a substantial rewrite to this backend is required. Since macOS notifications persist after process exit anyway, the lack of a distinct timeout callback is far less problematic than on Linux and can safely be left unimplemented for now.

---

API proposal

Add an optional on_timeout callback parameter to DesktopNotifier.send, analogous to on_dismissed.

await notifier.send(
    ...,
    on_dismissed=...,
    on_timeout=...,      # new
)

Backend changes are minimal:

• Linux DBus: map NOTIFICATION_CLOSED_EXPIRED to handle_timeout
• Windows WinRT: map ToastDismissalReason.TIMED_OUT to handle_timeout
• macOS: no-op

This change is completely backwards-compatible because:

• _on_closed/_on_dismissed are private
• Existing on_dismissed semantics remain "user explicitly closed"
• No breaking changes to public API if we only add a new optional callback

I'm willing to submit a PR if you're open to the idea. Implementation on Linux + Windows should be <100 LOC and trivial.

[PhrozenByte]

See #208

Few notes:

• TimedOut on Windows just means that the toast was sent to the notifications center; the notification is still active
• Native support of timeout (i.e., closing a notification after a given period of time) is very inconsistent across platforms, that's why we had some ideas for cross-platform implementations, but that's not trivial to implement (see #208 (comment) and the issues linked there)

Very detailed feature request, great, thanks! 👍

[gaesa]

Thanks for the quick response and the link to #208.

I did search open issues before posting, but missed that this one was a PR – my apologies for the duplicate discussion. Because the CONTRIBUTING.md explicitly states:

If you would like to contribute more than a simple bug fix, please open an issue first to discuss potential changes before implementing them.

Regarding TimedOut on Windows, according to the current official documentation,

The toast notification had been shown for the maximum allowed time and was faded out. The maximum time to show a toast notification is 7 seconds except in the case of long-duration toasts, in which case it is 25 seconds.

on modern Windows 10/11 it does correspond to the natural on-screen expiration and has the same semantics as the Freedesktop reason=1 (Expired). Did I miss some nuance here?

---

The request here is narrower than the broader cross-platform timeout ideas in #208: simply expose the obviously already-available expiration events on Linux (reason=1) and Windows (TimedOut). For macOS, the callback can be a plain no-op (empty function body) or print a one-time warning to sys.stderr.

macOS support is indeed the tricky part, and without contributors familiar with the relevant documentation or able to test the behaviour, requiring a full implementation there would prevent the feature from landing on the other two platforms for a very long time. Shipping Linux + Windows support first would deliver immediate value to the vast majority of users.

[PhrozenByte]

my apologies for the duplicate discussion

No harm done

Regarding TimedOut […] on modern Windows 10/11 it does correspond to the natural on-screen expiration and has the same semantics as the Freedesktop reason=1 (Expired). Did I miss some nuance here?

FDO implementations differ (it's quite a mess unfortunately), but historically (and still in GNOME at least) an expired notification was / is equivalent to a closed / dismissed notification, i.e. the notification is "gone", not just sent to the "background", like to a notifications center.

For example, GNOME shows notifications on screen and sends them to the notifications center after a GNOME-decided duration (with an exception for persistent notifications). There's no event issued when the notification is sent to the notifications center (synonymous "hidden"). Notifications are still active and can issue actions - indefinitely, i.e. until closed by user interaction, or by calling Desktop Notifier's clear() (resp. DBus call_close_notification).

On Windows, the TimedOut event is issued when the notification is sent to the notifications center ("hidden"). The notification is still active and can issue actions - indefinitely, i.e. until closed by user interaction, or by calling Desktop Notifier's clear() (resp. WinRT API remove_grouped_tag_with_id). It is thus not equivalent to UserCanceled.

Also see #206 (comment)

Are we talking about the "notification is sent to the notifications center (hidden) and still active, just no longer shown on-screen" event, or the "notification was closed automatically after some duration and is gone now" event?

Because you earlier noted "Expired (1) — closed automatically", so I was assuming that you talk about the latter case, which is different from Windows' TimedOut.

The request here is narrower than the broader cross-platform timeout ideas in #208: simply expose the obviously already-available expiration events

That's exactly what #208 is about 😄 The hard part is #46 resp. #206 resp. its follow-up after #200.

[gaesa]

Thanks for the patient and detailed explanation – I now fully understand the subtle (and messy) differences in expiration semantics across implementations.

The scoped request here is indeed covered by #208. If you're okay with it, I'm happy to close this issue.

Appreciate the ongoing work on that PR – looking forward to it landing!

[samschott]

Thank you @gaesa for the thorough proposal, and @PhrozenByte for explaining the cross-platform issues with timeouts.

Apologies for the lack of progress on #208. I have no objections in principle to a callback on timeouts. One thing that I am clear in about is regarding use cases: Does it make sense to combine handling of timeouts and other programmatic closing? It will be a breaking API change to split those again in the future, so if you can see value in separate handling, I'd rather introduce this now.

[PhrozenByte]

Does it make sense to combine handling of timeouts and other programmatic closing? It will be a breaking API change to split those again in the future, so if you can see value in separate handling, I'd rather introduce this now.

Sure, there's no harm in adding separate events. This won't affect #208 though (i.e., you can merge #208, no matter whether you want to go with a single or separate events), only the cross-platform implementation of timeouts (i.e., we'll add a separate event then, e.g. on_expired or similar). In the meantime it's impossible to distinguish a native timeout from a programmatic close - we only can with a cross-platform implementation (we then do so by never registering the native timeout, but doing things on our own, see #206 (diff)).