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

The client is published to PyPI as hypercolor (alpha):

uv add hypercolor

For development inside this repository:

uv sync

Quick Start

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.

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.

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

import asyncio

from hypercolor import HypercolorClient


async def main() -> None:
    async with HypercolorClient() as client:
        effects = await client.get_effects()
        borealis = next(effect for effect in effects if effect.name == "Borealis")

        await client.apply_effect(
            borealis.id,
            controls={"speed": 5, "palette": "SilkCircuit"},
            transition="cut",
        )


asyncio.run(main())

Control Surfaces

Control surfaces are dynamic device and driver settings. Request helpers accept normal Python values and return the canonical API resource contracts.

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.surface_id,
            {
                "enabled": True,
                "brightness": 0.88,
            },
        )

        await client.invoke_control_action(
            surface.surface_id,
            "identify",
            {"duration_ms": 750},
        )


asyncio.run(main())

Inside an async function, typed daemon values can pass through directly:

async with HypercolorClient() as client:
    await client.set_control_values(
        "device:keyboard",
        {"accent": {"kind": "color_rgb", "value": [128, 255, 234]}},
    )

WebSocket Events

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.

Event and metrics messages carry mono_us, the publication time in microseconds on the daemon's monotonic clock, beside the wall-clock timestamp. Order and time messages with mono_us: it never moves backwards when the host clock steps. stream.hello.clock_epoch names the clock, and a reconnect that reports a different epoch means the daemon restarted and old stamps no longer line up. Command responses carry mono_us too, read after the command finished, so it falls inside each request's round trip.

Development

Use the local recipes from python/:

just verify
just fix
just generate
just generate-check

The full project recipe also runs the Python gate:

just python-verify

Manual equivalents:

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