python-duco-connectivity 0.1.0__tar.gz

python_duco_connectivity-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ronald van der Meer
+
+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.

python_duco_connectivity-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: python-duco-connectivity
+Version: 0.1.0
+Summary: Async HTTP client for the local Duco Connectivity API
+Author: Ronald van der Meer
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ronaldvdmeer/python-duco-connectivity
+Project-URL: Repository, https://github.com/ronaldvdmeer/python-duco-connectivity
+Project-URL: Issues, https://github.com/ronaldvdmeer/python-duco-connectivity/issues
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: dev
+Requires-Dist: aioresponses>=0.7; extra == "dev"
+Requires-Dist: bandit>=1.7; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: pip-audit>=2.7; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Dynamic: license-file
+
+# python-duco-connectivity
+
+Async Python client for the local Duco HTTP API.
+
+`python-duco-connectivity` 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.
+
+## Installation
+
+Until the first PyPI release is published, install directly from GitHub:
+
+```bash
+pip install git+https://github.com/ronaldvdmeer/python-duco-connectivity.git
+```
+
+After the package is published on PyPI, install it with:
+
+```bash
+pip install python-duco-connectivity
+```
+
+## Current scope
+
+- HTTP only
+- asynchronous communication via `aiohttp`
+- typed models that stay close to the API response shape
+
+## Public API surface
+
+The current client exposes:
+
+- `async_get_api_info()` for `GET /api`
+- `async_get_board_info()` for `GET /info?module=General&submodule=Board`
+- `async_get_lan_info()` for `GET /info?module=General&submodule=Lan`
+- `async_get_nodes()` for `GET /info/nodes`
+- `async_get_diagnostics()` for `GET /info?module=Diag`
+- `async_get_write_requests_remaining()` for `GET /info?module=General&submodule=PublicApi`
+- `async_set_ventilation_state()` for `POST /action/nodes/{node}` with `SetVentilationState`
+
+The model layer includes `ApiInfo`, `BoardInfo`, `LanInfo`, `Node`,
+`NodeGeneralInfo`, `NodeVentilationInfo`, and `NodeSensorInfo`.
+
+## Development
+
+Install the development dependencies and run the same checks as CI:
+
+```bash
+pip install ".[dev]"
+pytest
+ruff check src tests
+ruff format --check src tests
+mypy src
+bandit -r src -ll
+pip-audit --desc on
+```
+
+## Validation
+
+The current API surface was validated against a real Duco box during the first
+development pass, covering:
+
+- `GET /api`
+- `GET /info?module=General&submodule=Board`
+- `GET /info?module=General&submodule=Lan`
+- `GET /info/nodes`
+- `GET /info?module=General&submodule=PublicApi`
+- `POST /action/nodes/{node}` with a no-op `SetVentilationState`
+

python_duco_connectivity-0.1.0/README.md

@@ -0,0 +1,70 @@
+# python-duco-connectivity
+
+Async Python client for the local Duco HTTP API.
+
+`python-duco-connectivity` 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.
+
+## Installation
+
+Until the first PyPI release is published, install directly from GitHub:
+
+```bash
+pip install git+https://github.com/ronaldvdmeer/python-duco-connectivity.git
+```
+
+After the package is published on PyPI, install it with:
+
+```bash
+pip install python-duco-connectivity
+```
+
+## Current scope
+
+- HTTP only
+- asynchronous communication via `aiohttp`
+- typed models that stay close to the API response shape
+
+## Public API surface
+
+The current client exposes:
+
+- `async_get_api_info()` for `GET /api`
+- `async_get_board_info()` for `GET /info?module=General&submodule=Board`
+- `async_get_lan_info()` for `GET /info?module=General&submodule=Lan`
+- `async_get_nodes()` for `GET /info/nodes`
+- `async_get_diagnostics()` for `GET /info?module=Diag`
+- `async_get_write_requests_remaining()` for `GET /info?module=General&submodule=PublicApi`
+- `async_set_ventilation_state()` for `POST /action/nodes/{node}` with `SetVentilationState`
+
+The model layer includes `ApiInfo`, `BoardInfo`, `LanInfo`, `Node`,
+`NodeGeneralInfo`, `NodeVentilationInfo`, and `NodeSensorInfo`.
+
+## Development
+
+Install the development dependencies and run the same checks as CI:
+
+```bash
+pip install ".[dev]"
+pytest
+ruff check src tests
+ruff format --check src tests
+mypy src
+bandit -r src -ll
+pip-audit --desc on
+```
+
+## Validation
+
+The current API surface was validated against a real Duco box during the first
+development pass, covering:
+
+- `GET /api`
+- `GET /info?module=General&submodule=Board`
+- `GET /info?module=General&submodule=Lan`
+- `GET /info/nodes`
+- `GET /info?module=General&submodule=PublicApi`
+- `POST /action/nodes/{node}` with a no-op `SetVentilationState`
+

