hyprland-events

Typed event dispatch layer for Hyprland IPC. Built on top of hyprland-socket.

Every Hyprland event is parsed into a frozen dataclass with named fields — no more splitting strings on commas.

Installation

pip install hyprland-events

Usage

Blocking event loop

from hyprland_events import EventDispatcher, WorkspaceEvent, MonitorAddedEvent

dispatcher = EventDispatcher()

@dispatcher.on("workspacev2")
def on_workspace(event: WorkspaceEvent):
    print(f"Switched to workspace {event.id} ({event.name})")

@dispatcher.on("monitoraddedv2")
def on_monitor(event: MonitorAddedEvent):
    print(f"Monitor {event.name} connected")

dispatcher.run()  # blocks until the socket closes

on() also works without the decorator syntax:

dispatcher.on("workspacev2", my_handler)

GLib / GTK integration

from gi.repository import GLib
from hyprland_events import EventDispatcher

dispatcher = EventDispatcher()
dispatcher.on("configreloaded", lambda e: print("Config reloaded"))

sock, feed = dispatcher.connect()
GLib.io_add_watch(
    sock.fileno(), GLib.IO_IN,
    lambda *_: feed(sock.recv(4096)) or True,
)

Wildcard handler

dispatcher.on("*", lambda event: print(event))

One-off parsing

from hyprland_events import parse_event

event = parse_event("workspacev2", "3,code")
# WorkspaceEvent(id=3, name='code')

Supported events

Unrecognized events are passed to handlers as the raw hyprland_socket.Event(name, data) object.

For sending commands and querying Hyprland state, see hyprland-socket.

License

MIT