python-duco-connectivity 0.9.0__tar.gz → 0.11.0__tar.gz

{python_duco_connectivity-0.9.0/src/python_duco_connectivity.egg-info → python_duco_connectivity-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-duco-connectivity
-Version: 0.9.0
+Version: 0.11.0
 Summary: Async HTTP client for the local Duco Connectivity API
 Author: Ronald van der Meer
 License-Expression: MIT
@@ -64,11 +64,22 @@ 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 temperature helpers that return `None` when the box reports their
-  endpoint as unavailable
+- 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 a typed target model for successful parameter-
+specific reads and raises `DucoError` if the requested target field is missing
+from an otherwise valid `/config` 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.9.0 → python_duco_connectivity-0.11.0}/README.md

@@ -32,11 +32,22 @@ 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 temperature helpers that return `None` when the box reports their
-  endpoint as unavailable
+- 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 a typed target model for successful parameter-
+specific reads and raises `DucoError` if the requested target field is missing
+from an otherwise valid `/config` 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.9.0 → python_duco_connectivity-0.11.0}/pyproject.toml

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

{python_duco_connectivity-0.9.0 → python_duco_connectivity-0.11.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.9.0 → python_duco_connectivity-0.11.0}/src/duco_connectivity/client.py

@@ -16,6 +16,7 @@ from .exceptions import (
     DucoConnectionError,
     DucoError,
     DucoResponseError,
+    DucoUnsupportedCapabilityError,
     DucoWriteLimitError,
 )
 from .models import (
@@ -2242,13 +2243,17 @@ class DucoClient:
             path="HeatRecovery.General",
         )
 
-    async def async_get_ventilation_temperature_info(self) -> VentilationTemperatureInfo | None:
+    async def async_get_ventilation_temperature_info(self) -> VentilationTemperatureInfo:
         """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"):
-                return None
+                raise DucoUnsupportedCapabilityError(
+                    err.status,
+                    err.path,
+                    err.body,
+                ) from err
             raise
 
         if not isinstance(payload, dict):
@@ -2290,7 +2295,7 @@ class DucoClient:
     async def async_get_bypass_supply_temperature_target(
         self,
         zone_id: int,
-    ) -> BypassSupplyTemperatureTarget | None:
+    ) -> BypassSupplyTemperatureTarget:
         """Return a bypass supply target from `/config` in Celsius."""
         parameter = self._validate_bypass_zone_id(zone_id)
         try:
@@ -2301,9 +2306,17 @@ class DucoClient:
             )
         except DucoResponseError as err:
             if _is_unsupported_optional_endpoint_error(err, "/config"):
-                return None
+                raise DucoUnsupportedCapabilityError(
+                    err.status,
+                    err.path,
+                    err.body,
+                ) from err
             raise
-        return self._extract_bypass_supply_temperature_target(config, zone_id)
+        target = self._extract_bypass_supply_temperature_target(config, zone_id)
+        if target is None:
+            msg = f"Expected {parameter} in /config response"
+            raise DucoError(msg)
+        return target
 
     async def async_set_bypass_supply_temperature_target(
         self,

{python_duco_connectivity-0.9.0 → python_duco_connectivity-0.11.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.9.0 → python_duco_connectivity-0.11.0/src/python_duco_connectivity.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-duco-connectivity
-Version: 0.9.0
+Version: 0.11.0
 Summary: Async HTTP client for the local Duco Connectivity API
 Author: Ronald van der Meer
 License-Expression: MIT
@@ -64,11 +64,22 @@ 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 temperature helpers that return `None` when the box reports their
-  endpoint as unavailable
+- 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 a typed target model for successful parameter-
+specific reads and raises `DucoError` if the requested target field is missing
+from an otherwise valid `/config` 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.9.0 → python_duco_connectivity-0.11.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 "without the requested target field in the 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.9.0 → python_duco_connectivity-0.11.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,8 +3690,8 @@ async def test_get_ventilation_temperature_info_returns_empty_model_when_sensor_
     assert payload.raw_payload == {}
 
 
-async def test_get_ventilation_temperature_info_returns_none_when_module_unsupported() -> None:
-    """Unsupported ventilation modules should be treated as an absent optional capability."""
+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"}',
@@ -3697,10 +3699,14 @@ async def test_get_ventilation_temperature_info_returns_none_when_module_unsuppo
 
     async with aiohttp.ClientSession() as session:
         client = DucoClient(session=session, host="192.0.2.94")
-        with patch.object(session, "request", _request(mock_response)):
-            payload = await client.async_get_ventilation_temperature_info()
+        with (
+            patch.object(session, "request", _request(mock_response)),
+            pytest.raises(DucoUnsupportedCapabilityError) as err_info,
+        ):
+            await client.async_get_ventilation_temperature_info()
 
-    assert payload is None
+    assert err_info.value.status == 400
+    assert err_info.value.path == "/info"
 
 
 async def test_get_ventilation_temperature_info_reraises_other_client_errors() -> None:
@@ -3788,20 +3794,24 @@ async def test_get_bypass_supply_temperature_target_returns_converted_values(
     }
 
 
-async def test_get_bypass_supply_temperature_target_returns_none_when_not_reported() -> None:
-    """Missing bypass targets should return None instead of failing."""
+async def test_get_bypass_supply_temperature_target_raises_when_not_reported() -> None:
+    """Missing bypass targets should fail for parameter-specific helper reads."""
     mock_response = _response(json_payload={"HeatRecovery": {"Bypass": {}}})
 
     async with aiohttp.ClientSession() as session:
         client = DucoClient(session=session, host="192.0.2.94")
-        with patch.object(session, "request", _request(mock_response)):
-            payload = await client.async_get_bypass_supply_temperature_target(1)
-
-    assert payload is None
+        with (
+            patch.object(session, "request", _request(mock_response)),
+            pytest.raises(
+                DucoError,
+                match=re.escape("Expected TempSupTgtZone1 in /config response"),
+            ),
+        ):
+            await client.async_get_bypass_supply_temperature_target(1)
 
 
-async def test_get_bypass_supply_temperature_target_returns_none_when_unsupported() -> None:
-    """Unsupported bypass targets should be treated as an absent optional capability."""
+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"}',
@@ -3809,10 +3819,14 @@ async def test_get_bypass_supply_temperature_target_returns_none_when_unsupporte
 
     async with aiohttp.ClientSession() as session:
         client = DucoClient(session=session, host="192.0.2.94")
-        with patch.object(session, "request", _request(mock_response)):
-            payload = await client.async_get_bypass_supply_temperature_target(1)
+        with (
+            patch.object(session, "request", _request(mock_response)),
+            pytest.raises(DucoUnsupportedCapabilityError) as err_info,
+        ):
+            await client.async_get_bypass_supply_temperature_target(1)
 
-    assert payload is None
+    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:
@@ -3927,8 +3941,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.9.0 → python_duco_connectivity-0.11.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)