Add on_cleared event

[PhrozenByte]

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).

We'll later also utilize this for the cross-platform implementation of timeout.

Without this new event we'd have to remove the if reason == NOTIFICATION_CLOSED_DISMISSED: check in DBusDesktopNotifier.

ToDo:

• [x] After merging #203 Notification.on_cleared must be changed to:

      on_cleared: Callable[[], Any] | None = field(default=None, repr=False)
  

• [x] After merging #205 DesktopNotifierBackend.on_cleared must be changed to:

      def handle_cleared(self, identifier: str) -> None:
          notification = self._clear_notification_from_cache(identifier)
          # …
  

• [x] After merging #205 DesktopNotifierBackend.on_cleared also update the docstring of DesktopNotifier.on_cleared
• [x] Add on_cleared to DesktopNotifierSync after merging #207

[codecov-commenter]

Codecov Report

:x: Patch coverage is 77.77778% with 6 lines in your changes missing coverage. Please review. :white_check_mark: Project coverage is 85.78%. Comparing base (75fd356) to head (80ea9b8). :warning: Report is 25 commits behind head on main.

Files with missing lines	Patch %	Lines
src/desktop_notifier/backends/winrt.py	0.00%	3 Missing :warning:
src/desktop_notifier/sync.py	66.66%	2 Missing :warning:
src/desktop_notifier/main.py	83.33%	1 Missing :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #208      +/-   ##
==========================================
+ Coverage   85.26%   85.78%   +0.51%     
==========================================
  Files          10       10              
  Lines         964     1013      +49     
==========================================
+ Hits          822      869      +47     
- Misses        142      144       +2     

Flag	Coverage Δ
pytest	85.78% <77.77%> (+0.51%)	:arrow_up:

Flags with carried forward coverage won't be shown. Click here to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[samschott]

As for https://github.com/samschott/desktop-notifier/pull/209, could you check if similar events are available on macOS and Windows?

[PhrozenByte]

Windows doesn't have a similar event (I checked).

Can't say anything about OS X because I neither understand their overly complex API, nor do I have an Apple device to do manual testing. I'm afraid anything OS-X-related is up to you.

As said earlier, my ultimate goal is to use this for #206 too, i.e. independent of the backend used. I'm just not sure yet how to prevent calling the dismissal class-level handler. However, this isn't really relevant here, see #206.

[PhrozenByte]

Do you think there is any value in distinguishing between expired and programatically closed notifications?

We could.

It's been five months, so I've forgotten a lot of my original reasoning :laughing: Sometimes that's a good thing: I now spent quite some time to think about this, especially in regards to #206, and distinguishing between those as well makes things easier for #206, too: We could then have a separate handler for #206 and the issues with #206 about duplicate events magically disappear thanks to DispatchedNotification. So, I definitely like your idea :+1:

I've rebased and updated this PRs accordingly. I'll update the other PRs as well.

[samschott]

@PhrozenByte, did you actually update this PR to separate timeout and programmatic clearing calbacks?

[PhrozenByte]

Yes. I assume you ask because I forgot to remove timeout from the examples? I just fixed that, sorry. Since I was over it I also now fully unified the examples. Should be ready-to-merge now :+1:

[PhrozenByte]

PR is up-to-date with main now (and thus all todos done) and ready to review + merge :+1:

After this has been merged I'll look into getting #200 back on track, it's mostly a single feature then (introducing DispatchedNotification) that can be reviewed separately. #200 then allows us to implement #46 resp. #206, which then also enables on_cleared for all backends, not just DBus.