python-izone 1.3.3__tar.gz → 1.3.4__tar.gz

{python_izone-1.3.3 → python_izone-1.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-izone
-Version: 1.3.3
+Version: 1.3.4
 Summary: A python interface to the iZone airconditioner controller
 Project-URL: Homepage, https://github.com/Swamp-Ig/pizone
 Author-email: Penny Wood <pypl@ninjateaparty.com>

python_izone-1.3.4/docs/release-notes/v1.3.4.md

@@ -0,0 +1,55 @@
+# Release notes — v1.3.4
+
+Released 2026-07-12. Maintenance and modernization release for the Home Assistant
+iZone integration.
+
+Shipped as **1.3.4** because PyPI versions `1.3.0`–`1.3.3` from an earlier
+premature release line remain yanked and cannot be replaced.
+
+**Compare range:** https://github.com/Swamp-Ig/pizone/compare/v1.2.10...v1.3.4
+
+## Summary
+
+Since `v1.2.10`, the library has been brought up to current Python packaging
+and typing practice, moved its HTTP stack to aiohttp, clarified how connection
+and command failures are reported, expanded test coverage, and tightened
+behaviour around partial device outages.
+
+## Packaging, dependencies, and development
+
+- **Python 3.14** minimum
+- Development and releases migrated to **uv** and **Hatchling** (VCS versioning, `py.typed`)
+- **aiohttp** (`>=3.14.1`) replaces the custom HTTP client; request timeout raised to **10 seconds**
+- **`ifaddr`** replaces `netifaces` for broadcast discovery
+- Stricter **mypy** configuration; typing and style cleanup across the codebase
+- CI updated (current GitHub Actions, **PyPI trusted publishing**); hardware tests excluded from default CI runs
+- Unit test coverage raised to **~92%** with dedicated power, HTTP, and discovery tests
+
+## Error handling and connection behaviour
+
+- **Cached property reads** no longer raise when disconnected; async I/O methods raise **`ConnectionError`** for transport failures
+- **`ControllerCommandError`** for reachable devices that reject a request (`{ERROR}` POST body or HTTP 4xx)
+- **`ResponseDecodeError`** for bridge-reachable HTTP responses that cannot be decoded as JSON (keeps `bridge_connected` true without string-matching exception messages)
+- **Layered connection state:** `bridge_connected` (ASH bridge HTTP) and `connected` (bridge plus valid iZone AC data). Fault `SystemSettings` no longer overwrites cached state; Home Assistant can mark entities unavailable through existing disconnect listeners during partial outages (bridge up, AC subsystem down)
+- **Fault-safe property reads:** empty or fault-shaped system settings return safe defaults so polling and entity bootstrap do not crash on `KeyError` or invalid enum values
+- **`Power.connected`** tracks power monitor I/O separately and does not clear `Controller.connected`
+- Optional subsystem I/O (power, V2 probe) uses untracked HTTP helpers so init-time probe failures do not poison controller connection state
+- Connection restore and reconnect notification fixes, including deduplication of failed init attempts and a `DiscoveryService` shutdown race
+
+## Protocol and performance
+
+- **Zones 13–14** supported via the zone extender endpoint (`Zones13_14`)
+- Controller resources refreshed **concurrently** (`asyncio.gather` with serialized HTTP via `_sending_lock`)
+- Runtime **V2** and **iPower** capability detection via non-fatal init probes (overrides or supplements discovery datagram hints)
+
+## Documentation
+
+- Public API and I/O method docstrings document exception behaviour and cached-read semantics
+- Package docstring documents layered connection properties (`bridge_connected`, `connected`, `Power.connected`)
+- README and inline docs updated for aiohttp requirements and development workflow
+
+## Other fixes
+
+- Discovery accepts `X` in the AC capability slot (per iZone docs, means subsystem unavailable in that slot — not an invalid bridge)
+- Power `status_last_reading` key correction
+- `controller_reconnected` KeyError when UID missing from internal disconnect tracking

{python_izone-1.3.3 → python_izone-1.3.4}/pizone/__init__.py

@@ -8,17 +8,24 @@ Synchronous property reads return cached device data and do not raise
 raise :exc:`ConnectionError` when the device cannot be reached. They raise
 :exc:`~pizone.exceptions.ControllerCommandError` when the device responds but
 rejects the request (``{ERROR...}`` body or HTTP 4xx).
+
+Layered connection state on :class:`~pizone.controller.Controller`:
+
+- :attr:`~pizone.controller.Controller.bridge_connected` — ASH bridge HTTP transport
+- :attr:`~pizone.controller.Controller.connected` — bridge plus valid iZone AC data
+- :attr:`~pizone.power.Power.connected` — power monitor I/O (when enabled)
 """
 
 from .controller import Controller
 from .discovery import DiscoveryService, Listener, discovery
-from .exceptions import ControllerCommandError
+from .exceptions import ControllerCommandError, ResponseDecodeError
 from .power import BatteryLevel, Power, PowerChannel, PowerDevice, PowerGroup
 from .zone import Zone
 
 __all__ = [
     "Controller",
     "ControllerCommandError",
+    "ResponseDecodeError",
     "Zone",
     "DiscoveryService",
     "Listener",

{python_izone-1.3.3 → python_izone-1.3.4}/pizone/controller.py

@@ -11,7 +11,7 @@ from typing import TYPE_CHECKING, Any, cast
 
 import aiohttp
 
-from .exceptions import ControllerCommandError
+from .exceptions import ControllerCommandError, ResponseDecodeError
 from .power import Power
 from .zone import Zone
 
@@ -79,6 +79,27 @@ class Controller:
         "var-speed": [Fan.LOW, Fan.MED, Fan.HIGH, Fan.AUTO],
     }
 
+    _FAULT_STATE_VALUES = frozenset({"error"})
+    _SYSTEM_STATE_DEFAULTS: ControllerData = {
+        "SysOn": "off",
+        "SysMode": "cool",
+        "SysFan": "auto",
+        "SleepTimer": 0,
+        "FreeAir": "disabled",
+        "Supply": "0.0",
+        "Setpoint": "0.0",
+        "Temp": "0.0",
+        "EcoLock": "false",
+        "EcoMin": "15.0",
+        "EcoMax": "30.0",
+        "RAS": "zones",
+        "CtrlZone": 0,
+        "NoOfZones": 0,
+        "NoOfConst": 0,
+        "SysType": "0",
+        "FanAuto": "disabled",
+    }
+
     def __init__(
         self,
         discovery_service: DiscoveryService,
@@ -280,14 +301,13 @@ class Controller:
 
     @property
     def mode(self) -> Mode:
-        """System mode (cooling, heating, etc.).
-
-        Raises:
-            ValueError: If the cached mode is not a valid :class:`Mode` member.
-        """
+        """System mode (cooling, heating, etc.)."""
         if self.free_air:
             return self.Mode.FREE_AIR
-        return self.Mode(self._get_system_state("SysMode"))
+        try:
+            return self.Mode(self._get_system_state("SysMode"))
+        except ValueError:
+            return self.Mode.COOL
 
     async def set_mode(self, value: Mode) -> None:
         """Set the system mode (cooling, heating, etc.).
@@ -309,12 +329,11 @@ class Controller:
 
     @property
     def fan(self) -> Fan:
-        """The current fan level.
-
-        Raises:
-            ValueError: If the cached fan mode is not a valid :class:`Fan` member.
-        """
-        return self.Fan(self._get_system_state("SysFan"))
+        """The current fan level."""
+        try:
+            return self.Fan(self._get_system_state("SysFan"))
+        except ValueError:
+            return self.Fan.AUTO
 
     async def set_fan(self, value: Fan) -> None:
         """Set the fan level.
@@ -606,7 +625,13 @@ class Controller:
         )
 
     def _get_system_state(self, state: str) -> DictValue:
-        return self._system_settings[state]
+        default = self._SYSTEM_STATE_DEFAULTS.get(state, "")
+        value = self._system_settings.get(state)
+        if value is None:
+            return default
+        if state in ("SysFan", "RAS", "SysMode") and str(value) in self._FAULT_STATE_VALUES:
+            return default
+        return value
 
     async def _set_system_state(
         self,
@@ -691,8 +716,8 @@ class Controller:
         """Fetch a JSON resource via HTTP GET without updating connection state.
 
         Raises:
-            ConnectionError: If the device cannot be reached or the response
-                cannot be decoded.
+            ConnectionError: If the device cannot be reached.
+            ResponseDecodeError: If the response cannot be decoded as JSON.
             ControllerCommandError: If the device returns HTTP 4xx.
         """
         session = self._discovery_service.session
@@ -716,7 +741,7 @@ class Controller:
                 if text[-4:] == "{OK}":
                     return json.loads(text[:-4])
                 _LOG.error('Decode error for "%s"', text, exc_info=True)
-                raise ConnectionError(
+                raise ResponseDecodeError(
                     "Unable to decode response from the controller"
                 ) from ex
 
@@ -762,8 +787,8 @@ class Controller:
         """Fetch a JSON resource from the device via HTTP GET.
 
         Raises:
-            ConnectionError: If the device cannot be reached, the response
-                cannot be decoded, or the HTTP request fails.
+            ConnectionError: If the device cannot be reached or the HTTP request fails.
+            ResponseDecodeError: If the response cannot be decoded as JSON.
             ControllerCommandError: If the device returns HTTP 4xx.
         """
         try:
@@ -776,11 +801,11 @@ class Controller:
                 False, ConnectionError("Unable to connect to the controller")
             )
             raise ConnectionError("Unable to connect to the controller") from ex
+        except ResponseDecodeError:
+            self._set_bridge_ok(True)
+            raise
         except ConnectionError as ex:
-            if str(ex) == "Unable to decode response from the controller":
-                self._set_bridge_ok(True)
-            else:
-                self._set_bridge_ok(False, ex)
+            self._set_bridge_ok(False, ex)
             raise
         self._set_bridge_ok(True)
         return result

{python_izone-1.3.3 → python_izone-1.3.4}/pizone/exceptions.py

@@ -8,3 +8,11 @@ class ControllerCommandError(Exception):
     device is reachable. Not used for transport failures (timeouts, connection
     refused, etc.) — those remain :exc:`ConnectionError`.
     """
+
+
+class ResponseDecodeError(ConnectionError):
+    """The bridge responded over HTTP but the body could not be decoded as JSON.
+
+    Raised when transport succeeds and the response is not a transport failure,
+    but JSON parsing fails (and the ``{OK}`` suffix workaround does not apply).
+    """

{python_izone-1.3.3 → python_izone-1.3.4}/pizone/version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.3.3'
-__version_tuple__ = version_tuple = (1, 3, 3)
+__version__ = version = '1.3.4'
+__version_tuple__ = version_tuple = (1, 3, 4)
 
 __commit_id__ = commit_id = None

{python_izone-1.3.3 → python_izone-1.3.4}/tests/test_controller.py

@@ -428,6 +428,45 @@ async def test_init_fault_disconnect_listener() -> None:
     assert controller.zones == []
 
 
+@pytest.mark.asyncio
+async def test_init_fault_property_reads_no_crash() -> None:
+    listener = _DisconnectListener()
+    svc = MockDiscoveryService()
+    controller = MockController(
+        svc,
+        listener,
+        device_uid="000000005",
+        device_ip="10.0.0.5",
+        is_v2=False,
+        is_ipower=False,
+    )
+    controller.resources["SystemSettings"] = _fault_system_settings("000000005")
+
+    await controller._initialize()
+
+    assert controller.connected is False
+    assert controller.ras_mode == "zones"
+    assert controller.sys_type == "0"
+    assert controller.fan == Controller.Fan.AUTO
+    assert controller.mode == Controller.Mode.COOL
+    assert controller.is_on is False
+    assert controller.zones_total == 0
+
+
+@pytest.mark.asyncio
+async def test_fault_placeholder_values_in_cache_use_defaults(
+    service: MockDiscoveryService,
+) -> None:
+    controller = cast(MockController, service._controllers["000000001"])
+    controller._system_settings["SysFan"] = "error"
+    controller._system_settings["RAS"] = "error"
+    controller._system_settings["SysMode"] = "error"
+
+    assert controller.fan == Controller.Fan.AUTO
+    assert controller.ras_mode == "zones"
+    assert controller.mode == Controller.Mode.COOL
+
+
 @pytest.mark.asyncio
 async def test_both_false_on_transport_failure(service: MockDiscoveryService) -> None:
     controller = cast(MockController, service._controllers["000000001"])

{python_izone-1.3.3 → python_izone-1.3.4}/tests/test_http.py

@@ -8,7 +8,7 @@ import pytest
 from aiohttp import ClientSession
 from pytest import raises
 
-from pizone import Controller, ControllerCommandError
+from pizone import Controller, ControllerCommandError, ResponseDecodeError
 
 from .conftest import MockDiscoveryService
 from .http_fakes import FakeHttpResponse, FakeHttpSession
@@ -98,11 +98,12 @@ async def test_get_resource_decode_failure(service: MockDiscoveryService) -> Non
         ),
     )
     try:
-        with raises(ConnectionError):
+        with raises(ResponseDecodeError):
             await controller._get_resource("SystemSettings")
     finally:
         service._session = original_session
 
+    assert controller.bridge_connected is True
     assert controller.connected is True