Components API¶

This is the component API reference. Here you will find the nitty-gritty details about Hyprpy component objects.

For a more general overview on how to use components, take a look at the Components guide.

Instance¶

The central Instance class for interfacing with Hyprland.

This class acts as the root for accessing other components like workspaces, windows, and monitors, and offers capabilities to listen to events and signals emitted by the underlying Hyprland system.

class Instance(signature: str | None = None)¶

Bases: object

Represents an active Hyprland instance.

The Instance class is a primary interface for interacting with the Hyprland system. It provides methods for accessing windows, workspaces, and monitors, as well as emitting signals based on events in the Hyprland environment.

Seealso:: Components: The Instance

signature: str¶: Instance signature of the Hyprland instance.

event_socket: EventSocket¶: The Hyprland event socket for this instance.

command_socket: CommandSocket¶: The Hyprland command socket for this instance.

signals: InstanceSignalCollection¶: The InstanceSignalCollection for this instance.

signal_workspace_created: Signal¶: 🚫 Deprecated since v0.2.0

This signal has been moved to createworkspace and will be removed in future versions of hyprpy.

Signal emitted when a new workspace gets created. Sends created_workspace_id, the id of the created workspace, as signal data.

signal_workspace_destroyed: Signal¶: 🚫 Deprecated since v0.2.0

This signal has been moved to destroyworkspace and will be removed in future versions of hyprpy.

Signal emitted when an existing workspace gets destroyed. Sends destroyed_workspace_id, the id of the destroyed workspace, as signal data.

signal_active_workspace_changed: Signal¶: 🚫 Deprecated since v0.2.0

This signal has been moved to workspace and will be removed in future versions of hyprpy.

Signal emitted when the focus changes to another workspace. Sends active_workspace_id, the id of the now active workspace, as signal data.

signal_window_created: Signal¶: 🚫 Deprecated since v0.2.0

This signal has been moved to openwindow and will be removed in future versions of hyprpy.

Signal emitted when a new window gets created. Sends created_window_address, the address of the newly created window, as signal data.

signal_window_destroyed: Signal¶: 🚫 Deprecated since v0.2.0

This signal has been moved to closewindow and will be removed in future versions of hyprpy.

Signal emitted when an existing window gets destroyed. Sends destroyed_window_address, the address of the destroyed window, as signal data.

signal_active_window_changed: Signal¶: 🚫 Deprecated since v0.2.0

This signal has been moved to activewindow and will be removed in future versions of hyprpy.

Signal emitted when the focus changes to another window. Sends active_window_address, the address of the now active window, as signal data.

dispatch(arguments: list[str]) → str | None¶

Runs a generic dispatcher command with the given arguments and returns None on success or a string indicating errors.

See the Hyprland Wiki for a list of available commands.

Example:

from hyprpy import Hyprland

instance = Hyprland()
instance.dispatch(["cyclenext", "prev"])

Parameters:: arguments (list[str]) – A list of strings containing the arguments of the dispatch command.
Returns:: None if the command succeeded, otherwise a string indicating errors.
Return type:: str or None

get_windows() → List[Window]¶

Returns all Windows currently managed by the instance.

Returns:: A list containing Window objects.

get_window_by_address(address: str) → Window | None¶

Retrieves the Window with the specified address.

The address must be a valid hexadecimal string.

Returns:: The Window if it exists, or None otherwise.
Raises:: TypeError if address is not a string.
Raises:: ValueError if address is not a valid hexadecimal string.

get_active_window() → Window¶

Returns the currently active Window.

Returns:: The currently active Window.

get_workspaces() → List[Workspace]¶

Returns all Workspaces currently managed by the instance.

Returns:: A list containing Workspaces.

get_workspace_by_id(id: int) → Workspace | None¶

Retrieves the Workspace with the specified id.

Returns:: The Workspace if it exists, or None otherwise.
Raises:: TypeError if id is not an integer.

get_active_workspace() → Workspace¶

Retrieves the currently active Workspace.

Returns:: The currently active Workspace.

get_workspace_by_name(name: int) → Workspace | None¶

Retrieves the Workspace with the specified name.

Returns:: The Workspace if it exists, or None otherwise.
Raises:: TypeError if name is not a string.

get_monitors() → List[Monitor]¶

Returns all Monitors currently managed by the instance.

Returns:: A list containing Monitors.

get_monitor_by_id(id: int) → Monitor | None¶

Retrieves the Monitor with the specified id.

