spacr.qt.notify

Cross-platform desktop notifications.

Used to fire an OS-level notification when a long pipeline finishes, so users don’t have to sit and watch a progress bar. Fails silently on any error — a missing notification is never worth crashing over.

Backends, in preference order:

  • Linux — notify-send (libnotify)

  • macOS — osascript -e 'display notification …'

  • Windows — win32 ToastNotifier if available, else no-op

Also exposes an in-app fallback via a Qt system-tray message so users who disabled OS notifications still get a subtle badge.

Functions

announce_pipeline_finished(→ None)

Convenience wrapper: notify the user a pipeline finished.

notify(→ bool)

Best-effort OS notification.

notify_tray(→ bool)

In-app fallback via QSystemTrayIcon.

Module Contents

spacr.qt.notify.announce_pipeline_finished(app_key: str, status: str, elapsed_s: float) → None[source]

Convenience wrapper: notify the user a pipeline finished.

Called from the Qt runtime when a pipeline worker emits its finished signal.

The run sound is asked for only when spacr.qt.sound is already loaded, which it is exactly when sound has been switched on: the engine is built by apply_sound_preferences at launch and after every Save, and without an engine spacr.qt.sound.announce_run_end() is a no-op anyway. Importing it here unconditionally cost 20.4 ms on the GUI thread at the first run that ended, for a user who had never asked for sound.

Parameters:

  • app_key – id of the pipeline app ("mask" / …).

  • status – "success" / "failed" / "cancelled".

  • elapsed_s – wall-clock seconds the run took.

spacr.qt.notify.notify(title: str, body: str = '', app_name: str = 'spaCR') → bool[source]

Best-effort OS notification.

Parameters:

  • title – short headline.

  • body – optional longer body text.

  • app_name – sender name shown alongside the notification.

Returns:

True iff a backend accepted the request.

spacr.qt.notify.notify_tray(title: str, body: str = '', icon: str | None = None) → bool[source]

In-app fallback via QSystemTrayIcon.

Called by the pipeline runner when notify() fails. Requires a running QApplication — safe no-op headless.

Parameters:

title – heading of the tray balloon message, shown for six seconds.

Returns:

True if the message was handed to the system tray, False without an application or tray, or on any error.