hypercolor 0.2.0a1__tar.gz

hypercolor-0.2.0a1/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: hypercolor
+Version: 0.2.0a1
+Summary: Async Python client for the Hypercolor daemon
+Keywords: hypercolor,rgb,lighting,websocket
+Author: Stefanie Jane
+Author-email: Stefanie Jane <stef@hyperbliss.tech>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: attrs>=25.4.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: msgspec>=0.21.1
+Requires-Dist: websockets>=16.0
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/hyperb1iss/hypercolor
+Project-URL: Repository, https://github.com/hyperb1iss/hypercolor/tree/main/python
+Project-URL: Issues, https://github.com/hyperb1iss/hypercolor/issues
+Description-Content-Type: text/markdown
+
+# Hypercolor Python
+
+Async Python client and WebSocket helpers for the Hypercolor daemon.
+
+This package lives inside the main Hypercolor repository at `python/`. It is a
+standalone uv project, so Python contributors can work here without touching the
+Rust workspace.
+
+Generation details live in `../docs/development/CLIENT_GENERATION.md`.
+
+## Install
+
+```bash
+uv sync
+```
+
+The package is source-only for the v0.1 launch and is not published to PyPI yet.
+Once it is published, apps should depend on it normally:
+
+```bash
+uv add hypercolor
+```
+
+## Quick Start
+
+```python
+import asyncio
+
+from hypercolor import HypercolorClient
+
+
+async def main() -> None:
+    async with HypercolorClient() as client:
+        status = await client.get_status()
+        devices = await client.get_devices()
+
+    print(status.running)
+    print([device.name for device in devices])
+
+
+asyncio.run(main())
+```
+
+The async client is the primary API. Use `SyncHypercolorClient` for scripts or
+small tools that are not already running an event loop.
+
+```python
+from hypercolor import SyncHypercolorClient
+
+with SyncHypercolorClient() as client:
+    print(client.get_status().global_brightness)
+```
+
+## Drivers
+
+Driver inventory includes module capabilities, config keys, optional control
+surface paths, and protocol catalogs for HAL-backed modules.
+
+```python
+import asyncio
+
+from hypercolor import HypercolorClient
+
+
+async def main() -> None:
+    async with HypercolorClient() as client:
+        for driver in await client.get_drivers():
+            if driver.descriptor.capabilities.protocol_catalog:
+                print(driver.descriptor.display_name)
+                print([protocol.display_name for protocol in driver.protocols])
+
+
+asyncio.run(main())
+```
+
+## Effects
+
+```python
+import asyncio
+
+from hypercolor import HypercolorClient
+
+
+async def main() -> None:
+    async with HypercolorClient() as client:
+        effects = await client.get_effects()
+        aurora = next(effect for effect in effects if effect.name == "Aurora")
+
+        await client.apply_effect(
+            aurora.id,
+            controls={"speed": 72, "palette": "silkcircuit"},
+            transition={"type": "fade", "duration_ms": 400},
+        )
+
+
+asyncio.run(main())
+```
+
+## Control Surfaces
+
+Control surfaces are dynamic device and driver settings. The generated OpenAPI
+models stay private; the public client accepts normal Python values.
+
+```python
+import asyncio
+
+from hypercolor import HypercolorClient
+
+
+async def main() -> None:
+    async with HypercolorClient() as client:
+        surface = await client.get_device_controls("keyboard")
+
+        await client.set_control_values(
+            surface.id,
+            {
+                "enabled": True,
+                "brightness": 88,
+            },
+            expected_revision=surface.revision,
+        )
+
+        await client.invoke_control_action(
+            surface.id,
+            "identify",
+            {"duration_ms": 750},
+        )
+
+
+asyncio.run(main())
+```
+
+Inside an async function, typed daemon values can pass through directly:
+
+```python
+async with HypercolorClient() as client:
+    await client.set_control_values(
+        "device:keyboard",
+        {"accent": {"kind": "color_rgb", "value": [128, 255, 234]}},
+    )
+```
+
+## WebSocket Events
+
+```python
+import asyncio
+
+from hypercolor import HypercolorClient
+from hypercolor.websocket import EventMessage, MetricsMessage
+
+
+async def main() -> None:
+    async with HypercolorClient() as client:
+        async with client.events() as stream:
+            await stream.subscribe("events", "metrics")
+
+            async for message in stream:
+                if isinstance(message, EventMessage):
+                    print(message.event, message.data)
+                elif isinstance(message, MetricsMessage):
+                    print(message.data)
+
+
+asyncio.run(main())
+```
+
+Binary frame, spectrum, and canvas messages are decoded into dataclasses, so
+callers do not need to parse the wire format.
+
+## Development
+
+Use the local recipes from `python/`:
+
+```bash
+just verify
+just fix
+just generate
+just generate-check
+```
+
+The full project recipe also runs the Python gate:
+
+```bash
+just python-verify
+```
+
+Manual equivalents:
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run ty check
+uv run python scripts/generate_ws_protocol.py --check
+uv run pytest
+uv run python scripts/generate_openapi_client.py --check
+```

hypercolor-0.2.0a1/README.md

@@ -0,0 +1,196 @@
+# Hypercolor Python
+
+Async Python client and WebSocket helpers for the Hypercolor daemon.
+
+This package lives inside the main Hypercolor repository at `python/`. It is a
+standalone uv project, so Python contributors can work here without touching the
+Rust workspace.
+
+Generation details live in `../docs/development/CLIENT_GENERATION.md`.
+
+## Install
+
+```bash
+uv sync
+```
+
+The package is source-only for the v0.1 launch and is not published to PyPI yet.
+Once it is published, apps should depend on it normally:
+
+```bash
+uv add hypercolor
+```
+
+## Quick Start
+
+```python
+import asyncio
+
+from hypercolor import HypercolorClient
+
+
+async def main() -> None:
+    async with HypercolorClient() as client:
+        status = await client.get_status()
+        devices = await client.get_devices()
+
+    print(status.running)
+    print([device.name for device in devices])
+
+
+asyncio.run(main())
+```
+
+The async client is the primary API. Use `SyncHypercolorClient` for scripts or
+small tools that are not already running an event loop.
+
+```python
+from hypercolor import SyncHypercolorClient
+
+with SyncHypercolorClient() as client:
+    print(client.get_status().global_brightness)
+```
+
+## Drivers
+
+Driver inventory includes module capabilities, config keys, optional control
+surface paths, and protocol catalogs for HAL-backed modules.
+
+```python
+import asyncio
+
+from hypercolor import HypercolorClient
+
+
+async def main() -> None:
+    async with HypercolorClient() as client:
+        for driver in await client.get_drivers():
+            if driver.descriptor.capabilities.protocol_catalog:
+                print(driver.descriptor.display_name)
+                print([protocol.display_name for protocol in driver.protocols])
+
+
+asyncio.run(main())
+```
+
+## Effects
+
+```python
+import asyncio
+
+from hypercolor import HypercolorClient
+
+
+async def main() -> None:
+    async with HypercolorClient() as client:
+        effects = await client.get_effects()
+        aurora = next(effect for effect in effects if effect.name == "Aurora")
+
+        await client.apply_effect(
+            aurora.id,
+            controls={"speed": 72, "palette": "silkcircuit"},
+            transition={"type": "fade", "duration_ms": 400},
+        )
+
+
+asyncio.run(main())
+```
+
+## Control Surfaces
+
+Control surfaces are dynamic device and driver settings. The generated OpenAPI
+models stay private; the public client accepts normal Python values.
+
+```python
+import asyncio
+
+from hypercolor import HypercolorClient
+
+
+async def main() -> None:
+    async with HypercolorClient() as client:
+        surface = await client.get_device_controls("keyboard")
+
+        await client.set_control_values(
+            surface.id,
+            {
+                "enabled": True,
+                "brightness": 88,
+            },
+            expected_revision=surface.revision,
+        )
+
+        await client.invoke_control_action(
+            surface.id,
+            "identify",
+            {"duration_ms": 750},
+        )
+
+
+asyncio.run(main())
+```
+
+Inside an async function, typed daemon values can pass through directly:
+
+```python
+async with HypercolorClient() as client:
+    await client.set_control_values(
+        "device:keyboard",
+        {"accent": {"kind": "color_rgb", "value": [128, 255, 234]}},
+    )
+```
+
+## WebSocket Events
+
+```python
+import asyncio
+
+from hypercolor import HypercolorClient
+from hypercolor.websocket import EventMessage, MetricsMessage
+
+
+async def main() -> None:
+    async with HypercolorClient() as client:
+        async with client.events() as stream:
+            await stream.subscribe("events", "metrics")
+
+            async for message in stream:
+                if isinstance(message, EventMessage):
+                    print(message.event, message.data)
+                elif isinstance(message, MetricsMessage):
+                    print(message.data)
+
+
+asyncio.run(main())
+```
+
+Binary frame, spectrum, and canvas messages are decoded into dataclasses, so
+callers do not need to parse the wire format.
+
+## Development
+
+Use the local recipes from `python/`:
+
+```bash
+just verify
+just fix
+just generate
+just generate-check
+```
+
+The full project recipe also runs the Python gate:
+
+```bash
+just python-verify
+```
+
+Manual equivalents:
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run ty check
+uv run python scripts/generate_ws_protocol.py --check
+uv run pytest
+uv run python scripts/generate_openapi_client.py --check
+```