Returns:: The Monitor if it exists, or None otherwise.
Raises:: TypeError if id is not an integer.

get_monitor_by_name(name: str) → Monitor | None¶

Retrieves the Monitor with the specified name.

Returns:: The Monitor if it exists, or None otherwise.
Raises:: TypeError if name is not a string.
Raises:: ValueError if name is an empty string.

watch() → None¶

Continuosly monitors the EventSocket and emits appropriate Signals when events are detected.

This is a blocking method which runs indefinitely. Signals are continuosly emitted, as soon as Hyprland events are detected.

Seealso:: Components: Reacting to events

Window¶

Window objects represent individual windows in Hyprland.

class Window(window_data: dict, instance: Instance)¶

Bases: object

Represents a window in the Hyprland compositor.

address: str¶: String representation of a hexadecimal number, unique identifier for the window.

is_mapped: bool¶: Unknown.

is_hidden: bool¶: Unknown.

position_x: int¶: Absolute X-coordinate of the window on the monitor (in pixels).

position_y: int¶: Absolute Y-coordinate of the window on the monitor (in pixels).

width: int¶: Width of the window (in pixels).

height: int¶: Height of the window (in pixels).

workspace_id: int¶: Numeric ID of the workspace which the window is on.

workspace_name: str¶: Name of the workspace which the window is on.

is_floating: bool¶: Whether or not this is a floating window.

monitor_id: int¶: Numeric ID of the monitor which the window is on.

wm_class: str¶: Window manager class assigned to this window.

title: str¶: Current title of the window.

initial_wm_class: str¶: Window manager class when the window was created.

initial_title: str¶: Title when the window was created.

pid: int¶: Process ID of the process the window is assigned to.

is_xwayland: bool¶: Whether or not the window is using xwayland to be displayed.

is_pinned: bool¶: Unknown.

is_fullscreen: int¶: Whether or not the window is in fullscreen mode.

property workspace: Workspace¶: The Workspace which this window is in.

property address_as_int: int¶: The integer representation of the window’s address property.

Workspace¶

Workspace objects represent individual workspaces in Hyprland.

class Workspace(workspace_data: dict, instance: Instance)¶

Bases: object

Represents a workspace in Hyprland.

id: int¶: Numeric ID of the workspace.

name: str¶: Name assigned to the workspace.

monitor_name: str¶: Name of the monitor which this workspace is on.

last_window_address: str¶: Address string of the most recently active window on the workspace.

last_window_title: str¶: Title of the most recently active window on the workspace.

window_count: int¶: Number of windows placed in the workspace.

has_fullscreen: bool¶: True if at least one window in the workspace is in fullscreen mode.

property monitor: Monitor¶: The Monitor this workspace is on.

property windows: List[Window]¶: The list of all Windows on this workspace.

property last_window_address_as_int: int¶: The integer representation of the workspace’s last_window_address property.

Monitor¶

Monitor objects represent monitors in Hyprland.

class Monitor(monitor_data: str, instance: Instance)¶

Bases: object

Represents a monitor within Hyprland.

id: int¶: Numeric ID of the monitor.

name: str¶: Name of the monitor.

description: str¶: Manufacturer’s name.

make: str¶: Model number of the monitor.

model: str¶: Composite string of make, name and model.

serial: str¶: Unknown.

width: int¶: Width of the monitor (in pixels).

height: int¶: Height of the monitor (in pixels).

refresh_rate: float¶: Refresh rate of the monitor (in Hz).

position_x: int¶: Unknown.

position_y: int¶: Unknown.

active_workspace_id: int¶: Numeric ID of the workspace currently active on the monitor.

active_workspace_name: str¶: Assigned name of the workspace currently active on the monitor.

reserved: List[int]¶: Unknown.

scale: float¶: Unknown.

transform: int¶: Unknown.

is_focused: bool¶: Whether or not the currently focused window is on this monitor.

uses_dpms: bool¶: Whether or not the monitor uses DPMS.

vrr: bool¶: Unknown.

property workspaces: List[Workspace]¶: All Workspaces located on this monitor.

Instance Signals¶

The list of signals emitted by hyprpy, which covers all events sent by Hyprland.

class InstanceSignalCollection¶

Bases: object

The collection of Hyprland signals emitted by an Instance.

activelayout: Signal¶

Emits the following Signal Data when a keyboard’s layout is changed:

Name	Type	Description
`keyboard_name`	`str`	Name of the keyboard
`layout_name`	`str`	Name of the newly active layout

