https://github.com/sukramj/openccu-loom-types
Generated Pydantic v2 models and enum types for the openccu-loom REST + WebSocket contract
https://github.com/sukramj/openccu-loom-types
code-generation home-assistant homematic homematicip openapi pydantic python rest-api type-hints websocket
Last synced: 21 days ago
JSON representation
Generated Pydantic v2 models and enum types for the openccu-loom REST + WebSocket contract
- Host: GitHub
- URL: https://github.com/sukramj/openccu-loom-types
- Owner: SukramJ
- License: mit
- Created: 2026-05-24T16:21:34.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-27T09:44:25.000Z (22 days ago)
- Last Synced: 2026-06-27T11:20:31.105Z (22 days ago)
- Topics: code-generation, home-assistant, homematic, homematicip, openapi, pydantic, python, rest-api, type-hints, websocket
- Language: Python
- Size: 171 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- License: LICENSE
Awesome Lists containing this project
README
# openccu-loom-types
Generated Pydantic models + enum definitions for the openccu-loom
REST + WebSocket contract. Sister-repo to the
[openccu-loom daemon](https://github.com/SukramJ/openccu-loom);
publishable as `openccu-loom-types` on PyPI.
## What this package provides
- `openccu_loom_types.enums` — every enum from the daemon's
`pkg/hmenum`. Each enum is a `str`-typed Python `Enum` whose values
match the wire strings the CCU emits. Source of truth:
`assets/schemas/enums.json` in the openccu-loom repo.
- `openccu_loom_types.rest` — Pydantic models for the REST surface.
Generated from `assets/openapi.yaml` via `datamodel-code-generator`.
- `openccu_loom_types.ws` — Pydantic models for the WebSocket
envelope + push payloads. Generated from the same OpenAPI document
(the WS envelope schemas live in `components.schemas` per ADR-0020).
## Why this exists (asks.md C1 + C3)
Higher-level clients (`openccu-loom-client`, the future
homematicip_local refactor) need stable typed bindings against the
daemon. Without a published types package each consumer would
duplicate the model code and drift away from the daemon's wire
contract. This package is the single import every Python consumer
shares — version-pinned and CI-rebuilt on every openccu-loom release.
## Regeneration workflow
Set `OPENCCU_LOOM_REPO` to a local checkout of the daemon repo
(default: `../openccu-loom`):
```sh
# Step 1 — make sure the daemon repo's schema export is fresh:
make -C "$OPENCCU_LOOM_REPO" export-schemas
# Step 2 — regenerate this package's models:
make generate
```
The two-step split keeps the daemon repo authoritative; this package
never re-parses Go source.
### Tooling required
- Python >= 3.11
- `datamodel-code-generator` >= 0.25 (for REST + WS Pydantic models)
Install both with `pip install -e '.[dev]'`.
## Versioning & contract identity
The package version (`const.VERSION`) is independent of the daemon
version; the regeneration workflow bumps the patch number on every
daemon release. The daemon coupling is carried by two stamped
constants in `const.py` (written by `make generate` →
`scripts/stamp_const.py`):
- `SCHEMA_DIGEST` — canonical digest of the daemon's contract assets
these types were generated from (definition: daemon ADR-0028).
Clients compare it against `GET /api/v1/info`.`schema_digest` to
verify exact type/daemon parity at connect time.
- `DAEMON_API_VERSION` — the daemon's `api_version` at generation
time. Minor bumps add fields without breaking existing consumers;
major bumps remove or rename payload fields, scopes, or
capabilities — see ADR-0020 in the daemon repo.
Regeneration and release are automated end to end. The daemon's
release workflow fires a `repository_dispatch` (`daemon-release`) at
this repo, which drives this chain:
1. `regenerate-on-daemon-release` checks out the daemon at the released
tag, regenerates all modules, stamps the constants, bumps the
version, seeds a baseline changelog section, opens a PR from a
`regen/daemon-` branch, and enables auto-merge.
2. `ci` runs on the PR: `Test` (the suite) and `Regen clean` (re-runs
`make generate` against the branch's daemon tag and fails on any
drift, so hand-edits to generated modules are caught).
3. Once the required checks are green the PR squash-merges;
`tag-on-regen-merge` then pushes `v`.
4. The tag triggers `release-on-tag` → GitHub Release →
`python-publish` → PyPI.
Manual fallback: `workflow_dispatch` with the tag, or the local
two-step flow above.
### CI / release setup
The automation needs three one-time repository settings; without them
the chain stops after step 1:
- A **`RELEASE_PAT`** secret — a fine-grained PAT (or GitHub App token)
with `contents: write` + `pull-requests: write`. The regen PR and the
release tag are pushed with it, because a branch/PR/tag created via
the default `GITHUB_TOKEN` does **not** trigger the downstream CI and
release workflows (GitHub's recursive-workflow guard).
- **Branch protection** on `main` requiring the `Test` and
`Regen clean` status checks — auto-merge waits on these.
- **Allow auto-merge** enabled in the repository settings.
## What this package does NOT contain
- HTTP / WebSocket transport — see `openccu-loom-client`
(when published) for the higher-level client.
- Any business logic — types only.
- Async helpers — types are framework-neutral.
## License
MIT. See [LICENSE](./LICENSE).