hyprland-schema

Typed Python schema for every Hyprland configuration option — with defaults, ranges, and descriptions. Generated from Hyprland's option-metadata source (ConfigDescriptions.hpp on v0.54.x and older, ConfigValues.cpp on v0.55.0 and newer, hyprwm/Hyprland#13817). Zero runtime dependencies — stdlib only.

Installation

pip install hyprland-schema

Usage

import hyprland_schema

# Schema version
print(hyprland_schema.HYPRLAND_VERSION)  # "v0.56.1"

# Lookup by key
border = hyprland_schema.OPTIONS_BY_KEY["general:border_size"]
print(border.type, border.default, border.min, border.max)
# int 1 0 20

# Filter by section
for opt in hyprland_schema.get_section("general"):
    print(f"{opt.name}: {opt.type} = {opt.default}")

# Filter by subsection
for opt in hyprland_schema.get_subsection("decoration", "blur"):
    print(f"{opt.name}: {opt.type} = {opt.default}")

# Iterate all options
for opt in hyprland_schema.OPTIONS:
    print(f"{opt.key}: {opt.type}")

# Export as JSON
json_str = hyprland_schema.get_json()

Loading older Hyprland versions

import hyprland_schema

# List all bundled versions (newest first)
print(hyprland_schema.available_versions())

# Load schema for a specific version
schema = hyprland_schema.load("v0.54.2")
print(schema.version, len(schema.options))

# Schema objects have the same filtering API
for opt in schema.get_section("general"):
    print(f"{opt.name}: {opt.type} = {opt.default}")

# Lookup on a Schema
border = schema.options_by_key["general:border_size"]

The version is accepted with or without the v prefix, so the bare number hyprctl reports can be passed straight through; schema.version reports the tag spelling either way.

Resolution order for load():

  1. Latest bundled version — instant (pre-parsed).
  2. Older bundled version — reconstructed via reverse migrations.
  3. Disk cache at ~/.cache/hyprland-schema/ — no network needed.
  4. GitHub fetch — downloads ConfigValues.cpp (or, for older tags, ConfigDescriptions.hpp) and parses it.

API

Symbol Type / Signature Description
HYPRLAND_VERSION str Hyprland tag the schema was built from
OPTIONS tuple[HyprOption, ...] All configuration options
OPTIONS_BY_KEY dict[str, HyprOption] Lookup by dotted key
get_section(s) (str) -> list[HyprOption] Options in a top-level section
get_subsection(s, sub) (str, str) -> list[HyprOption] Options in a nested subsection
get_json() (*, indent=2) -> str Full schema as a JSON string
load(version) (str) -> Schema Load schema for a specific Hyprland version
available_versions() () -> list[str] All bundled versions, newest first
MigrationError Exception Raised when a version migration fails

Schema

Schema is a frozen dataclass returned by load(). It holds options for a specific Hyprland version.

Attribute / Method Type / Signature Description
version str Hyprland version tag
options tuple[HyprOption, ...] All options for this version
options_by_key dict[str, HyprOption] Lookup by dotted key
get_section(s) (str) -> list[HyprOption] Options in a top-level section
get_subsection(s, sub) (str, str) -> list[HyprOption] Options in a nested subsection
get_json() (*, indent=2) -> str Schema as a JSON string

HyprOption fields

Field Type Description
key str "general:border_size"
section tuple[str, ...] ("general",)
name str "border_size"
description str Human-readable text
type str bool, int, float, string, color, gradient, vec2, choice, cssgap, font_weight
default Any Default value
min int | float | None For int/float types
max int | float | None For int/float types
enum_values tuple[str, ...] | None For choice type
default_str str | None Human-readable default for choice type
default_min tuple[float, ...] | None For vec2 type
default_max tuple[float, ...] | None For vec2 type

Requirements

  • Python >= 3.12

License

MIT

Project links

Data verified by PyPI on Jul 31, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for BlueManCZ from gravatar.com BlueManCZ

GitHub Statistics

Data verified by PyPI on Jul 31, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.12

Tags

compositor hyprland schema wayland

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hyprland_schema-0.7.1.tar.gz (47.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

hyprland_schema-0.7.1-py3-none-any.whl (53.3 kB view details)

Uploaded Python 3

File details

Details for the file hyprland_schema-0.7.1.tar.gz.

File metadata

  • Download URL: hyprland_schema-0.7.1.tar.gz
  • Upload date:
  • Size: 47.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hyprland_schema-0.7.1.tar.gz
Algorithm Hash digest
SHA256 e73d4a19aece1df602c52b2985df35f6c8bc584b0fa7058ea56e1aab9fc01233
MD5 d9a396a160f6b5a4c66ff471b72d142b
BLAKE2b-256 af4811d41c3740072c309fd1eb61dfbfe4f9897a2b1124c1f10cb17a18dc8172

See more details on using hashes here.

Provenance

The following attestation bundles were made for hyprland_schema-0.7.1.tar.gz:

Publisher: publish.yml on BlueManCZ/hyprland-schema

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hyprland_schema-0.7.1-py3-none-any.whl.

File metadata

  • Download URL: hyprland_schema-0.7.1-py3-none-any.whl
  • Upload date:
  • Size: 53.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hyprland_schema-0.7.1-py3-none-any.whl
Algorithm Hash digest
SHA256 97637f24ac593232e388f99b079c4166cc8e321775e9097470f3b467cda551dc
MD5 c737d7313c5a613e97ef44697c003dc3
BLAKE2b-256 0f2466d5aad64573e38a5ec31820f3a920ff6a79364a329dba7f3e708bced536

See more details on using hashes here.

Provenance

The following attestation bundles were made for hyprland_schema-0.7.1-py3-none-any.whl:

Publisher: publish.yml on BlueManCZ/hyprland-schema

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.7.1 This release

2 files

0.7.0

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.0

2 files

0.4.0

2 files

0.3.0

2 files

0.2.0

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page