python-duco-connectivity 0.1.0__tar.gz → 0.2.0__tar.gz

{python_duco_connectivity-0.1.0 → python_duco_connectivity-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-duco-connectivity
-Version: 0.1.0
+Version: 0.2.0
 Summary: Async HTTP client for the local Duco Connectivity API
 Author: Ronald van der Meer
 License-Expression: MIT

{python_duco_connectivity-0.1.0 → python_duco_connectivity-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-duco-connectivity"
-version = "0.1.0"
+version = "0.2.0"
 description = "Async HTTP client for the local Duco Connectivity API"
 readme = "README.md"
 license = "MIT"

{python_duco_connectivity-0.1.0 → python_duco_connectivity-0.2.0}/src/duco_connectivity/__init__.py

@@ -3,9 +3,15 @@
 from importlib.metadata import PackageNotFoundError, version
 
 from .client import DucoClient
-from .exceptions import DucoConnectionError, DucoError, DucoWriteLimitError
+from .exceptions import (
+    DucoConnectionError,
+    DucoError,
+    DucoRateLimitError,
+    DucoWriteLimitError,
+)
 from .models import (
     ApiEndpoint,
+    ApiEndpointInfo,
     ApiInfo,
     BoardInfo,
     DiagComponent,
@@ -28,11 +34,13 @@ except PackageNotFoundError:
 
 __all__ = [
     "ApiEndpoint",
+    "ApiEndpointInfo",
     "ApiInfo",
     "BoardInfo",
     "DucoClient",
     "DucoConnectionError",
     "DucoError",
+    "DucoRateLimitError",
     "DucoWriteLimitError",
     "DiagComponent",
     "DiagStatus",

{python_duco_connectivity-0.1.0 → python_duco_connectivity-0.2.0}/src/duco_connectivity/client.py

@@ -1,7 +1,11 @@
 """Async client for the local Duco HTTP API."""
 
 import json
+import logging
+import sys
+from types import FrameType
 from typing import Any
+from urllib.parse import urlsplit
 
 import aiohttp
 
@@ -23,6 +27,21 @@ from .models import (
     VentilationState,
 )
 
+_LOGGER = logging.getLogger(__name__)
+
+
+def _compat_caller() -> str | None:
+    """Return the first external caller that reached a compatibility path."""
+    frame: FrameType | None = sys._getframe(1)
+
+    while frame is not None:
+        module_name = frame.f_globals.get("__name__", "")
+        if module_name != "duco_connectivity" and not module_name.startswith("duco_connectivity."):
+            return f"{module_name}.{frame.f_code.co_name}"
+        frame = frame.f_back
+
+    return None
+
 
 class DucoClient:
     """Client for a Duco box that exposes the local HTTP API."""
@@ -37,17 +56,67 @@ class DucoClient:
     ) -> None:
         self._session = session
         self._timeout = aiohttp.ClientTimeout(total=request_timeout)
-        if host.startswith("https://"):
+
+        raw_host = host.rstrip("/")
+        authority = raw_host.split("://", 1)[1] if "://" in raw_host else raw_host
+        authority = authority.split("/", 1)[0].split("?", 1)[0].split("#", 1)[0]
+
+        if "@" not in authority and authority.count(":") >= 2 and not authority.startswith("["):
+            msg = "Unbracketed IPv6 host values are not supported; use [addr] or [addr]:port"
+            raise ValueError(msg)
+
+        parsed_host = urlsplit(raw_host if "://" in host else f"//{raw_host}")
+        scheme = parsed_host.scheme.lower()
+
+        if scheme == "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://"):
+
+        if scheme not in ("", "http"):
             msg = f"Unsupported scheme in host value: {host}"
             raise ValueError(msg)
-        if port is None:
+
+        if parsed_host.username is not None or parsed_host.password is not None:
+            msg = f"Host value must not include user credentials: {host}"
+            raise ValueError(msg)
+
+        if parsed_host.path not in ("", "/") or parsed_host.query or parsed_host.fragment:
+            msg = f"Host value must not include a path, query, or fragment: {host}"
+            raise ValueError(msg)
+
+        normalized_host = parsed_host.hostname
+        if normalized_host is None:
+            msg = f"Invalid host value: {host}"
+            raise ValueError(msg)
+
+        try:
+            embedded_port = parsed_host.port
+        except ValueError as err:
+            msg = f"Invalid port in host value: {host}"
+            raise ValueError(msg) from err
+
+        if port is not None and not 0 <= port <= 65535:
+            msg = f"Invalid port argument: {port}"
+            raise ValueError(msg)
+
+        if embedded_port is not None and port is not None:
+            msg = "Port specified both in host and port argument"
+            raise ValueError(msg)
+
+        if ":" in normalized_host:
+            normalized_host = f"[{normalized_host}]"
+
+        resolved_port = port if port is not None else embedded_port
+        if resolved_port is None:
             self._base_url = f"http://{normalized_host}"
         else:
-            self._base_url = f"http://{normalized_host}:{port}"
+            self._base_url = f"http://{normalized_host}:{resolved_port}"
+
+        _LOGGER.debug("Initialized DucoClient for %s", self._base_url)
+        _LOGGER.debug(
+            "Using HTTP-only duco_connectivity transport for %s.",
+            self._base_url,
+        )
 
     @property
     def base_url(self) -> str:
@@ -55,21 +124,51 @@ class DucoClient:
         return self._base_url
 
     async def _request_json(self, method: str, path: str, **kwargs: Any) -> Any:
+        json_payload = None
         if "json" in kwargs:
-            payload = kwargs.pop("json")
-            kwargs["data"] = json.dumps(payload, separators=(",", ":")).encode()
+            json_payload = kwargs.pop("json")
+            kwargs["data"] = json.dumps(json_payload, separators=(",", ":")).encode()
             kwargs.setdefault("headers", {})["Content-Type"] = "application/json"
         kwargs.setdefault("timeout", self._timeout)
 
+        _LOGGER.debug(
+            "Requesting %s %s%s with params=%s json=%s",
+            method,
+            self._base_url,
+            path,
+            kwargs.get("params"),
+            json_payload,
+        )
+
         try:
             request = self._session.request(method, f"{self._base_url}{path}", **kwargs)
         except (aiohttp.ClientError, TimeoutError) as err:
+            _LOGGER.debug(
+                "Request setup failed for %s %s%s: %s",
+                method,
+                self._base_url,
+                path,
+                err,
+            )
             msg = f"Could not reach Duco device at {self._base_url}: {err}"
             raise DucoConnectionError(msg) from err
 
         try:
             async with request as response:
+                _LOGGER.debug(
+                    "Received response %s for %s %s%s",
+                    response.status,
+                    method,
+                    self._base_url,
+                    path,
+                )
                 if response.status == 429:
+                    _LOGGER.debug(
+                        "Write limit reached for %s %s%s",
+                        method,
+                        self._base_url,
+                        path,
+                    )
                     raise DucoWriteLimitError()
 
                 if response.status >= 400:
@@ -85,6 +184,13 @@ class DucoClient:
         except DucoError:
             raise
         except (aiohttp.ClientError, TimeoutError) as err:
+            _LOGGER.debug(
+                "Request failed for %s %s%s: %s",
+                method,
+                self._base_url,
+                path,
+                err,
+            )
             msg = f"Could not reach Duco device at {self._base_url}: {err}"
             raise DucoConnectionError(msg) from err
 
@@ -97,6 +203,10 @@ class DucoClient:
         try:
             return NodeType(raw_value)
         except ValueError:
+            _LOGGER.debug(
+                "Unknown node type %r received from Duco API; falling back to UNKNOWN",
+                raw_value,
+            )
             return NodeType.UNKNOWN
 
     @staticmethod
@@ -104,8 +214,45 @@ class DucoClient:
         try:
             return NetworkType(raw_value)
         except ValueError:
+            _LOGGER.debug(
+                "Unknown network type %r received from Duco API; falling back to UNKNOWN",
+                raw_value,
+            )
             return NetworkType.UNKNOWN
 
+    @staticmethod
+    def _to_diag_status(raw_value: str) -> DiagStatus:
+        try:
+            return DiagStatus(raw_value)
+        except ValueError:
+            _LOGGER.debug(
+                "Unknown diagnostic status %r received from Duco API; falling back to UNKNOWN",
+                raw_value,
+            )
+            return DiagStatus.UNKNOWN
+
+    @staticmethod
+    def _to_ventilation_state(raw_value: str) -> VentilationState:
+        try:
+            return VentilationState(raw_value)
+        except ValueError:
+            _LOGGER.debug(
+                "Unknown ventilation state %r received from Duco API; falling back to UNKNOWN",
+                raw_value,
+            )
+            return VentilationState.UNKNOWN
+
+    @staticmethod
+    def _to_ventilation_mode(raw_value: str) -> VentilationMode:
+        try:
+            return VentilationMode(raw_value)
+        except ValueError:
+            _LOGGER.debug(
+                "Unknown ventilation mode %r received from Duco API; falling back to UNKNOWN",
+                raw_value,
+            )
+            return VentilationMode.UNKNOWN
+
     async def async_get_api_info(self) -> ApiInfo:
         """Return API metadata advertised by the box."""
         payload = await self._request_json("GET", "/api")
@@ -177,7 +324,7 @@ class DucoClient:
         return [
             DiagComponent(
                 component=item["Component"],
-                status=DiagStatus(item["Status"]),
+                status=self._to_diag_status(item["Status"]),
             )
             for item in payload["Diag"]["SubSystems"]
         ]
@@ -196,6 +343,22 @@ class DucoClient:
         )
         return int(self._read_wrapped_value(payload["General"]["PublicApi"], "WriteReqCntRemain"))
 
+    async def async_get_write_req_remaining(self) -> int:
+        """Backward-compatible alias for the old write budget method name."""
+        caller = _compat_caller()
+        if caller is None:
+            _LOGGER.debug(
+                "Compatibility alias async_get_write_req_remaining() used; "
+                "delegating to async_get_write_requests_remaining()."
+            )
+        else:
+            _LOGGER.debug(
+                "Compatibility alias async_get_write_req_remaining() used by %s; "
+                "delegating to async_get_write_requests_remaining().",
+                caller,
+            )
+        return await self.async_get_write_requests_remaining()
+
     async def async_set_ventilation_state(
         self, node_id: int, state: VentilationState | str
     ) -> None:
@@ -223,8 +386,8 @@ class DucoClient:
         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")),
+                state=self._to_ventilation_state(self._read_wrapped_value(vent, "State")),
+                mode=self._to_ventilation_mode(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")
@@ -234,13 +397,23 @@ class DucoClient:
 
         sensor = None
         if "Sensor" in payload:
-            sensor = payload["Sensor"]
+            sensor_payload = 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,
+                co2=self._read_wrapped_value(sensor_payload, "Co2")
+                if "Co2" in sensor_payload
+                else None,
+                iaq_co2=self._read_wrapped_value(sensor_payload, "IaqCo2")
+                if "IaqCo2" in sensor_payload
+                else None,
+                rh=self._read_wrapped_value(sensor_payload, "Rh")
+                if "Rh" in sensor_payload
+                else None,
+                iaq_rh=self._read_wrapped_value(sensor_payload, "IaqRh")
+                if "IaqRh" in sensor_payload
+                else None,
+                temp=self._read_wrapped_value(sensor_payload, "Temp")
+                if "Temp" in sensor_payload
+                else None,
             )
 
         return Node(

{python_duco_connectivity-0.1.0 → python_duco_connectivity-0.2.0}/src/duco_connectivity/exceptions.py

@@ -18,3 +18,7 @@ class DucoWriteLimitError(DucoError):
         if remaining is not None:
             detail = f"{detail} ({remaining} writes remaining)"
         super().__init__(detail)
+
+
+# Backward-compatible alias for the old python-duco-client exception name.
+DucoRateLimitError = DucoWriteLimitError

{python_duco_connectivity-0.1.0 → python_duco_connectivity-0.2.0}/src/duco_connectivity/models.py

@@ -1,7 +1,25 @@
 """Typed models for values exposed by the local Duco API."""
 
+import logging
+import sys
 from dataclasses import dataclass, field
 from enum import StrEnum
+from types import FrameType
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def _compat_caller() -> str | None:
+    """Return the first external caller that reached a compatibility path."""
+    frame: FrameType | None = sys._getframe(1)
+
+    while frame is not None:
+        module_name = frame.f_globals.get("__name__", "")
+        if module_name != "duco_connectivity" and not module_name.startswith("duco_connectivity."):
+            return f"{module_name}.{frame.f_code.co_name}"
+        frame = frame.f_back
+
+    return None
 
 
 class NodeType(StrEnum):
@@ -23,19 +41,21 @@ class NetworkType(StrEnum):
     VIRT = "VIRT"
     RF = "RF"
     WI = "WI"
+    MB = "MB"
     UNKNOWN = "UNKNOWN"
 
 
 class VentilationMode(StrEnum):
-    """Control modes reported for node ventilation."""
+    """Control modes reported for node ventilation, plus a client-side fallback."""
 
     AUTO = "AUTO"
     MANU = "MANU"
     NONE = "-"
+    UNKNOWN = "UNKNOWN"
 
 
 class VentilationState(StrEnum):
-    """State values accepted and reported for node ventilation."""
+    """Ventilation states reported by the API, plus a client-side fallback."""
 
     AUTO = "AUTO"
     AUT1 = "AUT1"
@@ -54,14 +74,16 @@ class VentilationState(StrEnum):
     MAN1x3 = "MAN1x3"
     MAN2x3 = "MAN2x3"
     MAN3x3 = "MAN3x3"
+    UNKNOWN = "UNKNOWN"
 
 
 class DiagStatus(StrEnum):
-    """Health states returned by the diagnostics API."""
+    """Health states returned by the diagnostics API, plus a client-side fallback."""
 
     OK = "Ok"
     DISABLE = "Disable"
     ERROR = "Error"
+    UNKNOWN = "UNKNOWN"
 
 
 @dataclass(frozen=True, slots=True)
@@ -74,7 +96,7 @@ class ApiEndpoint:
     modules: list[str] = field(default_factory=list)
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, slots=True, init=False)
 class ApiInfo:
     """Version and endpoint metadata returned by the API root."""
 
@@ -82,6 +104,63 @@ class ApiInfo:
     reported_api_version: str | None = None
     endpoints: list[ApiEndpoint] = field(default_factory=list)
 
+    def __init__(
+        self,
+        public_api_version: str | None = None,
+        reported_api_version: str | None = None,
+        endpoints: list[ApiEndpoint] | None = None,
+        *,
+        api_version: str | None = None,
+    ) -> None:
+        """Initialize API info with backward-compatible api_version support."""
+        if api_version is not None:
+            caller = _compat_caller()
+            if caller is None:
+                _LOGGER.debug(
+                    "Compatibility constructor argument api_version used; "
+                    "mapping to public_api_version."
+                )
+            else:
+                _LOGGER.debug(
+                    "Compatibility constructor argument api_version used by %s; "
+                    "mapping to public_api_version.",
+                    caller,
+                )
+
+        resolved_public_api_version = public_api_version
+        if resolved_public_api_version is None:
+            resolved_public_api_version = api_version
+        elif api_version is not None and api_version != public_api_version:
+            msg = "api_version must match public_api_version when both are provided"
+            raise ValueError(msg)
+
+        if resolved_public_api_version is None:
+            msg = "public_api_version or api_version must be provided"
+            raise TypeError(msg)
+
+        object.__setattr__(self, "public_api_version", resolved_public_api_version)
+        object.__setattr__(self, "reported_api_version", reported_api_version)
+        object.__setattr__(self, "endpoints", [] if endpoints is None else endpoints)
+
+    @property
+    def api_version(self) -> str:
+        """Backward-compatible alias for the old api_version field name."""
+        caller = _compat_caller()
+        if caller is None:
+            _LOGGER.debug(
+                "Compatibility property api_version accessed; delegating to public_api_version."
+            )
+        else:
+            _LOGGER.debug(
+                "Compatibility property api_version accessed by %s; delegating to "
+                "public_api_version.",
+                caller,
+            )
+        return self.public_api_version
+
+
+ApiEndpointInfo = ApiEndpoint
+
 
 @dataclass(frozen=True, slots=True)
 class BoardInfo:

{python_duco_connectivity-0.1.0 → python_duco_connectivity-0.2.0}/src/python_duco_connectivity.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-duco-connectivity
-Version: 0.1.0
+Version: 0.2.0
 Summary: Async HTTP client for the local Duco Connectivity API
 Author: Ronald van der Meer
 License-Expression: MIT

{python_duco_connectivity-0.1.0 → python_duco_connectivity-0.2.0}/tests/test_client.py

@@ -1,5 +1,6 @@
 """Tests for the HTTP-only Duco connectivity client."""
 
+import logging
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import aiohttp
@@ -13,6 +14,7 @@ from duco_connectivity import (
     DucoWriteLimitError,
     NetworkType,
     NodeType,
+    VentilationMode,
     VentilationState,
 )
 
@@ -48,6 +50,13 @@ def _request(response: MagicMock) -> MagicMock:
     return MagicMock(return_value=_request_context(response))
 
 
+def _build_async_wrapper(module_name: str, source: str) -> object:
+    """Create an async wrapper function in a custom module namespace."""
+    namespace = {"__name__": module_name}
+    exec(source, namespace)
+    return namespace["external_wrapper"]
+
+
 async def test_https_is_rejected() -> None:
     """HTTPS hosts should be rejected during client construction."""
     async with aiohttp.ClientSession() as session:
@@ -62,6 +71,69 @@ async def test_base_url_defaults_to_http() -> None:
         assert client.base_url == "http://192.0.2.94"
 
 
+async def test_base_url_uses_embedded_port_from_host() -> None:
+    """Hosts with an embedded port should preserve that port in the base URL."""
+    async with aiohttp.ClientSession() as session:
+        client = DucoClient(session=session, host="http://192.0.2.94:8080")
+        assert client.base_url == "http://192.0.2.94:8080"
+
+
+async def test_bracketed_ipv6_host_is_accepted() -> None:
+    """Bracketed IPv6 hosts should be accepted and normalized."""
+    async with aiohttp.ClientSession() as session:
+        client = DucoClient(session=session, host="[fe80::1]")
+        assert client.base_url == "http://[fe80::1]"
+
+
+async def test_uppercase_http_scheme_is_accepted() -> None:
+    """HTTP hosts should be accepted regardless of scheme casing."""
+    async with aiohttp.ClientSession() as session:
+        client = DucoClient(session=session, host="HTTP://192.0.2.94:8080")
+        assert client.base_url == "http://192.0.2.94:8080"
+
+
+async def test_conflicting_port_sources_are_rejected() -> None:
+    """The client should reject a separate port when the host already includes one."""
+    async with aiohttp.ClientSession() as session:
+        with pytest.raises(ValueError, match="Port specified both"):
+            DucoClient(session=session, host="192.0.2.94:8080", port=8081)
+
+
+async def test_userinfo_in_host_is_rejected() -> None:
+    """The unauthenticated client should reject credentials embedded in the host value."""
+    async with aiohttp.ClientSession() as session:
+        with pytest.raises(ValueError, match="must not include user credentials"):
+            DucoClient(session=session, host="user:pass@192.0.2.94")
+
+
+async def test_invalid_embedded_port_is_rejected() -> None:
+    """Malformed embedded ports should raise a consistent client ValueError."""
+    async with aiohttp.ClientSession() as session:
+        with pytest.raises(ValueError, match="Invalid port in host value"):
+            DucoClient(session=session, host="192.0.2.94:abc")
+
+
+async def test_unbracketed_ipv6_host_is_rejected() -> None:
+    """Bare IPv6 hosts should require brackets to avoid ambiguous parsing."""
+    async with aiohttp.ClientSession() as session:
+        with pytest.raises(ValueError, match="Unbracketed IPv6 host values"):
+            DucoClient(session=session, host="fe80::1")
+
+
+async def test_negative_port_argument_is_rejected() -> None:
+    """Explicit negative ports should be rejected during client construction."""
+    async with aiohttp.ClientSession() as session:
+        with pytest.raises(ValueError, match="Invalid port argument"):
+            DucoClient(session=session, host="192.0.2.94", port=-1)
+
+
+async def test_out_of_range_port_argument_is_rejected() -> None:
+    """Explicit ports above 65535 should be rejected during client construction."""
+    async with aiohttp.ClientSession() as session:
+        with pytest.raises(ValueError, match="Invalid port argument"):
+            DucoClient(session=session, host="192.0.2.94", port=99999)
+
+
 async def test_api_info_is_parsed(api_info_full_data: dict[str, object]) -> None:
     """Test that the API info model follows the public API payload."""
     mock_response = _response(json_payload=api_info_full_data)
@@ -75,7 +147,30 @@ async def test_api_info_is_parsed(api_info_full_data: dict[str, object]) -> None
     assert api_info.reported_api_version == "MOCKAPI 2.6.0"
     assert len(api_info.endpoints) == 2
     assert api_info.endpoints[1].url == "/info"
-    assert api_info.endpoints[1].query_parameters == ["module", "submodule", "parameter"]
+    assert api_info.endpoints[1].query_parameters == [
+        "module",
+        "submodule",
+        "parameter",
+    ]
+
+
+async def test_request_logging_includes_method_path_and_status(
+    caplog: pytest.LogCaptureFixture,
+    api_info_full_data: dict[str, object],
+) -> None:
+    """Requests should emit debug logs for the request and response."""
+    mock_response = _response(json_payload=api_info_full_data)
+
+    async with aiohttp.ClientSession() as session:
+        with caplog.at_level(logging.DEBUG, logger="duco_connectivity.client"):
+            client = DucoClient(session=session, host="192.0.2.94")
+            with patch.object(session, "request", _request(mock_response)):
+                await client.async_get_api_info()
+
+    assert "Initialized DucoClient for http://192.0.2.94" in caplog.text
+    assert "Using HTTP-only duco_connectivity transport for http://192.0.2.94." in caplog.text
+    assert "Requesting GET http://192.0.2.94/api" in caplog.text
+    assert "Received response 200 for GET http://192.0.2.94/api" in caplog.text
 
 
 async def test_board_info_is_parsed(board_info_data: dict[str, object]) -> None:
@@ -154,6 +249,26 @@ async def test_get_diagnostics(diag_data: dict[str, object]) -> None:
     assert diags[0].status == DiagStatus.OK
 
 
+async def test_get_diagnostics_unknown_status_falls_back_to_unknown() -> None:
+    """Unknown diagnostic statuses should not break parsing."""
+    payload: dict[str, object] = {
+        "Diag": {
+            "SubSystems": [
+                {"Component": "Ventilation", "Status": "FutureState"},
+            ]
+        }
+    }
+    mock_response = _response(json_payload=payload)
+
+    async with aiohttp.ClientSession() as session:
+        client = DucoClient(session=session, host="192.0.2.94")
+        with patch.object(session, "request", _request(mock_response)):
+            diags = await client.async_get_diagnostics()
+
+    assert len(diags) == 1
+    assert diags[0].status == DiagStatus.UNKNOWN
+
+
 async def test_get_nodes_parses_full_payload(nodes_data: dict[str, object]) -> None:
     """Test node parsing across box and sensor nodes."""
     mock_response = _response(json_payload=nodes_data)
@@ -221,6 +336,80 @@ async def test_get_nodes_unknown_network_type_falls_back_to_unknown() -> None:
     assert nodes[0].general.network_type == NetworkType.UNKNOWN
 
 
+async def test_get_nodes_unknown_network_type_logs_fallback(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Unknown enum fallbacks should emit a debug log for troubleshooting."""
+    payload: dict[str, object] = {
+        "Nodes": [
+            {
+                "Node": 4,
+                "General": {
+                    "Type": {"Val": "UCCO2"},
+                    "SubType": {"Val": 0},
+                    "NetworkType": {"Val": "FUTURE_TYPE"},
+                    "Parent": {"Val": 1},
+                    "Asso": {"Val": 1},
+                    "Name": {"Val": ""},
+                    "Identify": {"Val": 0},
+                },
+                "Ventilation": {
+                    "State": {"Val": "AUTO"},
+                    "TimeStateRemain": {"Val": 0},
+                    "TimeStateEnd": {"Val": 0},
+                    "Mode": {"Val": "-"},
+                },
+            }
+        ]
+    }
+    mock_response = _response(json_payload=payload)
+
+    async with aiohttp.ClientSession() as session:
+        client = DucoClient(session=session, host="192.0.2.94")
+        with (
+            caplog.at_level(logging.DEBUG, logger="duco_connectivity.client"),
+            patch.object(session, "request", _request(mock_response)),
+        ):
+            await client.async_get_nodes()
+
+    assert "Unknown network type 'FUTURE_TYPE' received from Duco API" in caplog.text
+
+
+async def test_get_nodes_mb_network_type_is_parsed() -> None:
+    """Known MB network types should be parsed explicitly."""
+    payload: dict[str, object] = {
+        "Nodes": [
+            {
+                "Node": 4,
+                "General": {
+                    "Type": {"Val": "UCCO2"},
+                    "SubType": {"Val": 0},
+                    "NetworkType": {"Val": "MB"},
+                    "Parent": {"Val": 1},
+                    "Asso": {"Val": 1},
+                    "Name": {"Val": ""},
+                    "Identify": {"Val": 0},
+                },
+                "Ventilation": {
+                    "State": {"Val": "AUTO"},
+                    "TimeStateRemain": {"Val": 0},
+                    "TimeStateEnd": {"Val": 0},
+                    "Mode": {"Val": "-"},
+                },
+            }
+        ]
+    }
+    mock_response = _response(json_payload=payload)
+
+    async with aiohttp.ClientSession() as session:
+        client = DucoClient(session=session, host="192.0.2.94")
+        with patch.object(session, "request", _request(mock_response)):
+            nodes = await client.async_get_nodes()
+
+    assert len(nodes) == 1
+    assert nodes[0].general.network_type == NetworkType.MB
+
+
 async def test_get_nodes_unknown_node_type_falls_back_to_unknown() -> None:
     """Test that unknown node types do not crash parsing."""
     payload: dict[str, object] = {
@@ -263,6 +452,91 @@ async def test_get_write_requests_remaining_is_parsed() -> None:
     assert remaining == 197
 
 
+async def test_get_write_req_remaining_alias_is_parsed() -> None:
+    """The old write budget method name should remain available."""
+    payload: dict[str, object] = {"General": {"PublicApi": {"WriteReqCntRemain": {"Val": 197}}}}
+    mock_response = _response(json_payload=payload)
+
+    async with aiohttp.ClientSession() as session:
+        client = DucoClient(session=session, host="192.0.2.94")
+        with patch.object(session, "request", _request(mock_response)):
+            remaining = await client.async_get_write_req_remaining()
+
+    assert remaining == 197
+
+
+async def test_get_write_req_remaining_alias_logs_external_caller(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Compatibility logging should include the external caller path."""
+    payload: dict[str, object] = {"General": {"PublicApi": {"WriteReqCntRemain": {"Val": 197}}}}
+    mock_response = _response(json_payload=payload)
+
+    async def external_wrapper(client: DucoClient) -> int:
+        return await client.async_get_write_req_remaining()
+
+    async with aiohttp.ClientSession() as session:
+        client = DucoClient(session=session, host="192.0.2.94")
+        with (
+            caplog.at_level(logging.DEBUG, logger="duco_connectivity.client"),
+            patch.object(session, "request", _request(mock_response)),
+        ):
+            remaining = await external_wrapper(client)
+
+    assert remaining == 197
+    assert (
+        "Compatibility alias async_get_write_req_remaining() used by "
+        "test_client.external_wrapper; delegating to "
+        "async_get_write_requests_remaining()."
+    ) in caplog.text
+
+
+async def test_get_write_req_remaining_alias_treats_prefixed_external_module_as_external(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Modules like duco_connectivity_tools should not be treated as internal."""
+    payload: dict[str, object] = {"General": {"PublicApi": {"WriteReqCntRemain": {"Val": 197}}}}
+    mock_response = _response(json_payload=payload)
+    external_wrapper = _build_async_wrapper(
+        "duco_connectivity_tools",
+        "async def external_wrapper(client):\n"
+        "    return await client.async_get_write_req_remaining()\n",
+    )
+
+    async with aiohttp.ClientSession() as session:
+        client = DucoClient(session=session, host="192.0.2.94")
+        with (
+            caplog.at_level(logging.DEBUG, logger="duco_connectivity.client"),
+            patch.object(session, "request", _request(mock_response)),
+        ):
+            remaining = await external_wrapper(client)
+
+    assert remaining == 197
+    assert (
+        "Compatibility alias async_get_write_req_remaining() used by "
+        "duco_connectivity_tools.external_wrapper; delegating to "
+        "async_get_write_requests_remaining()."
+    ) in caplog.text
+
+
+async def test_get_write_req_remaining_alias_logs_compat_usage(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """The compatibility alias should emit a debug log when it is used."""
+    payload: dict[str, object] = {"General": {"PublicApi": {"WriteReqCntRemain": {"Val": 197}}}}
+    mock_response = _response(json_payload=payload)
+
+    async with aiohttp.ClientSession() as session:
+        client = DucoClient(session=session, host="192.0.2.94")
+        with (
+            caplog.at_level(logging.DEBUG, logger="duco_connectivity.client"),
+            patch.object(session, "request", _request(mock_response)),
+        ):
+            await client.async_get_write_req_remaining()
+
+    assert "Compatibility alias async_get_write_req_remaining() used" in caplog.text
+
+
 async def test_timed_manual_state_is_parsed() -> None:
     """Test that timed manual ventilation states are accepted from the API."""
     payload: dict[str, object] = {
@@ -301,6 +575,80 @@ async def test_timed_manual_state_is_parsed() -> None:
     assert nodes[0].ventilation.state is VentilationState.MAN3x2
 
 
+async def test_get_nodes_unknown_ventilation_state_falls_back_to_unknown() -> None:
+    """Unknown ventilation states should not break node parsing."""
+    payload: dict[str, object] = {
+        "Nodes": [
+            {
+                "Node": 6,
+                "General": {
+                    "Type": {"Val": "BOX"},
+                    "SubType": {"Val": 1},
+                    "NetworkType": {"Val": "VIRT"},
+                    "Parent": {"Val": 0},
+                    "Asso": {"Val": 0},
+                    "Name": {"Val": "Living"},
+                    "Identify": {"Val": 0},
+                },
+                "Ventilation": {
+                    "State": {"Val": "FUTURE_STATE"},
+                    "Mode": {"Val": "AUTO"},
+                    "TimeStateRemain": {"Val": 0},
+                    "TimeStateEnd": {"Val": 0},
+                },
+            }
+        ]
+    }
+
+    mock_response = _response(json_payload=payload)
+
+    async with aiohttp.ClientSession() as session:
+        client = DucoClient(session=session, host="192.0.2.94")
+        with patch.object(session, "request", _request(mock_response)):
+            nodes = await client.async_get_nodes()
+
+    assert len(nodes) == 1
+    assert nodes[0].ventilation is not None
+    assert nodes[0].ventilation.state is VentilationState.UNKNOWN
+
+
+async def test_get_nodes_unknown_ventilation_mode_falls_back_to_unknown() -> None:
+    """Unknown ventilation modes should not break node parsing."""
+    payload: dict[str, object] = {
+        "Nodes": [
+            {
+                "Node": 7,
+                "General": {
+                    "Type": {"Val": "BOX"},
+                    "SubType": {"Val": 1},
+                    "NetworkType": {"Val": "VIRT"},
+                    "Parent": {"Val": 0},
+                    "Asso": {"Val": 0},
+                    "Name": {"Val": "Bedroom"},
+                    "Identify": {"Val": 0},
+                },
+                "Ventilation": {
+                    "State": {"Val": "AUTO"},
+                    "Mode": {"Val": "FUTURE_MODE"},
+                    "TimeStateRemain": {"Val": 0},
+                    "TimeStateEnd": {"Val": 0},
+                },
+            }
+        ]
+    }
+
+    mock_response = _response(json_payload=payload)
+
+    async with aiohttp.ClientSession() as session:
+        client = DucoClient(session=session, host="192.0.2.94")
+        with patch.object(session, "request", _request(mock_response)):
+            nodes = await client.async_get_nodes()
+
+    assert len(nodes) == 1
+    assert nodes[0].ventilation is not None
+    assert nodes[0].ventilation.mode is VentilationMode.UNKNOWN
+
+
 async def test_connection_error_raises_duco_connection_error() -> None:
     """Transport errors should raise DucoConnectionError."""
     async with aiohttp.ClientSession() as session:

{python_duco_connectivity-0.1.0 → python_duco_connectivity-0.2.0}/tests/test_exceptions.py

@@ -1,6 +1,11 @@
 """Tests for the public exceptions."""
 
-from duco_connectivity import DucoConnectionError, DucoError, DucoWriteLimitError
+from duco_connectivity import (
+    DucoConnectionError,
+    DucoError,
+    DucoRateLimitError,
+    DucoWriteLimitError,
+)
 
 
 def test_connection_error_inherits_from_base_error() -> None:
@@ -20,3 +25,11 @@ def test_write_limit_error_stores_remaining_count() -> None:
     err = DucoWriteLimitError(remaining=10)
     assert err.remaining == 10
     assert "10" in str(err)
+
+
+def test_rate_limit_error_alias_points_to_write_limit_error() -> None:
+    """The old rate-limit exception name should remain import-compatible."""
+    assert DucoRateLimitError is DucoWriteLimitError
+    err = DucoRateLimitError(remaining=3)
+    assert isinstance(err, DucoWriteLimitError)
+    assert err.remaining == 3

python_duco_connectivity-0.2.0/tests/test_models.py

@@ -0,0 +1,193 @@
+"""Tests for the public data models."""
+
+import logging
+
+import pytest
+
+from duco_connectivity import (
+    ApiEndpoint,
+    ApiEndpointInfo,
+    ApiInfo,
+    BoardInfo,
+    NetworkType,
+    Node,
+    NodeGeneralInfo,
+    NodeSensorInfo,
+    NodeType,
+    NodeVentilationInfo,
+    VentilationMode,
+    VentilationState,
+)
+
+
+def _build_wrapper(module_name: str, source: str) -> object:
+    """Create a wrapper function in a custom module namespace."""
+    namespace = {"__name__": module_name}
+    exec(source, namespace)
+    return namespace["external_wrapper"]
+
+
+def test_api_endpoint_defaults() -> None:
+    """ApiEndpoint should default to empty metadata lists."""
+    endpoint = ApiEndpoint(url="/api")
+    assert endpoint.methods == []
+    assert endpoint.query_parameters == []
+    assert endpoint.modules == []
+
+
+def test_api_info_defaults() -> None:
+    """ApiInfo should allow omitted optional fields."""
+    info = ApiInfo(public_api_version="2.5")
+    assert info.public_api_version == "2.5"
+    assert info.api_version == "2.5"
+    assert info.reported_api_version is None
+    assert info.endpoints == []
+
+
+def test_api_info_accepts_legacy_api_version_argument() -> None:
+    """ApiInfo should accept the old api_version keyword."""
+    info = ApiInfo(api_version="2.5")
+    assert info.public_api_version == "2.5"
+    assert info.api_version == "2.5"
+
+
+def test_api_info_accepts_previous_positional_signature() -> None:
+    """ApiInfo should still accept the old positional optional fields."""
+    endpoint = ApiEndpoint(url="/api")
+
+    info = ApiInfo("2.5", "reported", [endpoint])
+
+    assert info.public_api_version == "2.5"
+    assert info.reported_api_version == "reported"
+    assert info.endpoints == [endpoint]
+
+
+def test_api_info_accepts_positional_optional_fields_with_legacy_keyword() -> None:
+    """Legacy api_version support should not block the old positional optional fields."""
+    endpoint = ApiEndpoint(url="/api")
+
+    info = ApiInfo(None, "reported", [endpoint], api_version="2.5")
+
+    assert info.public_api_version == "2.5"
+    assert info.reported_api_version == "reported"
+    assert info.endpoints == [endpoint]
+
+
+def test_api_info_legacy_api_version_argument_logs_external_caller(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Using the old constructor keyword should log the external caller."""
+
+    def external_wrapper() -> ApiInfo:
+        return ApiInfo(api_version="2.5")
+
+    with caplog.at_level(logging.DEBUG, logger="duco_connectivity.models"):
+        info = external_wrapper()
+
+    assert info.public_api_version == "2.5"
+    assert (
+        "Compatibility constructor argument api_version used by "
+        "test_models.external_wrapper; mapping to public_api_version."
+    ) in caplog.text
+
+
+def test_api_info_legacy_api_version_property_logs_external_caller(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Using the old property should log the external caller."""
+    info = ApiInfo(public_api_version="2.5")
+
+    def external_wrapper() -> str:
+        return info.api_version
+
+    with caplog.at_level(logging.DEBUG, logger="duco_connectivity.models"):
+        value = external_wrapper()
+
+    assert value == "2.5"
+    assert (
+        "Compatibility property api_version accessed by "
+        "test_models.external_wrapper; delegating to public_api_version."
+    ) in caplog.text
+
+
+def test_api_info_legacy_api_version_property_treats_prefixed_external_module_as_external(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Modules like duco_connectivity_tools should not be treated as internal."""
+    info = ApiInfo(public_api_version="2.5")
+    external_wrapper = _build_wrapper(
+        "duco_connectivity_tools",
+        "def external_wrapper(info):\n    return info.api_version\n",
+    )
+
+    with caplog.at_level(logging.DEBUG, logger="duco_connectivity.models"):
+        value = external_wrapper(info)
+
+    assert value == "2.5"
+    assert (
+        "Compatibility property api_version accessed by "
+        "duco_connectivity_tools.external_wrapper; delegating to public_api_version."
+    ) in caplog.text
+
+
+def test_api_endpoint_info_alias_points_to_api_endpoint() -> None:
+    """ApiEndpointInfo should remain import-compatible with ApiEndpoint."""
+    assert ApiEndpointInfo is ApiEndpoint
+
+
+def test_board_info_optional_software_version() -> None:
+    """BoardInfo should keep software_version optional."""
+    board = BoardInfo(
+        box_name="SILENT_CONNECT",
+        box_sub_type_name="Eu",
+        serial_board_box="RS0000000001",
+        serial_board_comm="PS0000000001",
+        serial_duco_box="n/a",
+        serial_duco_comm="P000000-000000-001",
+        time=1775082497,
+    )
+    assert board.software_version is None
+
+
+def test_node_sensor_info_defaults() -> None:
+    """NodeSensorInfo should default all optional fields to None."""
+    sensor = NodeSensorInfo()
+    assert sensor.co2 is None
+    assert sensor.iaq_co2 is None
+    assert sensor.rh is None
+    assert sensor.iaq_rh is None
+    assert sensor.temp is None
+
+
+def test_node_ventilation_info_flow_target_is_optional() -> None:
+    """NodeVentilationInfo should allow omitted flow target."""
+    ventilation = NodeVentilationInfo(
+        state=VentilationState.CNT1,
+        time_state_remain=0,
+        time_state_end=0,
+        mode=VentilationMode.NONE,
+    )
+    assert ventilation.flow_lvl_tgt is None
+
+
+def test_node_is_frozen() -> None:
+    """The public node model should remain immutable."""
+    node = Node(
+        node_id=1,
+        general=NodeGeneralInfo(
+            node_type=NodeType.BOX,
+            sub_type=1,
+            network_type=NetworkType.VIRT,
+            parent=0,
+            asso=0,
+            name="",
+            identify=0,
+        ),
+    )
+    with pytest.raises(AttributeError):
+        node.node_id = 2  # type: ignore[misc]
+
+
+def test_network_type_includes_mb() -> None:
+    """NetworkType should expose MB as an explicit known value."""
+    assert NetworkType.MB.value == "MB"

python_duco_connectivity-0.1.0/tests/test_models.py

@@ -1,86 +0,0 @@
-"""Tests for the public data models."""
-
-import pytest
-
-from duco_connectivity import (
-    ApiEndpoint,
-    ApiInfo,
-    BoardInfo,
-    NetworkType,
-    Node,
-    NodeGeneralInfo,
-    NodeSensorInfo,
-    NodeType,
-    NodeVentilationInfo,
-    VentilationMode,
-    VentilationState,
-)
-
-
-def test_api_endpoint_defaults() -> None:
-    """ApiEndpoint should default to empty metadata lists."""
-    endpoint = ApiEndpoint(url="/api")
-    assert endpoint.methods == []
-    assert endpoint.query_parameters == []
-    assert endpoint.modules == []
-
-
-def test_api_info_defaults() -> None:
-    """ApiInfo should allow omitted optional fields."""
-    info = ApiInfo(public_api_version="2.5")
-    assert info.public_api_version == "2.5"
-    assert info.reported_api_version is None
-    assert info.endpoints == []
-
-
-def test_board_info_optional_software_version() -> None:
-    """BoardInfo should keep software_version optional."""
-    board = BoardInfo(
-        box_name="SILENT_CONNECT",
-        box_sub_type_name="Eu",
-        serial_board_box="RS0000000001",
-        serial_board_comm="PS0000000001",
-        serial_duco_box="n/a",
-        serial_duco_comm="P000000-000000-001",
-        time=1775082497,
-    )
-    assert board.software_version is None
-
-
-def test_node_sensor_info_defaults() -> None:
-    """NodeSensorInfo should default all optional fields to None."""
-    sensor = NodeSensorInfo()
-    assert sensor.co2 is None
-    assert sensor.iaq_co2 is None
-    assert sensor.rh is None
-    assert sensor.iaq_rh is None
-    assert sensor.temp is None
-
-
-def test_node_ventilation_info_flow_target_is_optional() -> None:
-    """NodeVentilationInfo should allow omitted flow target."""
-    ventilation = NodeVentilationInfo(
-        state=VentilationState.CNT1,
-        time_state_remain=0,
-        time_state_end=0,
-        mode=VentilationMode.NONE,
-    )
-    assert ventilation.flow_lvl_tgt is None
-
-
-def test_node_is_frozen() -> None:
-    """The public node model should remain immutable."""
-    node = Node(
-        node_id=1,
-        general=NodeGeneralInfo(
-            node_type=NodeType.BOX,
-            sub_type=1,
-            network_type=NetworkType.VIRT,
-            parent=0,
-            asso=0,
-            name="",
-            identify=0,
-        ),
-    )
-    with pytest.raises(AttributeError):
-        node.node_id = 2  # type: ignore[misc]