python_duco_connectivity-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "python-duco-connectivity"
+version = "0.1.0"
+description = "Async HTTP client for the local Duco Connectivity API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [
+    { name = "Ronald van der Meer" },
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Home Automation",
+    "Framework :: AsyncIO",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aiohttp>=3.9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "aioresponses>=0.7",
+    "bandit>=1.7",
+    "mypy>=1.8",
+    "pip-audit>=2.7",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
+    "ruff>=0.11",
+]
+
+[project.urls]
+Homepage = "https://github.com/ronaldvdmeer/python-duco-connectivity"
+Repository = "https://github.com/ronaldvdmeer/python-duco-connectivity"
+Issues = "https://github.com/ronaldvdmeer/python-duco-connectivity/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+duco_connectivity = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = [
+    "--cov=duco_connectivity",
+    "--cov-report=term-missing",
+]
+
+[tool.coverage.run]
+source = ["duco_connectivity"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

python_duco_connectivity-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

python_duco_connectivity-0.1.0/src/duco_connectivity/__init__.py

@@ -0,0 +1,49 @@
+"""Public package exports for python-duco-connectivity."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import DucoClient
+from .exceptions import DucoConnectionError, DucoError, DucoWriteLimitError
+from .models import (
+    ApiEndpoint,
+    ApiInfo,
+    BoardInfo,
+    DiagComponent,
+    DiagStatus,
+    LanInfo,
+    NetworkType,
+    Node,
+    NodeGeneralInfo,
+    NodeSensorInfo,
+    NodeType,
+    NodeVentilationInfo,
+    VentilationMode,
+    VentilationState,
+)
+
+try:
+    __version__ = version("python-duco-connectivity")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "ApiEndpoint",
+    "ApiInfo",
+    "BoardInfo",
+    "DucoClient",
+    "DucoConnectionError",
+    "DucoError",
+    "DucoWriteLimitError",
+    "DiagComponent",
+    "DiagStatus",
+    "LanInfo",
+    "NetworkType",
+    "Node",
+    "NodeGeneralInfo",
+    "NodeSensorInfo",
+    "NodeType",
+    "NodeVentilationInfo",
+    "VentilationMode",
+    "VentilationState",
+    "__version__",
+]

python_duco_connectivity-0.1.0/src/duco_connectivity/client.py

@@ -0,0 +1,251 @@
+"""Async client for the local Duco HTTP API."""
+
+import json
+from typing import Any
+
+import aiohttp
+
+from .exceptions import DucoConnectionError, DucoError, DucoWriteLimitError
+from .models import (
+    ApiEndpoint,
+    ApiInfo,
+    BoardInfo,
+    DiagComponent,
+    DiagStatus,
+    LanInfo,
+    NetworkType,
+    Node,
+    NodeGeneralInfo,
+    NodeSensorInfo,
+    NodeType,
+    NodeVentilationInfo,
+    VentilationMode,
+    VentilationState,
+)
+
+
+class DucoClient:
+    """Client for a Duco box that exposes the local HTTP API."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        host: str,
+        *,
+        port: int | None = None,
+        request_timeout: float = 10.0,
+    ) -> None:
+        self._session = session
+        self._timeout = aiohttp.ClientTimeout(total=request_timeout)
+        if host.startswith("https://"):
+            msg = "HTTPS is not supported by this client"
+            raise ValueError(msg)
+        normalized_host = host.removeprefix("http://").removeprefix("https://").rstrip("/")
+        if "://" in host and not host.startswith("http://"):
+            msg = f"Unsupported scheme in host value: {host}"
+            raise ValueError(msg)
+        if port is None:
+            self._base_url = f"http://{normalized_host}"
+        else:
+            self._base_url = f"http://{normalized_host}:{port}"
+
+    @property
+    def base_url(self) -> str:
+        """Normalized base URL used for requests."""
+        return self._base_url
+
+    async def _request_json(self, method: str, path: str, **kwargs: Any) -> Any:
+        if "json" in kwargs:
+            payload = kwargs.pop("json")
+            kwargs["data"] = json.dumps(payload, separators=(",", ":")).encode()
+            kwargs.setdefault("headers", {})["Content-Type"] = "application/json"
+        kwargs.setdefault("timeout", self._timeout)
+
+        try:
+            request = self._session.request(method, f"{self._base_url}{path}", **kwargs)
+        except (aiohttp.ClientError, TimeoutError) as err:
+            msg = f"Could not reach Duco device at {self._base_url}: {err}"
+            raise DucoConnectionError(msg) from err
+
+        try:
+            async with request as response:
+                if response.status == 429:
+                    raise DucoWriteLimitError()
+
+                if response.status >= 400:
+                    body = await response.text()
+                    msg = f"Unexpected response {response.status} for {path}: {body}"
+                    raise DucoError(msg)
+
+                try:
+                    return await response.json(content_type=None)
+                except ValueError as err:
+                    msg = f"Expected JSON response from {path}: {err}"
+                    raise DucoError(msg) from err
+        except DucoError:
+            raise
+        except (aiohttp.ClientError, TimeoutError) as err:
+            msg = f"Could not reach Duco device at {self._base_url}: {err}"
+            raise DucoConnectionError(msg) from err
+
+    @staticmethod
+    def _read_wrapped_value(payload: dict[str, Any], key: str) -> Any:
+        return payload[key]["Val"]
+
+    @staticmethod
+    def _to_node_type(raw_value: str) -> NodeType:
+        try:
+            return NodeType(raw_value)
+        except ValueError:
+            return NodeType.UNKNOWN
+
+    @staticmethod
+    def _to_network_type(raw_value: str) -> NetworkType:
+        try:
+            return NetworkType(raw_value)
+        except ValueError:
+            return NetworkType.UNKNOWN
+
+    async def async_get_api_info(self) -> ApiInfo:
+        """Return API metadata advertised by the box."""
+        payload = await self._request_json("GET", "/api")
+        public_api_version = self._read_wrapped_value(payload, "PublicApiVersion")
+        reported_api_version = None
+        if "ApiVersion" in payload:
+            reported_api_version = self._read_wrapped_value(payload, "ApiVersion")
+        endpoints = [
+            ApiEndpoint(
+                url=item["Url"],
+                methods=list(item.get("Methods", [])),
+                query_parameters=list(item.get("QueryParameters", [])),
+                modules=list(item.get("Modules", [])),
+            )
+            for item in payload.get("ApiInfo", [])
+        ]
+        return ApiInfo(
+            public_api_version=public_api_version,
+            reported_api_version=reported_api_version,
+            endpoints=endpoints,
+        )
+
+    async def async_get_board_info(self) -> BoardInfo:
+        """Return identity and version details for the main unit."""
+        payload = await self._request_json(
+            "GET",
+            "/info",
+            params={"module": "General", "submodule": "Board"},
+        )
+        board = payload["General"]["Board"]
+        return BoardInfo(
+            box_name=self._read_wrapped_value(board, "BoxName"),
+            box_sub_type_name=self._read_wrapped_value(board, "BoxSubTypeName"),
+            serial_board_box=self._read_wrapped_value(board, "SerialBoardBox"),
+            serial_board_comm=self._read_wrapped_value(board, "SerialBoardComm"),
+            serial_duco_box=self._read_wrapped_value(board, "SerialDucoBox"),
+            serial_duco_comm=self._read_wrapped_value(board, "SerialDucoComm"),
+            time=self._read_wrapped_value(board, "Time"),
+            public_api_version=self._read_wrapped_value(board, "PublicApiVersion")
+            if "PublicApiVersion" in board
+            else None,
+            software_version=self._read_wrapped_value(board, "SwVersion")
+            if "SwVersion" in board
+            else None,
+        )
+
+    async def async_get_lan_info(self) -> LanInfo:
+        """Return LAN settings reported by the box."""
+        payload = await self._request_json(
+            "GET",
+            "/info",
+            params={"module": "General", "submodule": "Lan"},
+        )
+        lan = payload["General"]["Lan"]
+        return LanInfo(
+            mode=self._read_wrapped_value(lan, "Mode"),
+            ip=self._read_wrapped_value(lan, "Ip"),
+            net_mask=self._read_wrapped_value(lan, "NetMask"),
+            default_gateway=self._read_wrapped_value(lan, "DefaultGateway"),
+            dns=self._read_wrapped_value(lan, "Dns"),
+            mac=self._read_wrapped_value(lan, "Mac"),
+            host_name=self._read_wrapped_value(lan, "HostName"),
+            rssi_wifi=self._read_wrapped_value(lan, "RssiWifi") if "RssiWifi" in lan else None,
+        )
+
+    async def async_get_diagnostics(self) -> list[DiagComponent]:
+        """Return health states for diagnostic subsystems."""
+        payload = await self._request_json("GET", "/info", params={"module": "Diag"})
+        return [
+            DiagComponent(
+                component=item["Component"],
+                status=DiagStatus(item["Status"]),
+            )
+            for item in payload["Diag"]["SubSystems"]
+        ]
+
+    async def async_get_nodes(self) -> list[Node]:
+        """Return nodes reported by the local API."""
+        payload = await self._request_json("GET", "/info/nodes")
+        return [self._parse_node(item) for item in payload["Nodes"]]
+
+    async def async_get_write_requests_remaining(self) -> int:
+        """Return the remaining write budget reported by the box."""
+        payload = await self._request_json(
+            "GET",
+            "/info",
+            params={"module": "General", "submodule": "PublicApi"},
+        )
+        return int(self._read_wrapped_value(payload["General"]["PublicApi"], "WriteReqCntRemain"))
+
+    async def async_set_ventilation_state(
+        self, node_id: int, state: VentilationState | str
+    ) -> None:
+        """Request a ventilation state change for a node."""
+        state_value = state.value if isinstance(state, VentilationState) else state
+        await self._request_json(
+            "POST",
+            f"/action/nodes/{node_id}",
+            json={"Action": "SetVentilationState", "Val": state_value},
+        )
+
+    def _parse_node(self, payload: dict[str, Any]) -> Node:
+        general = payload["General"]
+        node_general = NodeGeneralInfo(
+            node_type=self._to_node_type(self._read_wrapped_value(general, "Type")),
+            sub_type=self._read_wrapped_value(general, "SubType"),
+            network_type=self._to_network_type(self._read_wrapped_value(general, "NetworkType")),
+            parent=self._read_wrapped_value(general, "Parent"),
+            asso=self._read_wrapped_value(general, "Asso"),
+            name=self._read_wrapped_value(general, "Name"),
+            identify=self._read_wrapped_value(general, "Identify"),
+        )
+
+        ventilation = None
+        if "Ventilation" in payload:
+            vent = payload["Ventilation"]
+            ventilation = NodeVentilationInfo(
+                state=VentilationState(self._read_wrapped_value(vent, "State")),
+                mode=VentilationMode(self._read_wrapped_value(vent, "Mode")),
+                time_state_remain=self._read_wrapped_value(vent, "TimeStateRemain"),
+                time_state_end=self._read_wrapped_value(vent, "TimeStateEnd"),
+                flow_lvl_tgt=self._read_wrapped_value(vent, "FlowLvlTgt")
+                if "FlowLvlTgt" in vent
+                else None,
+            )
+
+        sensor = None
+        if "Sensor" in payload:
+            sensor = payload["Sensor"]
+            sensor = NodeSensorInfo(
+                co2=self._read_wrapped_value(sensor, "Co2") if "Co2" in sensor else None,
+                iaq_co2=self._read_wrapped_value(sensor, "IaqCo2") if "IaqCo2" in sensor else None,
+                rh=self._read_wrapped_value(sensor, "Rh") if "Rh" in sensor else None,
+                iaq_rh=self._read_wrapped_value(sensor, "IaqRh") if "IaqRh" in sensor else None,
+                temp=self._read_wrapped_value(sensor, "Temp") if "Temp" in sensor else None,
+            )
+
+        return Node(
+            node_id=payload["Node"],
+            general=node_general,
+            ventilation=ventilation,
+            sensor=sensor,
+        )

python_duco_connectivity-0.1.0/src/duco_connectivity/exceptions.py

@@ -0,0 +1,20 @@
+"""Exceptions raised by the Duco client."""
+
+
+class DucoError(Exception):
+    """Base class for client errors."""
+
+
+class DucoConnectionError(DucoError):
+    """Raised when the client cannot reach the box."""
+
+
+class DucoWriteLimitError(DucoError):
+    """Raised when the box rejects writes because its budget is exhausted."""
+
+    def __init__(self, remaining: int | None = None) -> None:
+        self.remaining = remaining
+        detail = "Duco write capacity exhausted"
+        if remaining is not None:
+            detail = f"{detail} ({remaining} writes remaining)"
+        super().__init__(detail)