python-duco-connectivity 0.5.0__tar.gz → 0.7.0__tar.gz

{python_duco_connectivity-0.5.0/src/python_duco_connectivity.egg-info → python_duco_connectivity-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-duco-connectivity
-Version: 0.5.0
+Version: 0.7.0
 Summary: Async HTTP client for the local Duco Connectivity API
 Author: Ronald van der Meer
 License-Expression: MIT
@@ -27,7 +27,7 @@ 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"
+Requires-Dist: ruff>=0.15.14; extra == "dev"
 Dynamic: license-file
 
 # python-duco-connectivity
@@ -63,9 +63,14 @@ in the development examples below.
 - HTTP only
 - 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
 - typed models that stay close to the API response shape
 - preserved `raw_payload` data on typed response models for forward compatibility
 
+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.
+
 ## Getting started
 
 ```python
@@ -188,6 +193,7 @@ development pass, covering:
 - `PATCH /config` with a no-op `TimeZone` write against the current value
 - `GET /info?module=General&submodule=Board`
 - `GET /info?module=General&submodule=Lan`
+- `GET /info?module=HeatRecovery`
 - `GET /info/nodes`
 - `GET /info?module=General&submodule=PublicApi`
 - `POST /action/nodes/{node}` with a no-op `SetVentilationState`

{python_duco_connectivity-0.5.0 → python_duco_connectivity-0.7.0}/README.md

@@ -31,9 +31,14 @@ in the development examples below.
 - HTTP only
 - 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
 - typed models that stay close to the API response shape
 - preserved `raw_payload` data on typed response models for forward compatibility
 
+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.
+
 ## Getting started
 
 ```python
@@ -156,6 +161,7 @@ development pass, covering:
 - `PATCH /config` with a no-op `TimeZone` write against the current value
 - `GET /info?module=General&submodule=Board`
 - `GET /info?module=General&submodule=Lan`
+- `GET /info?module=HeatRecovery`
 - `GET /info/nodes`
 - `GET /info?module=General&submodule=PublicApi`
 - `POST /action/nodes/{node}` with a no-op `SetVentilationState`

{python_duco_connectivity-0.5.0 → python_duco_connectivity-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-duco-connectivity"
-version = "0.5.0"
+version = "0.7.0"
 description = "Async HTTP client for the local Duco Connectivity API"
 readme = "README.md"
 license = "MIT"
@@ -38,7 +38,7 @@ dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
     "pytest-cov>=5.0",
-    "ruff>=0.11",
+    "ruff>=0.15.14",
 ]
 
 [project.urls]
@@ -80,9 +80,10 @@ exclude_lines = [
 [tool.ruff]
 line-length = 100
 target-version = "py312"
+required-version = ">=0.15.14"
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "UP"]
+select = ["B", "E", "F", "I", "RUF", "UP"]
 
 [tool.mypy]
 python_version = "3.12"

{python_duco_connectivity-0.5.0 → python_duco_connectivity-0.7.0}/src/duco_connectivity/__init__.py

@@ -51,7 +51,7 @@ from .models import (
     ConfigZoneWithGroupStruct,
     DeviceGroupConfigSubmoduleSelector,
     DiagComponent,
-    DiagStatus,
+    DiagInfo,
     DucoSerialNumber,
     DucoVersion,
     HostName,
@@ -134,10 +134,10 @@ __all__ = [
     "ApiEndpoint",
     "ApiEndpointInfo",
     "ApiInfo",
-    "BoardName",
     "BoardInfo",
-    "ConfigAutoRebootComm",
+    "BoardName",
     "Config",
+    "ConfigAutoRebootComm",
     "ConfigGeneral",
     "ConfigGeneralSubmoduleSelector",
     "ConfigGroup",
@@ -153,33 +153,33 @@ __all__ = [
     "ConfigNodeStruct",
     "ConfigSection",
     "ConfigTime",
-    "ConfigZone",
-    "ConfigZoneWithGroupStruct",
-    "ConfigZonesOverview",
-    "ConfigZoneStruct",
     "ConfigValue",
     "ConfigValueOptions",
     "ConfigValueString",
+    "ConfigZone",
+    "ConfigZoneStruct",
+    "ConfigZoneWithGroupStruct",
+    "ConfigZonesOverview",
     "DeviceGroupConfigSubmoduleSelector",
+    "DiagComponent",
+    "DiagInfo",
     "DucoClient",
     "DucoConnectionError",
     "DucoError",
     "DucoRateLimitError",
     "DucoResponseError",
     "DucoSerialNumber",
-    "DucoWriteLimitError",
-    "DiagComponent",
-    "DiagStatus",
     "DucoVersion",
+    "DucoWriteLimitError",
     "HostName",
-    "InfoGroup",
     "InfoGeneralSubmoduleSelector",
+    "InfoGroup",
     "InfoGroupStruct",
     "InfoModuleSelector",
     "InfoZone",
     "InfoZoneGroup",
-    "InfoZonesOverview",
     "InfoZoneStruct",
+    "InfoZonesOverview",
     "IpAddress",
     "KnownActionName",
     "KnownBoardName",
@@ -189,18 +189,18 @@ __all__ = [
     "MacAddress",
     "NetworkType",
     "Node",
+    "NodeActionItemList",
     "NodeAirQualityIndex",
     "NodeAssociationId",
-    "NodeActionItemList",
     "NodeCo2Ppm",
     "NodeGeneralInfo",
     "NodeIdentify",
     "NodeInfoModuleSelector",
     "NodeListActionItemList",
     "NodeMotorDeviceType",
-    "NodeMotorStateInfo",
     "NodeMotorPosition",
     "NodeMotorRequest",
+    "NodeMotorStateInfo",
     "NodeName",
     "NodeOverview",
     "NodeParentId",
@@ -216,8 +216,8 @@ __all__ = [
     "PatchConfigHeatRecovery",
     "PatchConfigHeatRecoveryBypass",
     "PatchConfigLan",
-    "PatchConfigModel",
     "PatchConfigModbus",
+    "PatchConfigModel",
     "PatchConfigNodeStruct",
     "PatchConfigNodeValue",
     "PatchConfigTime",

{python_duco_connectivity-0.5.0 → python_duco_connectivity-0.7.0}/src/duco_connectivity/cli.py

@@ -77,6 +77,9 @@ METHOD_SPECS: dict[str, MethodSpec] = {
     ),
     "async_get_board_info": MethodSpec(description="Return board identity details."),
     "async_get_lan_info": MethodSpec(description="Return LAN settings."),
+    "async_get_diagnostics_info": MethodSpec(
+        description="Return the typed diagnostics response from /info?module=Diag."
+    ),
     "async_get_diagnostics": MethodSpec(description="Return diagnostic subsystem states."),
     "async_get_nodes": MethodSpec(description="Return full node information."),
     "async_get_zones_info": MethodSpec(description="Return zone information."),

{python_duco_connectivity-0.5.0 → python_duco_connectivity-0.7.0}/src/duco_connectivity/client.py

@@ -53,7 +53,7 @@ from .models import (
     ConfigZoneWithGroupStruct,
     DeviceGroupConfigSubmoduleSelector,
     DiagComponent,
-    DiagStatus,
+    DiagInfo,
     InfoGeneralSubmoduleSelector,
     InfoGroup,
     InfoGroupStruct,
@@ -281,6 +281,31 @@ class DucoClient:
     def _read_wrapped_value(payload: dict[str, Any], key: str) -> Any:
         return payload[key]["Val"]
 
+    @staticmethod
+    def _read_optional_wrapped_int(
+        payload: dict[str, Any],
+        key: str,
+        *,
+        path: str,
+    ) -> int | None:
+        """Read an optional wrapped integer from a typed-stable API branch."""
+        if key not in payload:
+            return None
+        raw_entry = payload[key]
+        if not isinstance(raw_entry, dict):
+            msg = f"Expected wrapped Val object for {path}.{key}, got {type(raw_entry).__name__}"
+            raise DucoError(msg)
+        if "Val" not in raw_entry:
+            msg = f"Expected wrapped Val object for {path}.{key}"
+            raise DucoError(msg)
+
+        raw_value = raw_entry["Val"]
+        if type(raw_value) is not int:
+            msg = f"Expected integer value for {path}.{key}, got {type(raw_value).__name__}"
+            raise DucoError(msg)
+
+        return raw_value
+
     @staticmethod
     def _read_scalar_value(payload: dict[str, Any], key: str) -> Any:
         raw_value = payload[key]
@@ -1240,17 +1265,6 @@ class DucoClient:
             )
             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_action_result_status(raw_value: str) -> ActionResultStatus:
         try:
@@ -1919,17 +1933,76 @@ class DucoClient:
             raw_payload=self._preserve_raw_payload(lan),
         )
 
+    @classmethod
+    def _parse_diag_component(cls, payload: Any, *, path: str) -> DiagComponent | None:
+        if not isinstance(payload, dict):
+            _LOGGER.debug(
+                "Skipping diagnostic subsystem at %s: expected object, got %s",
+                path,
+                type(payload).__name__,
+            )
+            return None
+
+        component = payload.get("Component")
+        status = payload.get("Status")
+        if not isinstance(component, str) or not component:
+            _LOGGER.debug(
+                "Skipping diagnostic subsystem at %s: missing non-empty string Component",
+                path,
+            )
+            return None
+        if not isinstance(status, str) or not status:
+            _LOGGER.debug(
+                "Skipping diagnostic subsystem at %s: missing non-empty string Status",
+                path,
+            )
+            return None
+
+        return DiagComponent(
+            component=component,
+            status=status,
+            raw_payload=cls._preserve_raw_payload(payload),
+        )
+
+    @classmethod
+    def _parse_diag_info(cls, payload: Any) -> DiagInfo:
+        if not isinstance(payload, dict):
+            msg = f"Expected object payload from /info?module=Diag, got {type(payload).__name__}"
+            raise DucoError(msg)
+
+        diag_payload = payload.get("Diag")
+        if diag_payload is None:
+            return DiagInfo()
+        if not isinstance(diag_payload, dict):
+            msg = f"Expected object for Diag, got {type(diag_payload).__name__}"
+            raise DucoError(msg)
+
+        raw_subsystems = diag_payload.get("SubSystems")
+        if raw_subsystems is None:
+            return DiagInfo(raw_payload=cls._preserve_raw_payload(diag_payload))
+        if not isinstance(raw_subsystems, list):
+            msg = f"Expected list for Diag.SubSystems, got {type(raw_subsystems).__name__}"
+            raise DucoError(msg)
+
+        diagnostic_subsystems: list[DiagComponent] = []
+        for index, item in enumerate(raw_subsystems):
+            subsystem = cls._parse_diag_component(item, path=f"Diag.SubSystems[{index}]")
+            if subsystem is not None:
+                diagnostic_subsystems.append(subsystem)
+
+        return DiagInfo(
+            diagnostic_subsystems=tuple(diagnostic_subsystems),
+            raw_payload=cls._preserve_raw_payload(diag_payload),
+        )
+
+    async def async_get_diagnostics_info(self) -> DiagInfo:
+        """Return diagnostic subsystem details reported by the box."""
+        payload = await self.async_get_info(module="Diag")
+        return self._parse_diag_info(payload)
+
     async def async_get_diagnostics(self) -> list[DiagComponent]:
         """Return health states for diagnostic subsystems."""
-        payload = await self.async_get_info(module="Diag")
-        return [
-            DiagComponent(
-                component=item["Component"],
-                status=self._to_diag_status(item["Status"]),
-                raw_payload=self._preserve_raw_payload(item),
-            )
-            for item in payload["Diag"]["SubSystems"]
-        ]
+        return list((await self.async_get_diagnostics_info()).diagnostic_subsystems)
 
     async def async_get_nodes(self) -> list[Node]:
         """Return nodes reported by the local API."""
@@ -2037,6 +2110,39 @@ class DucoClient:
         )
         return int(self._read_wrapped_value(payload["General"]["PublicApi"], "WriteReqCntRemain"))
 
+    async def async_get_time_filter_remaining(self) -> int | None:
+        """Return the remaining heat recovery filter time when the box reports it."""
+        payload = await self.async_get_info(module=InfoModuleSelector.HEAT_RECOVERY)
+        if not isinstance(payload, dict):
+            msg = (
+                "Expected object payload from /info?module=HeatRecovery, got "
+                f"{type(payload).__name__}"
+            )
+            raise DucoError(msg)
+
+        heat_recovery = payload.get("HeatRecovery")
+        if heat_recovery is None:
+            return None
+        if not isinstance(heat_recovery, dict):
+            msg = "Expected object payload at HeatRecovery in /info?module=HeatRecovery response"
+            raise DucoError(msg)
+
+        general = heat_recovery.get("General")
+        if general is None:
+            return None
+        if not isinstance(general, dict):
+            msg = (
+                "Expected object payload at HeatRecovery.General in "
+                "/info?module=HeatRecovery response"
+            )
+            raise DucoError(msg)
+
+        return self._read_optional_wrapped_int(
+            general,
+            "TimeFilterRemain",
+            path="HeatRecovery.General",
+        )
+
     async def async_get_write_req_remaining(self) -> int:
         """Backward-compatible alias for the old write budget method name."""
         caller = _compat_caller()

{python_duco_connectivity-0.5.0 → python_duco_connectivity-0.7.0}/src/duco_connectivity/models.py

@@ -1128,11 +1128,6 @@ class _PatchPayloadModel:
     __slots__ = ()
 
 
-def _patch_field(api_name: str) -> Any:
-    """Return a dataclass field that stores the API key mapping."""
-    return field(default=None, metadata={"api_name": api_name})
-
-
 class PatchConfigModel(_PatchPayloadModel):
     """Base class for typed `/config` patch payload models."""
 
@@ -1150,98 +1145,152 @@ class PatchConfigValue:
 class PatchConfigTime(PatchConfigModel):
     """Typed time-related patch payload for `/config`."""
 
-    time_zone: PatchConfigValue | None = _patch_field("TimeZone")
-    dst: PatchConfigValue | None = _patch_field("Dst")
+    time_zone: PatchConfigValue | None = field(
+        default=None,
+        metadata={"api_name": "TimeZone"},
+    )
+    dst: PatchConfigValue | None = field(default=None, metadata={"api_name": "Dst"})
 
 
 @dataclass(frozen=True, slots=True)
 class PatchConfigModbus(PatchConfigModel):
     """Typed Modbus patch payload for `/config`."""
 
-    addr: PatchConfigValue | None = _patch_field("Addr")
-    offset: PatchConfigValue | None = _patch_field("Offset")
+    addr: PatchConfigValue | None = field(default=None, metadata={"api_name": "Addr"})
+    offset: PatchConfigValue | None = field(default=None, metadata={"api_name": "Offset"})
 
 
 @dataclass(frozen=True, slots=True)
 class PatchConfigLan(PatchConfigModel):
     """Typed LAN patch payload for `/config`."""
 
-    mode: PatchConfigValue | None = _patch_field("Mode")
-    dhcp: PatchConfigValue | None = _patch_field("Dhcp")
-    static_ip: PatchConfigValue | None = _patch_field("StaticIp")
-    static_net_mask: PatchConfigValue | None = _patch_field("StaticNetMask")
-    static_default_gateway: PatchConfigValue | None = _patch_field("StaticDefaultGateway")
-    static_dns: PatchConfigValue | None = _patch_field("StaticDns")
-    wifi_client_ssid: PatchConfigValue | None = _patch_field("WifiClientSsid")
-    wifi_client_key: PatchConfigValue | None = _patch_field("WifiClientKey")
+    mode: PatchConfigValue | None = field(default=None, metadata={"api_name": "Mode"})
+    dhcp: PatchConfigValue | None = field(default=None, metadata={"api_name": "Dhcp"})
+    static_ip: PatchConfigValue | None = field(default=None, metadata={"api_name": "StaticIp"})
+    static_net_mask: PatchConfigValue | None = field(
+        default=None,
+        metadata={"api_name": "StaticNetMask"},
+    )
+    static_default_gateway: PatchConfigValue | None = field(
+        default=None,
+        metadata={"api_name": "StaticDefaultGateway"},
+    )
+    static_dns: PatchConfigValue | None = field(default=None, metadata={"api_name": "StaticDns"})
+    wifi_client_ssid: PatchConfigValue | None = field(
+        default=None,
+        metadata={"api_name": "WifiClientSsid"},
+    )
+    wifi_client_key: PatchConfigValue | None = field(
+        default=None,
+        metadata={"api_name": "WifiClientKey"},
+    )
 
 
 @dataclass(frozen=True, slots=True)
 class PatchConfigAutoRebootComm(PatchConfigModel):
     """Typed auto-reboot communication patch payload for `/config`."""
 
-    period: PatchConfigValue | None = _patch_field("Period")
-    time: PatchConfigValue | None = _patch_field("Time")
+    period: PatchConfigValue | None = field(default=None, metadata={"api_name": "Period"})
+    time: PatchConfigValue | None = field(default=None, metadata={"api_name": "Time"})
 
 
 @dataclass(frozen=True, slots=True)
 class PatchConfigGeneral(PatchConfigModel):
     """Typed `General` patch payload for `/config`."""
 
-    time: PatchConfigTime | None = _patch_field("Time")
-    modbus: PatchConfigModbus | None = _patch_field("Modbus")
-    lan: PatchConfigLan | None = _patch_field("Lan")
-    auto_reboot_comm: PatchConfigAutoRebootComm | None = _patch_field("AutoRebootComm")
+    time: PatchConfigTime | None = field(default=None, metadata={"api_name": "Time"})
+    modbus: PatchConfigModbus | None = field(default=None, metadata={"api_name": "Modbus"})
+    lan: PatchConfigLan | None = field(default=None, metadata={"api_name": "Lan"})
+    auto_reboot_comm: PatchConfigAutoRebootComm | None = field(
+        default=None,
+        metadata={"api_name": "AutoRebootComm"},
+    )
 
 
 @dataclass(frozen=True, slots=True)
 class PatchConfigHeatRecoveryBypass(PatchConfigModel):
     """Typed bypass patch payload for `/config`."""
 
-    temp_sup_tgt_zone_1: PatchConfigValue | None = _patch_field("TempSupTgtZone1")
-    temp_sup_tgt_zone_2: PatchConfigValue | None = _patch_field("TempSupTgtZone2")
-    temp_sup_tgt_zone_3: PatchConfigValue | None = _patch_field("TempSupTgtZone3")
-    temp_sup_tgt_zone_4: PatchConfigValue | None = _patch_field("TempSupTgtZone4")
-    temp_sup_tgt_zone_5: PatchConfigValue | None = _patch_field("TempSupTgtZone5")
-    temp_sup_tgt_zone_6: PatchConfigValue | None = _patch_field("TempSupTgtZone6")
-    temp_sup_tgt_zone_7: PatchConfigValue | None = _patch_field("TempSupTgtZone7")
-    temp_sup_tgt_zone_8: PatchConfigValue | None = _patch_field("TempSupTgtZone8")
+    temp_sup_tgt_zone_1: PatchConfigValue | None = field(
+        default=None,
+        metadata={"api_name": "TempSupTgtZone1"},
+    )
+    temp_sup_tgt_zone_2: PatchConfigValue | None = field(
+        default=None,
+        metadata={"api_name": "TempSupTgtZone2"},
+    )
+    temp_sup_tgt_zone_3: PatchConfigValue | None = field(
+        default=None,
+        metadata={"api_name": "TempSupTgtZone3"},
+    )
+    temp_sup_tgt_zone_4: PatchConfigValue | None = field(
+        default=None,
+        metadata={"api_name": "TempSupTgtZone4"},
+    )
+    temp_sup_tgt_zone_5: PatchConfigValue | None = field(
+        default=None,
+        metadata={"api_name": "TempSupTgtZone5"},
+    )
+    temp_sup_tgt_zone_6: PatchConfigValue | None = field(
+        default=None,
+        metadata={"api_name": "TempSupTgtZone6"},
+    )
+    temp_sup_tgt_zone_7: PatchConfigValue | None = field(
+        default=None,
+        metadata={"api_name": "TempSupTgtZone7"},
+    )
+    temp_sup_tgt_zone_8: PatchConfigValue | None = field(
+        default=None,
+        metadata={"api_name": "TempSupTgtZone8"},
+    )
 
 
 @dataclass(frozen=True, slots=True)
 class PatchConfigHeatRecovery(PatchConfigModel):
     """Typed `HeatRecovery` patch payload for `/config`."""
 
-    bypass: PatchConfigHeatRecoveryBypass | None = _patch_field("Bypass")
+    bypass: PatchConfigHeatRecoveryBypass | None = field(
+        default=None,
+        metadata={"api_name": "Bypass"},
+    )
 
 
 @dataclass(frozen=True, slots=True)
 class PatchConfig(PatchConfigModel):
     """Typed top-level patch payload for `/config`."""
 
-    general: PatchConfigGeneral | None = _patch_field("General")
-    heat_recovery: PatchConfigHeatRecovery | None = _patch_field("HeatRecovery")
+    general: PatchConfigGeneral | None = field(default=None, metadata={"api_name": "General"})
+    heat_recovery: PatchConfigHeatRecovery | None = field(
+        default=None,
+        metadata={"api_name": "HeatRecovery"},
+    )
 
 
 @dataclass(frozen=True, slots=True)
 class PatchConfigZoneGeneral(_PatchPayloadModel):
     """Typed `General` patch payload under `DeviceGroupConfig` for a zone."""
 
-    name: PatchConfigValue | None = _patch_field("Name")
+    name: PatchConfigValue | None = field(default=None, metadata={"api_name": "Name"})
 
 
 @dataclass(frozen=True, slots=True)
 class PatchConfigZoneDeviceGroupConfig(_PatchPayloadModel):
     """Typed `DeviceGroupConfig` patch payload for `/config/zones/{zone}`."""
 
-    general: PatchConfigZoneGeneral | None = _patch_field("General")
+    general: PatchConfigZoneGeneral | None = field(
+        default=None,
+        metadata={"api_name": "General"},
+    )
 
 
 @dataclass(frozen=True, slots=True)
 class PatchConfigZoneStruct(_PatchPayloadModel):
     """Typed zone config patch payload for stable writable zone fields."""
 
-    device_group_config: PatchConfigZoneDeviceGroupConfig | None = _patch_field("DeviceGroupConfig")
+    device_group_config: PatchConfigZoneDeviceGroupConfig | None = field(
+        default=None,
+        metadata={"api_name": "DeviceGroupConfig"},
+    )
 
 
 @dataclass(frozen=True, slots=True)
@@ -1309,7 +1358,7 @@ class PatchConfigNodeValue:
 class PatchConfigNodeStruct(_PatchPayloadModel):
     """Typed node config patch payload for stable writable node fields."""
 
-    name: PatchConfigNodeValue | None = _patch_field("Name")
+    name: PatchConfigNodeValue | None = field(default=None, metadata={"api_name": "Name"})
 
 
 @dataclass(frozen=True, slots=True, init=False)
@@ -1500,7 +1549,15 @@ class DiagComponent:
     """Health state for a diagnostic subsystem."""
 
     component: str
-    status: DiagStatus
+    status: str
+    raw_payload: dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+
+@dataclass(frozen=True, slots=True)
+class DiagInfo:
+    """Diagnostic subsystem payload returned by the local Duco API."""
+
+    diagnostic_subsystems: tuple[DiagComponent, ...] = ()
     raw_payload: dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
 
 

{python_duco_connectivity-0.5.0 → python_duco_connectivity-0.7.0/src/python_duco_connectivity.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-duco-connectivity
-Version: 0.5.0
+Version: 0.7.0
 Summary: Async HTTP client for the local Duco Connectivity API
 Author: Ronald van der Meer
 License-Expression: MIT
@@ -27,7 +27,7 @@ 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"
+Requires-Dist: ruff>=0.15.14; extra == "dev"
 Dynamic: license-file
 
 # python-duco-connectivity
@@ -63,9 +63,14 @@ in the development examples below.
 - HTTP only
 - 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
 - typed models that stay close to the API response shape
 - preserved `raw_payload` data on typed response models for forward compatibility
 
+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.
+
 ## Getting started
 
 ```python
@@ -188,6 +193,7 @@ development pass, covering:
 - `PATCH /config` with a no-op `TimeZone` write against the current value
 - `GET /info?module=General&submodule=Board`
 - `GET /info?module=General&submodule=Lan`
+- `GET /info?module=HeatRecovery`
 - `GET /info/nodes`
 - `GET /info?module=General&submodule=PublicApi`
 - `POST /action/nodes/{node}` with a no-op `SetVentilationState`

{python_duco_connectivity-0.5.0 → python_duco_connectivity-0.7.0}/src/python_duco_connectivity.egg-info/requires.txt

@@ -8,4 +8,4 @@ pip-audit>=2.7
 pytest>=8.0
 pytest-asyncio>=0.23
 pytest-cov>=5.0
-ruff>=0.11
+ruff>=0.15.14

{python_duco_connectivity-0.5.0 → python_duco_connectivity-0.7.0}/tests/test_client.py

@@ -3,7 +3,7 @@
 import logging
 import re
 from dataclasses import dataclass, field
-from typing import Any, cast
+from typing import Any, assert_type, cast
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import aiohttp
@@ -39,7 +39,8 @@ from duco_connectivity import (
     ConfigZonesOverview,
     ConfigZoneWithGroupStruct,
     DeviceGroupConfigSubmoduleSelector,
-    DiagStatus,
+    DiagComponent,
+    DiagInfo,
     DucoClient,
     DucoConnectionError,
     DucoError,
@@ -1284,7 +1285,7 @@ async def test_set_config_rejects_patch_model_without_api_name_metadata() -> Non
         client = DucoClient(session=session, host="192.0.2.94")
         with pytest.raises(
             ValueError,
-            match="Patch model field BrokenPatch.mode must declare api_name metadata",
+            match=re.escape("Patch model field BrokenPatch.mode must declare api_name metadata"),
         ):
             await client.async_set_config(BrokenPatch(mode=PatchConfigValue(value=2)))
 
@@ -1299,7 +1300,7 @@ async def test_set_config_invalid_response_raises_duco_error() -> None:
             patch.object(session, "request", _request(mock_response)),
             pytest.raises(
                 DucoError,
-                match="Unsupported config value type bool for General.Lan.Mode",
+                match=re.escape("Unsupported config value type bool for General.Lan.Mode"),
             ),
         ):
             await client.async_set_config({"General": {"Lan": {"Mode": PatchConfigValue(value=2)}}})
@@ -1829,7 +1830,9 @@ async def test_set_node_config_invalid_response_raises_duco_error() -> None:
             patch.object(session, "request", _request(mock_response)),
             pytest.raises(
                 DucoError,
-                match="Expected string Val for node config value /config/nodes/7.Name, got int",
+                match=re.escape(
+                    "Expected string Val for node config value /config/nodes/7.Name, got int"
+                ),
             ),
         ):
             await client.async_set_node_config(
@@ -2060,12 +2063,40 @@ async def test_get_diagnostics(diag_data: dict[str, object]) -> None:
 
     assert len(diags) == 3
     assert diags[0].component == "Ventilation"
-    assert diags[0].status == DiagStatus.OK
+    assert diags[0].status == "Ok"
     assert diags[0].raw_payload is diag_data["Diag"]["SubSystems"][0]
 
 
-async def test_get_diagnostics_unknown_status_falls_back_to_unknown() -> None:
-    """Unknown diagnostic statuses should not break parsing."""
+async def test_get_diagnostics_info_exposes_typed_subsystems(
+    diag_data: dict[str, object],
+) -> None:
+    """Typed diagnostics info should expose an immutable subsystem collection."""
+    mock_response = _response(json_payload=diag_data)
+
+    async with aiohttp.ClientSession() as session:
+        client = DucoClient(session=session, host="192.0.2.94")
+        with patch.object(session, "request", _request(mock_response)):
+            diag_info = await client.async_get_diagnostics_info()
+
+    assert isinstance(diag_info, DiagInfo)
+    assert_type(diag_info, DiagInfo)
+    assert_type(diag_info.diagnostic_subsystems, tuple[DiagComponent, ...])
+    assert_type(diag_info.diagnostic_subsystems[0].component, str)
+    assert_type(diag_info.diagnostic_subsystems[0].status, str)
+    assert tuple(item.component for item in diag_info.diagnostic_subsystems) == (
+        "Ventilation",
+        "VentCool",
+        "SunCtrl",
+    )
+    assert tuple(item.status for item in diag_info.diagnostic_subsystems) == (
+        "Ok",
+        "Ok",
+        "Ok",
+    )
+
+
+async def test_get_diagnostics_preserves_unknown_status() -> None:
+    """Unknown diagnostic statuses should be preserved as raw strings."""
     payload: dict[str, object] = {
         "Diag": {
             "SubSystems": [
@@ -2081,7 +2112,104 @@ async def test_get_diagnostics_unknown_status_falls_back_to_unknown() -> None:
             diags = await client.async_get_diagnostics()
 
     assert len(diags) == 1
-    assert diags[0].status == DiagStatus.UNKNOWN
+    assert diags[0].status == "FutureState"
+
+
+async def test_get_diagnostics_preserves_unknown_component_name() -> None:
+    """Unknown diagnostic subsystem names should remain available to consumers."""
+    payload: dict[str, object] = {
+        "Diag": {
+            "SubSystems": [
+                {"Component": "FutureSubsystem", "Status": "Ok"},
+            ]
+        }
+    }
+    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)):
+            diag_info = await client.async_get_diagnostics_info()
+
+    assert tuple(item.component for item in diag_info.diagnostic_subsystems) == ("FutureSubsystem",)
+
+
+@pytest.mark.parametrize(
+    ("payload", "expected_raw_payload"),
+    [
+        pytest.param({}, {}, id="diag-missing"),
+        pytest.param({"Diag": {}}, {}, id="subsystems-missing"),
+        pytest.param({"Diag": {"SubSystems": []}}, {"SubSystems": []}, id="subsystems-empty"),
+    ],
+)
+async def test_get_diagnostics_info_missing_data_returns_empty_collection(
+    payload: dict[str, object],
+    expected_raw_payload: dict[str, object],
+) -> None:
+    """Missing diagnostic data should produce an empty typed subsystem collection."""
+    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)):
+            diag_info = await client.async_get_diagnostics_info()
+
+    assert diag_info.diagnostic_subsystems == ()
+    assert diag_info.raw_payload == expected_raw_payload
+
+
+async def test_get_diagnostics_info_skips_partial_entries() -> None:
+    """Incomplete diagnostic entries should be ignored instead of failing parsing."""
+    payload: dict[str, object] = {
+        "Diag": {
+            "SubSystems": [
+                {"Component": "Ventilation", "Status": "Ok"},
+                {"Component": "VentCool"},
+                {"Status": "Error"},
+                {},
+                "not-a-dict",
+                {"Component": "SunCtrl", "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)):
+            diag_info = await client.async_get_diagnostics_info()
+
+    assert tuple((item.component, item.status) for item in diag_info.diagnostic_subsystems) == (
+        ("Ventilation", "Ok"),
+        ("SunCtrl", "FutureState"),
+    )
+
+
+async def test_get_diagnostics_info_does_not_filter_product_specific_subsystems() -> None:
+    """Subsystems should be passed through without product-specific filtering."""
+    payload: dict[str, object] = {
+        "Diag": {
+            "SubSystems": [
+                {"Component": "Ventilation", "Status": "Error"},
+                {"Component": "VentCool", "Status": "Ok"},
+                {"Component": "SunCtrl", "Status": "Ok"},
+                {"Component": "FutureSubsystem", "Status": "Disable"},
+            ]
+        }
+    }
+    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)):
+            diag_info = await client.async_get_diagnostics_info()
+
+    assert tuple(item.component for item in diag_info.diagnostic_subsystems) == (
+        "Ventilation",
+        "VentCool",
+        "SunCtrl",
+        "FutureSubsystem",
+    )
 
 
 async def test_get_nodes_parses_full_payload(nodes_data: dict[str, object]) -> None:
@@ -2880,7 +3008,7 @@ async def test_set_zone_config_invalid_response_raises_duco_error() -> None:
             patch.object(session, "request", _request(mock_response)),
             pytest.raises(
                 DucoError,
-                match=(
+                match=re.escape(
                     "Expected string Val for zone config value "
                     "/config/zones/1.DeviceGroupConfig.General.Name, got int"
                 ),
@@ -3538,6 +3666,88 @@ async def test_get_write_requests_remaining_is_parsed() -> None:
     assert remaining == 197
 
 
+async def test_get_time_filter_remaining_is_parsed() -> None:
+    """Heat recovery filter time should be parsed when the box reports it."""
+    payload: dict[str, object] = {"HeatRecovery": {"General": {"TimeFilterRemain": {"Val": 180}}}}
+    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_time_filter_remaining()
+
+    assert remaining == 180
+
+
+async def test_get_time_filter_remaining_returns_none_when_not_reported() -> None:
+    """Heat recovery filter time should stay optional for boxes that omit it."""
+    payload: dict[str, object] = {"HeatRecovery": {"General": {}}}
+    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_time_filter_remaining()
+
+    assert remaining is None
+
+
+@pytest.mark.parametrize(
+    ("payload", "message"),
+    [
+        pytest.param(
+            [],
+            "Expected object payload from /info?module=HeatRecovery, got list",
+            id="root_not_object",
+        ),
+        pytest.param(
+            {"HeatRecovery": []},
+            "Expected object payload at HeatRecovery in /info?module=HeatRecovery response",
+            id="heat_recovery_not_object",
+        ),
+        pytest.param(
+            {"HeatRecovery": {"General": []}},
+            "Expected object payload at HeatRecovery.General in /info?module=HeatRecovery response",
+            id="general_not_object",
+        ),
+        pytest.param(
+            {"HeatRecovery": {"General": {"TimeFilterRemain": 180}}},
+            "Expected wrapped Val object for HeatRecovery.General.TimeFilterRemain, got int",
+            id="leaf_not_object",
+        ),
+        pytest.param(
+            {"HeatRecovery": {"General": {"TimeFilterRemain": None}}},
+            "Expected wrapped Val object for HeatRecovery.General.TimeFilterRemain, got NoneType",
+            id="leaf_null",
+        ),
+        pytest.param(
+            {"HeatRecovery": {"General": {"TimeFilterRemain": {}}}},
+            "Expected wrapped Val object for HeatRecovery.General.TimeFilterRemain",
+            id="leaf_missing_val",
+        ),
+        pytest.param(
+            {"HeatRecovery": {"General": {"TimeFilterRemain": {"Val": "180"}}}},
+            "Expected integer value for HeatRecovery.General.TimeFilterRemain, got str",
+            id="leaf_non_int_val",
+        ),
+    ],
+)
+async def test_get_time_filter_remaining_rejects_malformed_payloads(
+    payload: object,
+    message: str,
+) -> None:
+    """Malformed heat recovery payloads should raise DucoError."""
+    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)),
+            pytest.raises(DucoError, match=re.escape(message)),
+        ):
+            await client.async_get_time_filter_remaining()
+
+
 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}}}}