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 = shell.get_env_var_or_fail('HYPRLAND_INSTANCE_SIGNATURE'))¶

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.

signal_workspace_created: Signal¶: 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¶: 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¶: 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¶: 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¶: 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¶: 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.

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.