activespecial: Signal¶

Emits the following Signal Data when the special workspace on a monitor changes:

Name	Type	Description
`workspace_name`	`str` or `None`	`name` of the workspace (`"special:special"`) if the special workspace was created, and `None` if it was destroyed
`monitor_name`	`str`	`name` of the monitor

activespecialv2: Signal¶

Emits the following Signal Data when the special workspace on a monitor changes:

Name	Type	Description
`workspace_id`	`int` or `None`	`id` of the workspace (`-99`) if the special workspace was created, and `None` if it was destroyed
`workspace_name`	`str` or `None`	`name` of the workspace (`"special:special"`) if the special workspace was created, and `None` if it was destroyed
`monitor_name`	`str`	`name` of the monitor

activewindow: Signal¶

Emits the following Signal Data when the active window is changed:

Name	Type	Description
`window_class`	`str`	The newly active window’s `wm_class`
`window_title`	`str`	Name of the newly active window’s `title`

activewindowv2: Signal¶

Emits the following Signal Data when the active window is changed:

Name	Type	Description
`window_address`	`str`	The newly active Window’s `address`

changefloatingmode: Signal¶

Emits the following Signal Data when a window’s floating state changes:

Name	Type	Description
`window_address`	`str`	`address` of the window
`is_floating`	`bool`	`True` if the window is floating, and `False` otherwise

closelayer: Signal¶

Emits the following Signal Data when a layerSurface is unmapped:

Name	Type	Description
`namespace`	`str`	Unknown.

closewindow: Signal¶

Emits the following Signal Data when a window is closed:

Name	Type	Description
`window_address`	`str`	`address` of the closed window

configreloaded: Signal¶

Emitted upon a completed config reload.

Does not emit any Signal Data.

createworkspace: Signal¶

Emits the following Signal Data when a workspace is created:

Name	Type	Description
`workspace_name`	`str`	`name` of the created workspace

createworkspacev2: Signal¶

Emits the following Signal Data when a workspace is created:

Name	Type	Description
`workspace_id`	`int`	`id` of the created workspace
`workspace_name`	`str`	`name` of the created workspace

destroyworkspace: Signal¶

Emits the following Signal Data when a workspace is destroyed:

Name	Type	Description
`workspace_name`	`str`	`name` of the destroyed workspace

destroyworkspacev2: Signal¶

Emits the following Signal Data when a workspace is destroyed:

Name	Type	Description
`workspace_id`	`int`	`id` of the destroyed workspace
`workspace_name`	`str`	`name` of the destroyed workspace

focusedmon: Signal¶

Emits the following Signal Data when the active monitor changes:

Name	Type	Description
`monitor_name`	`str`	`name` of the newly active monitor
`workspace_name`	`str`	`name` of the newly active workspace

focusedmonv2: Signal¶

Emits the following Signal Data when the active monitor changes:

Name	Type	Description
`monitor_name`	`str`	`name` of the newly active monitor
`workspace_id`	`int`	`id` of the workspace which is now active

fullscreen: Signal¶

Emits the following Signal Data when the fullscreen state of any window changes:

Name	Type	Description
`is_fullscreen`	`bool`	`True` if fullscreen mode was activated, and `False` if fullscreen mode was deactivated

ignoregrouplock: Signal¶

Emits the following Signal Data when ignoregrouplock is toggled:

Name	Type	Description
`ignore_group_lock_enabled`	`bool`	`True` if `ignoregrouplock` was activated, and `False` if it was deactivated

lockgroups: Signal¶

Emits the following Signal Data when lockgroups is toggled:

Name	Type	Description
`lock_groups_enabled`	`bool`	`True` if `lockgroups` was activated, and `False` if it was deactivated

monitoradded: Signal¶

Emits the following Signal Data when a monitor is added:

Name	Type	Description
`monitor_name`	`str`	`name` of the newly added monitor

monitoraddedv2: Signal¶

Emits the following Signal Data when a monitor is added:

Name	Type	Description
`monitor_id`	`int`	`id` of the newly added monitor
`monitor_name`	`str`	`name` of the newly added monitor
`monitor_description`	`str`	`description` of the newly added monitor

monitorremoved: Signal¶

Emits the following Signal Data when a monitor is removed:

Name	Type	Description
`monitor_name`	`str`	`name` of the removed monitor

moveintogroup: Signal¶

Emits the following Signal Data when a window is merged into a group:

Name	Type	Description
`window_address`	`str`	`address` of the merged window

moveoutofgroup: Signal¶

Emits the following Signal Data when a window is removed from a group:

Name	Type	Description
`window_address`	`str`	`address` of the removed window

movewindow: Signal¶

Emits the following Signal Data when a window is moved to a workspace:

Name	Type	Description
`window_address`	`str`	`address` of the window which was moved
`workspace_name`	`str`	`name` of the workspace the window was moved to

movewindowv2: Signal¶

Emits the following Signal Data when a window is moved to a workspace:

Name	Type	Description
`window_address`	`str`	`address` of the window which was moved
`workspace_name`	`str`	`name` of the workspace the window was moved to
`workspace_id`	`int`	`id` of the workspace the window was moved to

moveworkspace: Signal¶

Emits the following Signal Data when a workspace is moved to a different monitor:

Name	Type	Description
`workspace_name`	`str`	`name` of the workspace which was moved
`monitor_name`	`str`	`name` of the monitor which the workspace was moved to

moveworkspacev2: Signal¶

Emits the following Signal Data when a workspace is moved to a different monitor:

Name	Type	Description
`workspace_id`	`int`	`id` of the workspace which was moved
`workspace_name`	`str`	`name` of the workspace which was moved
`monitor_name`	`str`	`name` of the monitor which the workspace was moved to

openlayer: Signal¶

Emits the following Signal Data when a layerSurface is mapped:

Name	Type	Description
`namespace`	`str`	Unknown.

openwindow: Signal¶

Emits the following Signal Data when a window is opened:

Name	Type	Description
`window_address`	`str`	`address` of the opened window
`workspace_name`	`str`	`name` of the workspace on which the window was opened
`window_class`	`str`	The opened window’s `wm_class`
`window_title`	`str`	Name of the opened window’s `title`

pin: Signal¶

Emits the following Signal Data when a window is pinned or unpinned:

Name	Type	Description
`window_address`	`str`	`address` of the pinned/unpinned window
`is_pinned`	`bool`	`True` if the window was pinned, and `False` if it was unpinned.

renameworkspace: Signal¶

Emits the following Signal Data when a workspace is renamed:

Name	Type	Description
`workspace_id`	`int`	`id` of the workspace which was renamed
`new_name`	`str`	New `name` of the workspace

screencast: Signal¶

Emits the following Signal Data when the screencopy state of a client changes:

Name	Type	Description
`screencast_enabled`	`bool`	`True` if the screencast was enabled, and `False` if it was disabled
`screencast_type`	`str`	`"MONITOR"` if the screencast was enabled for a monitor, and `"WINDOW"` if it was enabled for a window

submap: Signal¶

Emits the following Signal Data when a keybind submap changes:

Name	Type	Description
`submap_name`	`str` or `None`	Name of the new submap, or `None` if the default submap is now active

togglegroup: Signal¶

Emits the following Signal Data when the togglegroup command is used:

Name	Type	Description
`group_is_active`	`bool`	`True` if the group was created, and `False` if it was destroyed
`window_addresses`	`list[str]`	`list` of `address`es of the windows in the group

urgent: Signal¶

Emits the following Signal Data when a window requests an urgent state:

Name	Type	Description
`window_address`	`str`	`address` of the window requesting urgent state

windowtitle: Signal¶

Emits the following Signal Data when the title of a window changes:

Name	Type	Description
`window_address`	`str`	`address` of the window whose title changed

windowtitlev2: Signal¶

Emits the following Signal Data when the title of a window changes:

Name	Type	Description
`window_address`	`str`	`address` of the window whose title changed
`window_title`	`str`	`title` of the window whose title changed

workspace: Signal¶

Emits the following Signal Data when the active workspace changes (ignores mouse movements):

Name	Type	Description
`workspace_name`	`str`	`name` of the newly active workspace

workspacev2: Signal¶

Emits the following Signal Data when the active workspace changes (ignores mouse movements):

Name	Type	Description
`workspace_name`	`str`	`name` of the newly active workspace
`workspace_id`	`int`	`id` of the newly active workspace

Misc.¶

Common classes, shared among different components.

exception ParentNotFoundException¶

Bases: Exception

Raised when a component’s parent could not be found.

This exception may occur due to programming errors or race conditions, for example when a hyprpy.components.windows.Window knows the ID of the hyprpy.components.workspaces.Workspace it is on, but no workspace with that ID exists.