Skip to content

terok-dbus

D-Bus desktop notification package for the terok clearance system.

What it does

terok-dbus wraps the freedesktop Notifications D-Bus interface via dbus-fast, providing an async-first Python API for desktop notifications with action buttons.

Key properties

  • Async-first — built on dbus-fast with native asyncio support
  • Action buttons — notifications can carry interactive actions (Allow / Deny)
  • Signal handling — listen for ActionInvoked and NotificationClosed signals
  • Graceful fallback — create_notifier() returns a silent NullNotifier when D-Bus is unavailable (headless, container, CI)
  • Protocol-based — consumers type-hint against Notifier (PEP 544 Protocol)

Quick start

Install

pip install terok-dbus

Send a notification

import asyncio
from terok_dbus import create_notifier

async def main():
    notifier = await create_notifier(app_name="terok")
    action_received = asyncio.Event()

    def on_action(nid, key):
        print(f"{nid}: {key}")
        action_received.set()

    notifier.on_action(on_action)

    nid = await notifier.notify(
        "Clearance request",
        "Task alpha wants access to api.github.com:443",
        actions={"allow": "Allow", "deny": "Deny"},
    )

    await action_received.wait()
    await notifier.close()

asyncio.run(main())

CLI tool (development / testing)

terok-dbus-notify "Title" "Body" --actions allow:Allow deny:Deny --wait

API preview

Symbol Description
create_notifier() Async factory — returns DesktopNotifier or NullNotifier
DesktopNotifier Real D-Bus client via dbus-fast
NullNotifier No-op fallback (all methods return immediately)
Notifier PEP 544 Protocol for consumer type hints

Next steps