global-shortcut-portal

A pure-Python library for the Wayland Global Shortcut Portal (org.freedesktop.portal.GlobalShortcuts).
Lets any application register and receive global keyboard shortcuts on Wayland, without X11 key grabbing.

AI was used heavily during development, with human review and testing of all code.
This is a personal library I wanted and I'm sharing it in case it's useful to others.

Requirements

• Python >= 3.10
• dbus-next (pure Python, no C extensions)
• A Wayland compositor with a Global Shortcuts portal backend (KDE Plasma 6+, GNOME 48+, Hyprland, etc.)

Installation

pip install global-shortcut-portal

On systems with an externally managed environment (e.g. recent Debian/Ubuntu, Fedora, Arch Linux with system Python) use pip install --user or a virtual environment. Alternatively, install with uv:

uv pip install global-shortcut-portal

For development, clone the repo and run:

uv sync --group dev

Reference Example

The repository includes a fully-commented reference app at examples/reference_example_app.py that demonstrates the complete session lifecycle with interactive controls:

python examples/reference_example_app.py

Documentation

• docs/overview.md — the Global Shortcut Portal and this library
• docs/usage.md — full API guide with code examples
• examples/reference_example_app.py — interactive reference app

Quick Start

import asyncio
from global_shortcut_portal import GlobalShortcutsSession, Portal, Shortcut, SessionCallback

class MyCallback(SessionCallback):
    def on_activated(self, event):
        print(f"Shortcut activated: {event.shortcut_id}")

    def on_deactivated(self, event):
        print(f"Shortcut deactivated: {event.shortcut_id}")

async def main():
    portal = Portal()
    await portal.connect()

    session = GlobalShortcutsSession(
        portal,
        app_id="org.example.MyApp",
        callback=MyCallback(),
    )
    await session.connect()

    shortcuts = [
        Shortcut(
            id="toggle-overlay",
            description="Toggle overlay window",
            preferred_trigger="<Control><Alt>space",
        ),
    ]
    bound = await session.bind(shortcuts)
    for s in bound:
        print(f"Bound: {s.id} -> {s.trigger_description}")

    await asyncio.Event().wait()

asyncio.run(main())

Features

• Async API via dbus-next (pure Python asyncio D-Bus library)
• Session life-cycle management (create, bind, list, configure, close)
• Supports Registry.Register for xdg-desktop-portal >= 1.20
• Full signal handling (Activated, Deactivated, ShortcutsChanged)
• Shortcut trigger parsing and formatting (XDG shortcuts specification)
• Version 2 portal features (ConfigureShortcuts)

Notes

• Desktop environment persistence: Some DEs (notably Plasma/KDE) persist shortcut triggers per app_id. Once registered, BindShortcuts cannot overwrite these stored values. Use the native config dialog or remove entries in System Settings > Keyboard > Shortcuts while the app is closed.