_protocol

_protocol

PEP 544 protocol defining the Notifier interface.

Notifier

Bases: Protocol

Structural type for desktop notification backends.

Implementations must provide notify, on_action, close, and disconnect. DbusNotifier talks to a real session bus; NullNotifier silently discards everything for headless environments.

notify(summary, body='', *, actions=(), timeout_ms=-1, hints=None, replaces_id=0, app_icon='') async

Send a desktop notification.

Parameters:

Name	Type	Description	Default
summary	str	Notification title.	required
body	str	Optional body text.	''
actions	Sequence[tuple[str, str]]	(action_id, label) pairs rendered as buttons.	()
timeout_ms	int	Expiration hint in milliseconds (-1 = server default).	-1
hints	Mapping[str, Any] | None	Freedesktop hint dict (values are dbus_fast.Variant for DbusNotifier, ignored by NullNotifier).	None
replaces_id	int	Replace an existing notification in-place.	0
app_icon	str	Icon name or file:/// URI.	''

Returns:

Type	Description
int	Server-assigned notification ID (0 for null implementations).

Source code in src/terok_dbus/_protocol.py

async def notify(
    self,
    summary: str,
    body: str = "",
    *,
    actions: Sequence[tuple[str, str]] = (),
    timeout_ms: int = -1,
    hints: Mapping[str, Any] | None = None,
    replaces_id: int = 0,
    app_icon: str = "",
) -> int:
    """Send a desktop notification.

    Args:
        summary: Notification title.
        body: Optional body text.
        actions: ``(action_id, label)`` pairs rendered as buttons.
        timeout_ms: Expiration hint in milliseconds (``-1`` = server default).
        hints: Freedesktop hint dict (values are ``dbus_fast.Variant`` for
            ``DbusNotifier``, ignored by ``NullNotifier``).
        replaces_id: Replace an existing notification in-place.
        app_icon: Icon name or ``file:///`` URI.

    Returns:
        Server-assigned notification ID (``0`` for null implementations).
    """
    ...

on_action(notification_id, callback) async

Register a callback for when the user clicks an action button.

Parameters:

Name	Type	Description	Default
notification_id	int	ID returned by notify.	required
callback	Callable[[str], None]	Called with the action_id string when invoked.	required

Source code in src/terok_dbus/_protocol.py

async def on_action(
    self,
    notification_id: int,
    callback: Callable[[str], None],
) -> None:
    """Register a callback for when the user clicks an action button.

    Args:
        notification_id: ID returned by ``notify``.
        callback: Called with the ``action_id`` string when invoked.
    """
    ...

close(notification_id) async

Close an active notification.

Parameters:

Name	Type	Description	Default
notification_id	int	ID returned by notify.	required

Source code in src/terok_dbus/_protocol.py

async def close(self, notification_id: int) -> None:
    """Close an active notification.

    Args:
        notification_id: ID returned by ``notify``.
    """
    ...

disconnect() async

Release backend resources (no-op for null backends).

Source code in src/terok_dbus/_protocol.py

async def disconnect(self) -> None:
    """Release backend resources (no-op for null backends)."""
    ...