python-duco-connectivity 0.8.0__tar.gz → 0.10.0__tar.gz

{python_duco_connectivity-0.8.0/src/python_duco_connectivity.egg-info → python_duco_connectivity-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-duco-connectivity
-Version: 0.8.0
+Version: 0.10.0
 Summary: Async HTTP client for the local Duco Connectivity API
 Author: Ronald van der Meer
 License-Expression: MIT
@@ -64,9 +64,21 @@ in the development examples below.
 - asynchronous communication via `aiohttp`
 - typed stable config families for the documented `/config` branches
 - typed helpers for stable `/info` fields such as heat recovery filter time
+- optional endpoint helpers with explicit unsupported-capability errors
 - typed models that stay close to the API response shape
 - preserved `raw_payload` data on typed response models for forward compatibility
 
+## Error handling
+
+When a Duco box explicitly reports that the optional ventilation-temperature or
+bypass-target endpoint is unsupported, the relevant helper raises
+`DucoUnsupportedCapabilityError`. This exception is a `DucoResponseError`
+subclass and preserves the HTTP status, path, and response body. A valid
+ventilation-temperature response always returns a `VentilationTemperatureInfo`
+model, whose individual temperature fields can be `None` when omitted. The
+bypass-target helper returns `None` when its target is omitted from a valid
+response.
+
 Diagnostic subsystem reads now keep raw component and status strings from
 `Diag.SubSystems`, so future subsystem names or status values remain available
 to downstream consumers without parse fallbacks or product-specific filtering.

{python_duco_connectivity-0.8.0 → python_duco_connectivity-0.10.0}/README.md

@@ -32,9 +32,21 @@ in the development examples below.
 - asynchronous communication via `aiohttp`
 - typed stable config families for the documented `/config` branches
 - typed helpers for stable `/info` fields such as heat recovery filter time
+- optional endpoint helpers with explicit unsupported-capability errors
 - typed models that stay close to the API response shape
 - preserved `raw_payload` data on typed response models for forward compatibility
 
+## Error handling
+
+When a Duco box explicitly reports that the optional ventilation-temperature or
+bypass-target endpoint is unsupported, the relevant helper raises
+`DucoUnsupportedCapabilityError`. This exception is a `DucoResponseError`
+subclass and preserves the HTTP status, path, and response body. A valid
+ventilation-temperature response always returns a `VentilationTemperatureInfo`
+model, whose individual temperature fields can be `None` when omitted. The
+bypass-target helper returns `None` when its target is omitted from a valid
+response.
+
 Diagnostic subsystem reads now keep raw component and status strings from
 `Diag.SubSystems`, so future subsystem names or status values remain available
 to downstream consumers without parse fallbacks or product-specific filtering.

{python_duco_connectivity-0.8.0 → python_duco_connectivity-0.10.0}/pyproject.toml

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

{python_duco_connectivity-0.8.0 → python_duco_connectivity-0.10.0}/src/duco_connectivity/__init__.py

@@ -8,6 +8,7 @@ from .exceptions import (
     DucoError,
     DucoRateLimitError,
     DucoResponseError,
+    DucoUnsupportedCapabilityError,
     DucoWriteLimitError,
 )
 from .models import (
@@ -172,6 +173,7 @@ __all__ = [
     "DucoRateLimitError",
     "DucoResponseError",
     "DucoSerialNumber",
+    "DucoUnsupportedCapabilityError",
     "DucoVersion",
     "DucoWriteLimitError",
     "HostName",

{python_duco_connectivity-0.8.0 → python_duco_connectivity-0.10.0}/src/duco_connectivity/client.py

@@ -16,6 +16,7 @@ from .exceptions import (
     DucoConnectionError,
     DucoError,
     DucoResponseError,
+    DucoUnsupportedCapabilityError,
     DucoWriteLimitError,
 )
 from .models import (
@@ -105,6 +106,23 @@ def _compat_caller() -> str | None:
     return None
 
 
+def _is_unsupported_optional_endpoint_error(error: DucoResponseError, path: str) -> bool:
+    """Return whether a Duco response reports an unavailable optional endpoint."""
+    if error.status != 400 or error.path != path:
+        return False
+
+    try:
+        error_payload = cast(object, json.loads(error.body))
+    except json.JSONDecodeError:
+        return False
+
+    if not isinstance(error_payload, dict):
+        return False
+
+    response = cast(dict[str, object], error_payload)
+    return response.get("Code") == 3 and response.get("Result") == "FAILED"
+
+
 class DucoClient:
     """Client for a Duco box that exposes the local HTTP API."""
 
@@ -2191,18 +2209,8 @@ class DucoClient:
         try:
             payload = await self.async_get_info(module=InfoModuleSelector.HEAT_RECOVERY)
         except DucoResponseError as err:
-            if err.status == 400 and err.path == "/info":
-                try:
-                    error_payload = json.loads(err.body)
-                except json.JSONDecodeError:
-                    pass
-                else:
-                    if (
-                        isinstance(error_payload, dict)
-                        and error_payload.get("Code") == 3
-                        and error_payload.get("Result") == "FAILED"
-                    ):
-                        return None
+            if _is_unsupported_optional_endpoint_error(err, "/info"):
+                return None
             raise
 
         if not isinstance(payload, dict):
@@ -2236,8 +2244,17 @@ class DucoClient:
         )
 
     async def async_get_ventilation_temperature_info(self) -> VentilationTemperatureInfo:
-        """Return ventilation temperatures from `/info?module=Ventilation` in Celsius."""
-        payload = await self.async_get_info(module=InfoModuleSelector.VENTILATION)
+        """Return ventilation temperatures when the box exposes them, in Celsius."""
+        try:
+            payload = await self.async_get_info(module=InfoModuleSelector.VENTILATION)
+        except DucoResponseError as err:
+            if _is_unsupported_optional_endpoint_error(err, "/info"):
+                raise DucoUnsupportedCapabilityError(
+                    err.status,
+                    err.path,
+                    err.body,
+                ) from err
+            raise
 
         if not isinstance(payload, dict):
             msg = (
@@ -2281,11 +2298,20 @@ class DucoClient:
     ) -> BypassSupplyTemperatureTarget | None:
         """Return a bypass supply target from `/config` in Celsius."""
         parameter = self._validate_bypass_zone_id(zone_id)
-        config = await self.async_get_config(
-            module=ConfigModuleSelector.HEAT_RECOVERY,
-            submodule=ConfigHeatRecoverySubmoduleSelector.BYPASS,
-            parameter=parameter,
-        )
+        try:
+            config = await self.async_get_config(
+                module=ConfigModuleSelector.HEAT_RECOVERY,
+                submodule=ConfigHeatRecoverySubmoduleSelector.BYPASS,
+                parameter=parameter,
+            )
+        except DucoResponseError as err:
+            if _is_unsupported_optional_endpoint_error(err, "/config"):
+                raise DucoUnsupportedCapabilityError(
+                    err.status,
+                    err.path,
+                    err.body,
+                ) from err
+            raise
         return self._extract_bypass_supply_temperature_target(config, zone_id)
 
     async def async_set_bypass_supply_temperature_target(

{python_duco_connectivity-0.8.0 → python_duco_connectivity-0.10.0}/src/duco_connectivity/exceptions.py

@@ -32,6 +32,16 @@ class DucoResponseError(DucoError):
         super().__init__(detail)
 
 
+class DucoUnsupportedCapabilityError(DucoResponseError):
+    """Raised when the box does not support an optional capability."""
+
+    def __init__(self, status: int, path: str, body: str = "") -> None:
+        detail = f"Unsupported capability for {path}"
+        if body.strip():
+            detail = f"{detail}: {body}"
+        super().__init__(status, path, body, message=detail)
+
+
 class DucoWriteLimitError(DucoResponseError):
     """Raised when the box rejects writes because its budget is exhausted."""
 

{python_duco_connectivity-0.8.0 → python_duco_connectivity-0.10.0/src/python_duco_connectivity.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-duco-connectivity
-Version: 0.8.0
+Version: 0.10.0
 Summary: Async HTTP client for the local Duco Connectivity API
 Author: Ronald van der Meer
 License-Expression: MIT
@@ -64,9 +64,21 @@ in the development examples below.
 - asynchronous communication via `aiohttp`
 - typed stable config families for the documented `/config` branches
 - typed helpers for stable `/info` fields such as heat recovery filter time
+- optional endpoint helpers with explicit unsupported-capability errors
 - typed models that stay close to the API response shape
 - preserved `raw_payload` data on typed response models for forward compatibility
 
+## Error handling
+
+When a Duco box explicitly reports that the optional ventilation-temperature or
+bypass-target endpoint is unsupported, the relevant helper raises
+`DucoUnsupportedCapabilityError`. This exception is a `DucoResponseError`
+subclass and preserves the HTTP status, path, and response body. A valid
+ventilation-temperature response always returns a `VentilationTemperatureInfo`
+model, whose individual temperature fields can be `None` when omitted. The
+bypass-target helper returns `None` when its target is omitted from a valid
+response.
+
 Diagnostic subsystem reads now keep raw component and status strings from
 `Diag.SubSystems`, so future subsystem names or status values remain available
 to downstream consumers without parse fallbacks or product-specific filtering.

{python_duco_connectivity-0.8.0 → python_duco_connectivity-0.10.0}/tests/test_api_reference.py

@@ -85,6 +85,15 @@ def test_api_reference_contains_expected_sections() -> None:
     assert "selectors.md" in content
 
 
+def test_api_reference_documents_optional_capability_contracts() -> None:
+    """Optional endpoint return and exception contracts should stay explicit."""
+    content = render_api_reference()
+
+    assert "optional endpoint as unsupported" in content
+    assert "target is omitted from an otherwise valid response" in content
+    assert "optional target endpoint is unsupported" in content
+
+
 def test_api_reference_hides_compatibility_only_method_aliases() -> None:
     """Compatibility-only client aliases should not be published as documented methods."""
     content = render_api_reference()

{python_duco_connectivity-0.8.0 → python_duco_connectivity-0.10.0}/tests/test_client.py

@@ -47,6 +47,7 @@ from duco_connectivity import (
     DucoError,
     DucoResponseError,
     DucoSerialNumber,
+    DucoUnsupportedCapabilityError,
     DucoVersion,
     DucoWriteLimitError,
     HostName,
@@ -3666,6 +3667,7 @@ async def test_get_ventilation_temperature_info_is_parsed(
         with patch.object(session, "request", _request(mock_response)):
             payload = await client.async_get_ventilation_temperature_info()
 
+    assert_type(payload, VentilationTemperatureInfo)
     assert payload == VentilationTemperatureInfo(
         temp_oda=17.5,
         temp_sup=18.0,
@@ -3688,6 +3690,38 @@ async def test_get_ventilation_temperature_info_returns_empty_model_when_sensor_
     assert payload.raw_payload == {}
 
 
+async def test_get_ventilation_temperature_info_raises_for_unsupported_module() -> None:
+    """Unsupported ventilation modules should raise a typed capability error."""
+    mock_response = _response(
+        status=400,
+        text_payload='{"Code":3,"Result":"FAILED"}',
+    )
+
+    async with aiohttp.ClientSession() as session:
+        client = DucoClient(session=session, host="192.0.2.94")
+        with (
+            patch.object(session, "request", _request(mock_response)),
+            pytest.raises(DucoUnsupportedCapabilityError) as err_info,
+        ):
+            await client.async_get_ventilation_temperature_info()
+
+    assert err_info.value.status == 400
+    assert err_info.value.path == "/info"
+
+
+async def test_get_ventilation_temperature_info_reraises_other_client_errors() -> None:
+    """Unexpected ventilation endpoint failures should remain visible to callers."""
+    mock_response = _response(status=400, text_payload='{"Code":4,"Result":"FAILED"}')
+
+    async with aiohttp.ClientSession() as session:
+        client = DucoClient(session=session, host="192.0.2.94")
+        with (
+            patch.object(session, "request", _request(mock_response)),
+            pytest.raises(DucoResponseError),
+        ):
+            await client.async_get_ventilation_temperature_info()
+
+
 @pytest.mark.parametrize(
     ("payload", "message"),
     [
@@ -3772,6 +3806,38 @@ async def test_get_bypass_supply_temperature_target_returns_none_when_not_report
     assert payload is None
 
 
+async def test_get_bypass_supply_temperature_target_raises_when_unsupported() -> None:
+    """Unsupported bypass targets should raise a typed capability error."""
+    mock_response = _response(
+        status=400,
+        text_payload='{"Code":3,"Result":"FAILED"}',
+    )
+
+    async with aiohttp.ClientSession() as session:
+        client = DucoClient(session=session, host="192.0.2.94")
+        with (
+            patch.object(session, "request", _request(mock_response)),
+            pytest.raises(DucoUnsupportedCapabilityError) as err_info,
+        ):
+            await client.async_get_bypass_supply_temperature_target(1)
+
+    assert err_info.value.status == 400
+    assert err_info.value.path == "/config"
+
+
+async def test_get_bypass_supply_temperature_target_reraises_other_client_errors() -> None:
+    """Unexpected bypass target failures should remain visible to callers."""
+    mock_response = _response(status=400, text_payload='{"Code":4,"Result":"FAILED"}')
+
+    async with aiohttp.ClientSession() as session:
+        client = DucoClient(session=session, host="192.0.2.94")
+        with (
+            patch.object(session, "request", _request(mock_response)),
+            pytest.raises(DucoResponseError),
+        ):
+            await client.async_get_bypass_supply_temperature_target(1)
+
+
 @pytest.mark.parametrize("zone_id", [0, 9, "1"])
 async def test_bypass_supply_temperature_helpers_reject_invalid_zone_ids(zone_id: object) -> None:
     """Bypass target helpers should validate the supported zone range."""
@@ -3871,8 +3937,8 @@ async def test_get_time_filter_remaining_returns_none_when_not_reported() -> Non
     assert remaining is None
 
 
-async def test_get_time_filter_remaining_returns_none_when_module_unsupported() -> None:
-    """Heat recovery filter time should stay optional for boxes without that module."""
+async def test_get_time_filter_remaining_returns_none_for_unsupported_module() -> None:
+    """Unsupported heat recovery modules should remain an optional value."""
     mock_response = _response(
         status=400,
         text_payload='{"Code":3,"Result":"FAILED"}',

{python_duco_connectivity-0.8.0 → python_duco_connectivity-0.10.0}/tests/test_exceptions.py

@@ -7,6 +7,7 @@ from duco_connectivity import (
     DucoError,
     DucoRateLimitError,
     DucoResponseError,
+    DucoUnsupportedCapabilityError,
     DucoWriteLimitError,
 )
 
@@ -41,6 +42,22 @@ def test_response_error_omits_empty_body_from_default_message(body: str) -> None
     assert str(err) == "Unexpected response 404 for /info"
 
 
+def test_unsupported_capability_error_preserves_response_context() -> None:
+    """DucoUnsupportedCapabilityError should retain HTTP response context."""
+    err = DucoUnsupportedCapabilityError(400, "/info", "unsupported")
+    assert isinstance(err, DucoResponseError)
+    assert err.status == 400
+    assert err.path == "/info"
+    assert err.body == "unsupported"
+    assert str(err) == "Unsupported capability for /info: unsupported"
+
+
+def test_unsupported_capability_error_omits_empty_body_from_message() -> None:
+    """DucoUnsupportedCapabilityError should omit an empty body from its message."""
+    err = DucoUnsupportedCapabilityError(400, "/info", "   ")
+    assert str(err) == "Unsupported capability for /info"
+
+
 def test_write_limit_error_stores_remaining_count() -> None:
     """DucoWriteLimitError should expose the remaining count when present."""
     err = DucoWriteLimitError(remaining=10)