hypercolor-0.2.0a1/pyproject.toml

@@ -0,0 +1,152 @@
+[build-system]
+requires = ["uv_build>=0.11.18,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "hypercolor"
+version = "0.2.0a1"
+description = "Async Python client for the Hypercolor daemon"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.13"
+authors = [{ name = "Stefanie Jane", email = "stef@hyperbliss.tech" }]
+keywords = ["hypercolor", "rgb", "lighting", "websocket"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "attrs>=25.4.0",
+    "httpx>=0.28.1",
+    "msgspec>=0.21.1",
+    "websockets>=16.0",
+]
+
+[dependency-groups]
+dev = [
+    { include-group = "lint" },
+    { include-group = "test" },
+    { include-group = "types" },
+]
+generate = [
+    "openapi-python-client==0.29.0",
+]
+lint = [
+    "ruff>=0.15.15",
+]
+test = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.1.0",
+    "respx>=0.23.1",
+]
+types = [
+    "ty>=0.0.42",
+]
+
+[project.urls]
+Homepage = "https://github.com/hyperb1iss/hypercolor"
+Repository = "https://github.com/hyperb1iss/hypercolor/tree/main/python"
+Issues = "https://github.com/hyperb1iss/hypercolor/issues"
+
+[tool.uv]
+package = true
+default-groups = ["dev"]
+
+[tool.uv.build-backend]
+source-include = ["tests/**"]
+
+[tool.ruff]
+line-length = 99
+target-version = "py313"
+src = ["scripts", "src", "tests"]
+extend-exclude = ["src/hypercolor/_generated"]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint]
+select = [
+    "ASYNC",
+    "B",
+    "BLE",
+    "C4",
+    "DTZ",
+    "E",
+    "ERA",
+    "F",
+    "G",
+    "I",
+    "N",
+    "PL",
+    "PT",
+    "RET",
+    "RSE",
+    "RUF",
+    "S",
+    "SIM",
+    "TRY",
+    "UP",
+    "W",
+]
+ignore = [
+    "COM812",
+    "E501",
+    "ISC001",
+    "PLR0913",
+    "PLR2004",
+    "S101",
+    "TRY003",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"scripts/**/*.py" = ["S603", "S607"]
+"tests/**/*.py" = ["PLR2004", "S101"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["hypercolor"]
+combine-as-imports = true
+
+[tool.ty.environment]
+python-version = "3.13"
+
+[tool.ty.src]
+include = ["scripts/**/*.py", "src/**/*.py", "tests/**/*.py"]
+exclude = ["src/hypercolor/_generated/**"]
+
+[tool.ty.terminal]
+output-format = "concise"
+
+[[tool.ty.overrides]]
+include = ["tests/**"]
+
+[tool.ty.overrides.rules]
+possibly-unresolved-reference = "warn"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+    "-v",
+]
+filterwarnings = [
+    "error",
+]
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+parallel = true
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 85

hypercolor-0.2.0a1/src/hypercolor/__init__.py

@@ -0,0 +1,35 @@
+"""Public API for hypercolor-python."""
+
+from .client import HypercolorClient
+from .exceptions import (
+    HypercolorApiError,
+    HypercolorAuthenticationError,
+    HypercolorConflictError,
+    HypercolorConnectionError,
+    HypercolorError,
+    HypercolorNotFoundError,
+    HypercolorPreconditionError,
+    HypercolorRateLimitError,
+    HypercolorUnavailableError,
+    HypercolorValidationError,
+)
+from .sync_client import SyncHypercolorClient
+from .websocket import HypercolorEventStream
+
+__all__ = [
+    "HypercolorApiError",
+    "HypercolorAuthenticationError",
+    "HypercolorClient",
+    "HypercolorConflictError",
+    "HypercolorConnectionError",
+    "HypercolorError",
+    "HypercolorEventStream",
+    "HypercolorNotFoundError",
+    "HypercolorPreconditionError",
+    "HypercolorRateLimitError",
+    "HypercolorUnavailableError",
+    "HypercolorValidationError",
+    "SyncHypercolorClient",
+]
+
+__version__ = "0.2.0a1"

hypercolor-0.2.0a1/src/hypercolor/_generated/GENERATED.md

@@ -0,0 +1,4 @@
+# Generated Hypercolor OpenAPI Client
+
+This private package is generated by `python/scripts/generate_openapi_client.py`.
+Do not edit these files by hand.

hypercolor-0.2.0a1/src/hypercolor/_generated/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing hypercolor-daemon"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

hypercolor-0.2.0a1/src/hypercolor/_generated/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

hypercolor-0.2.0a1/src/hypercolor/_generated/api/attachments/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""