{"id":50950131,"url":"https://github.com/ronaldvdmeer/python-duco-connectivity","last_synced_at":"2026-06-18T00:32:09.912Z","repository":{"id":356610024,"uuid":"1233262742","full_name":"ronaldvdmeer/python-duco-connectivity","owner":"ronaldvdmeer","description":"This is a small async client for the unauthenticated local Duco HTTP endpoints that were validated during initial development. The library keeps its public models close to the API payload shape and is intended to stay reusable outside Home Assistant.","archived":false,"fork":false,"pushed_at":"2026-05-17T11:19:10.000Z","size":297,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-17T11:30:17.212Z","etag":null,"topics":["duco","duco-api","ducobox","home-assistant","python"],"latest_commit_sha":null,"homepage":"https://github.com/ronaldvdmeer/python-duco-connectivity","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ronaldvdmeer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-08T19:11:45.000Z","updated_at":"2026-05-17T11:05:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ronaldvdmeer/python-duco-connectivity","commit_stats":null,"previous_names":["ronaldvdmeer/python-duco-connectivity"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ronaldvdmeer/python-duco-connectivity","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronaldvdmeer%2Fpython-duco-connectivity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronaldvdmeer%2Fpython-duco-connectivity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronaldvdmeer%2Fpython-duco-connectivity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronaldvdmeer%2Fpython-duco-connectivity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ronaldvdmeer","download_url":"https://codeload.github.com/ronaldvdmeer/python-duco-connectivity/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronaldvdmeer%2Fpython-duco-connectivity/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34471638,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["duco","duco-api","ducobox","home-assistant","python"],"created_at":"2026-06-18T00:32:09.037Z","updated_at":"2026-06-18T00:32:09.893Z","avatar_url":"https://github.com/ronaldvdmeer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# python-duco-connectivity\n\nAsync Python client for the local Duco HTTP API.\n\n`python-duco-connectivity` is a small async client for the unauthenticated\nlocal Duco HTTP endpoints that were validated during initial development. The\nlibrary keeps its public models close to the API payload shape and is intended\nto stay reusable outside Home Assistant.\n\n## Installation\n\nUntil the first PyPI release is published, install directly from GitHub:\n\n```bash\npip install git+https://github.com/ronaldvdmeer/python-duco-connectivity.git\n```\n\nAfter the package is published on PyPI, install it with:\n\n```bash\npip install python-duco-connectivity\n```\n\nThe package also installs a `duco-probe` CLI and supports module execution for\nquick function probes against a local Duco box. When you are not running inside\nan activated virtual environment, use the explicit `.venv/bin/...` paths shown\nin the development examples below.\n\n## Current scope\n\n- HTTP only\n- asynchronous communication via `aiohttp`\n- typed stable config families for the documented `/config` branches\n- typed models that stay close to the API response shape\n- preserved `raw_payload` data on typed response models for forward compatibility\n\nDiagnostic subsystem reads now keep raw component and status strings from\n`Diag.SubSystems`, so future subsystem names or status values remain available\nto downstream consumers without parse fallbacks or product-specific filtering.\n\n## Getting started\n\n```python\nimport asyncio\n\nimport aiohttp\n\nfrom duco_connectivity import DucoClient\n\n\nasync def main() -\u003e None:\n    async with aiohttp.ClientSession() as session:\n        client = DucoClient(session, \"192.168.1.10\")\n        api_info = await client.async_get_api_info()\n        nodes = await client.async_get_nodes_overview()\n\n        print(api_info.public_api_version)\n        print([node.node_id for node in nodes])\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n## Documentation map\n\nStart with `docs/api-reference.md` when you want a compact inventory of the\npublic client methods, exports, compatibility aliases, and construction rules.\n\n- `docs/api-reference.md` for the central public API inventory\n- `docs/cli.md` for the function probe CLI and shell examples\n- `docs/config.md` for system, node, and zone config reads and writes\n- `docs/live-testing.md` for local opt-in tests against a real Duco device\n- `docs/replay-testing.md` for local sample validation against ignored raw API\n  captures\n- `docs/actions.md` for action discovery and execution\n- `docs/nodes.md` for node models and node information readers\n- `docs/public-api-boundaries.md` for the typed-model contract and raw escape\n  hatch boundaries\n- `docs/zones.md` for zone and group info and config readers\n- `docs/ventilation-states.md` for ventilation enum values and compatibility\n  members\n- `docs/payload-preservation.md` for raw payload preservation and raw endpoint\n  access\n\nThe public surface keeps a deliberate split between stable typed readers and\nbroader raw escape hatches. Use the typed methods when the model already\nmatches the data you need, and use the raw helpers when you need endpoint\ncoverage, selector flexibility, or payload fields that have not been typed yet.\nSee `docs/public-api-boundaries.md` for the full contract.\n\n## Testing strategy\n\nThe repository uses three automated test layers:\n\n- Synthetic unit tests cover focused parser and client behavior with mocked HTTP\n  responses.\n- Local sample-validation tests can replay a small set of typed client methods\n  against your own ignored raw API captures.\n- Live tests validate read paths, safe writes, and latency probes against your\n  own Duco device.\n\nThat split matters for Duco support. Synthetic tests keep day-to-day iteration\nfast. Local sample validation lets you check real captures without committing\nthem or maintaining a sanitization workflow. Live tests confirm that the client\nstill behaves correctly against actual hardware.\n\n## Public API maintenance\n\nThe compact API reference is generated from the published exports and public\nasync client methods. Regenerate it after public surface changes with:\n\n```bash\npython tools/api_reference.py write\n```\n\n## Development\n\nFrom the repository root, use any activated virtual environment you prefer. The\ncommands below use a local `.venv` so they stay copy-pasteable from a clean\ncheckout. Create it first if needed, then install the development dependencies\nand run the same checks as CI:\n\n```bash\npython -m venv .venv\n.venv/bin/python -m pip install -e \".[dev]\"\n.venv/bin/pytest\n.venv/bin/ruff check src tests\n.venv/bin/ruff format --check src tests\n.venv/bin/mypy src\n.venv/bin/bandit -r src -ll\n.venv/bin/pip-audit --desc on\n```\n\nFor local function probes without activating the environment first:\n\n```bash\n.venv/bin/python -m duco_connectivity --host 192.168.1.10 call async_get_board_info\n.venv/bin/duco-probe --host 192.168.1.10 call async_get_board_info\n```\n\nFor local real-device validation against your own Duco box, use the opt-in\nworkflow documented in `docs/live-testing.md`.\n\nFor local sample validation against ignored raw captures,\nuse `docs/replay-testing.md`.\n\nIf you want to validate raw API captures locally, follow the layout guidance in\n`docs/replay-testing.md` and the fixture-specific notes in\n`tests/fixtures/replay/README.md`.\n\n## Validation\n\nThe current API surface was validated against a real Duco box during the first\ndevelopment pass, covering:\n\n- `GET /api`\n- `GET /info` with generic module, submodule, and parameter queries\n- `GET /config` with generic module, submodule, and parameter queries\n- `PATCH /config` with a no-op `TimeZone` write against the current value\n- `GET /info?module=General\u0026submodule=Board`\n- `GET /info?module=General\u0026submodule=Lan`\n- `GET /info/nodes`\n- `GET /info?module=General\u0026submodule=PublicApi`\n- `POST /action/nodes/{node}` with a no-op `SetVentilationState`\n\nThe repository now also includes opt-in local live tests so the same read and\nsafe-write checks can be repeated against your own device without changing the\ndefault mock-only test workflow.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronaldvdmeer%2Fpython-duco-connectivity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fronaldvdmeer%2Fpython-duco-connectivity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronaldvdmeer%2Fpython-duco-connectivity/lists"}