Data Models¶

Hyprpy retrieves data about Hyprland components by talking to Hyprland’s CommandSocket. The data retrieved from the socket arrives as JSON. This JSON data needs to be parsed, validated, and converted into python objects with proper attribute names.

Hyprpy leverages Pydantic under the hood to parse socket data into python objects. This enables automatic model validation and serialization/deserialization of data, based purely on class structure and type annotations.

Data model classes¶

Data classes used for parsing, validating and storing JSON output received from the Hyprland command socket.

Classes:

WindowData: data for Hyprland windows.
WorkspaceData: data for Hyprland workspaces.
MonitorData: data for Hyprland monitors.
InstanceData: data for Hyprland instances.

class WindowData(*, address: str, mapped: bool, hidden: bool, position_x: int, position_y: int, width: int, height: int, workspace_id: int, workspace_name: str, floating: bool, monitor: int, title: str, initialClass: str, initialTitle: str, pid: int, xwayland: bool, pinned: bool, fullscreen: int, **extra_data: Any)¶

Bases: BaseModel

Deserialization and validation of hyprctl window (client) data.

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.

class WorkspaceData(*, id: int, name: str, monitor: str, lastwindow: str, lastwindowtitle: str, windows: int, hasfullscreen: bool)¶

Bases: BaseModel

Deserialization and validation of hyprctl workspace data.

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.

class MonitorData(*, id: int, name: str, description: str, make: str, model: str, serial: str, width: int, height: int, refreshRate: float, x: int, y: int, active_workspace_id: int, active_workspace_name: str, reserved: List[int], scale: float, transform: int, focused: bool, dpmsStatus: bool, vrr: bool)¶

Bases: BaseModel

Deserialization and validation of hyprctl monitor data.

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.

class InstanceData(*, signature: str)¶

Bases: BaseModel

Deserialization and validation of hyprctl instance data.

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

Data model background¶

The data module provides Pydantic-based data model classes designed for defining the data structure, validation, and serialization/deserialization of the various Hyprland components. These model classes act as the central point of data transformation, ensuring that data retrieved from Hyprland is correctly structured and validated.

Utility:

Through Pydantic, the library offers a robust mechanism for parsing, validating, and serializing JSON data. The source of this JSON data is primarily the CommandSocket which interacts with Hyprland to retrieve current state and event information.

Notably, these data models not only handle validation but also perform renaming of JSON properties to provide a more Pythonic interface.

Serialization:

The instantiated data model objects are easily serializable back into JSON, providing flexibility in both consuming Hyprland data and in using it for further operations.

Example:

>>> from hyprpy.data.models import WindowData

>>> # Output from `hyprctl -j clients` for example
>>> window_json_str = '''
    {
        "address": "0x1981f40",
        "mapped": true,
        "hidden": false,
        "at": [11, 11],
        "size": [1344, 746],
        "workspace": {
            "id": 1,
            "name": "1"
        },
        "floating": false,
        "monitor": 0,
        "class": "kitty",
        "title": "python ~/d/p/src",
        "initialClass": "kitty",
        "initialTitle": "fish",
        "pid": 1782,
        "xwayland": false,
        "pinned": false,
        "fullscreen": 0,
        "grouped": [],
        "swallowing": null
    }
    '''

>>> # Deserialize and validate JSON, creating an object
>>> window_data = WindowData.model_validate_json(window_json_str)

>>> # Access window data properties
>>> window_data.pid
1782
>>> window_data.floating
False

>>> # Serialize back into JSON
>>> print(window_data.model_dump_json(indent=2))
{
  "address": "0x1981f40",
  "is_mapped": true,
  "is_hidden": false,
  "position_x": 11,
  "position_y": 11,
  "width": 1344,
  "height": 746,
  "workspace_id": 1,
  "workspace_name": "1",
  "is_floating": false,
  "monitor_id": 0,
  "wm_class": "kitty",
  "title": "python ~/d/p/src",
  "initial_wm_class": "kitty",
  "initial_title": "fish",
  "pid": 1782,
  "is_xwayland": false,
  "is_pinned": false,
  "is_fullscreen": 0,
}

Component Data validators¶

Custom validators used for type annotations and data model instance validation.

non_empty_string(value: str) → str¶: Ensures that value is a non-empty string.

valid_hex_string(value: str) → str¶: Ensures that value is a valid hexadecimal string.