hyprland-schema 0.1.0__tar.gz

hyprland_schema-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.idea/
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+.venv/
+.pytest_cache/
+.python-version

hyprland_schema-0.1.0/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Ivo Šmerek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

hyprland_schema-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: hyprland-schema
+Version: 0.1.0
+Summary: Typed Python schema for every Hyprland configuration option
+Project-URL: Repository, https://github.com/BlueManCZ/hyprland-schema
+License-Expression: MIT
+License-File: LICENSE
+Keywords: compositor,hyprland,schema,wayland
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Desktop Environment
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# hyprland-schema
+
+Typed Python schema for every Hyprland configuration option — with defaults,
+ranges, and descriptions. Generated from Hyprland's
+[ConfigDescriptions.hpp](https://github.com/hyprwm/Hyprland/blob/main/src/config/ConfigDescriptions.hpp).
+Zero runtime dependencies — stdlib only.
+
+## Installation
+
+```
+pip install hyprland-schema
+```
+
+## Usage
+
+```python
+import hyprland_schema
+
+# Schema version
+print(hyprland_schema.HYPRLAND_VERSION)  # "v0.54.2"
+
+# 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
+
+```python
+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"]
+```
+
+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 `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          |
+
+### 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` |
+| `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

hyprland_schema-0.1.0/README.md

@@ -0,0 +1,122 @@
+# hyprland-schema
+
+Typed Python schema for every Hyprland configuration option — with defaults,
+ranges, and descriptions. Generated from Hyprland's
+[ConfigDescriptions.hpp](https://github.com/hyprwm/Hyprland/blob/main/src/config/ConfigDescriptions.hpp).
+Zero runtime dependencies — stdlib only.
+
+## Installation
+
+```
+pip install hyprland-schema
+```
+
+## Usage
+
+```python
+import hyprland_schema
+
+# Schema version
+print(hyprland_schema.HYPRLAND_VERSION)  # "v0.54.2"
+
+# 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
+
+```python
+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"]
+```
+
+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 `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          |
+
+### 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` |
+| `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

hyprland_schema-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "hyprland-schema"
+version = "0.1.0"
+description = "Typed Python schema for every Hyprland configuration option"
+requires-python = ">=3.12"
+license = "MIT"
+readme = "README.md"
+keywords = ["hyprland", "schema", "wayland", "compositor"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Intended Audience :: Developers",
+    "Topic :: Desktop Environment",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/BlueManCZ/hyprland-schema"
+
+[dependency-groups]
+dev = ["pyright>=1.1", "pytest>=9.0", "ruff>=0.15"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+only-packages = true
+
+[tool.hatch.build.targets.sdist]
+exclude = ["tests/"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]

hyprland_schema-0.1.0/src/hyprland_schema/__init__.py

@@ -0,0 +1,73 @@
+"""Hyprland configuration option schema."""
+
+import functools
+from types import MappingProxyType
+
+from hyprland_schema._data import HYPRLAND_VERSION as HYPRLAND_VERSION
+from hyprland_schema._data import OPTIONS as OPTIONS
+from hyprland_schema._model import HyprOption as HyprOption
+from hyprland_schema._schema import Schema as Schema
+
+__all__ = [
+    "HYPRLAND_VERSION",
+    "HyprOption",
+    "OPTIONS",
+    "OPTIONS_BY_KEY",
+    "Schema",
+    "available_versions",
+    "get_json",
+    "get_section",
+    "get_subsection",
+    "load",
+]
+
+
+@functools.cache
+def _get_latest_schema() -> Schema:
+    return Schema(version=HYPRLAND_VERSION, options=OPTIONS)
+
+
+OPTIONS_BY_KEY: MappingProxyType[str, HyprOption] = _get_latest_schema().options_by_key
+
+
+def get_section(section: str) -> list[HyprOption]:
+    """Return all options whose top-level section matches."""
+    return _get_latest_schema().get_section(section)
+
+
+def get_subsection(section: str, subsection: str) -> list[HyprOption]:
+    """Return all options in a nested subsection."""
+    return _get_latest_schema().get_subsection(section, subsection)
+
+
+def get_json(*, indent: int | None = 2) -> str:
+    """Return the full schema as a JSON string.
+
+    Produces the same format as the schema.json that the generator emits.
+    """
+    return _get_latest_schema().get_json(indent=indent)
+
+
+@functools.lru_cache(maxsize=32)
+def load(version: str) -> Schema:
+    """Load the schema for a specific Hyprland version.
+
+    Resolution order:
+    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. Download from GitHub — fetches ConfigDescriptions.hpp and parses it.
+
+    Results are cached in memory for repeated calls.
+    """
+    from hyprland_schema._migration import build_options
+
+    opts = build_options(version)
+    return Schema(version=version, options=opts)
+
+
+def available_versions() -> list[str]:
+    """Return all bundled Hyprland versions, newest first."""
+    from hyprland_schema._migrations._registry import VERSIONS
+
+    return list(VERSIONS)