python-izone 1.3.5__tar.gz → 1.3.6__tar.gz

{python_izone-1.3.5 → python_izone-1.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-izone
-Version: 1.3.5
+Version: 1.3.6
 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.6/docs/release-notes/v1.3.5.md

@@ -0,0 +1,85 @@
+# Release notes — v1.3.5
+
+Released 2026-07-17.
+
+**Compare range:** https://github.com/Swamp-Ig/pizone/compare/v1.3.4...v1.3.5
+
+This is a **pre-release**. It includes work toward a better Home Assistant
+integration (stored bridge IP, improved discovery, and cleaner refresh
+timing), plus reliability fixes you can use today. Home Assistant still uses
+the same library entry points as 1.3.4. The older API remains available; a
+future major release will remove it in favour of the new discovery and refresh
+API below.
+
+## Summary
+
+Since v1.3.4:
+
+- HTTP connections are closed after each GET, which greatly reduces stalls on
+  some iZone bridges ([home-assistant/core#176536](https://github.com/home-assistant/core/issues/176536))
+- A new discovery and refresh API is available for integrators (the older API
+  still works for now)
+- iPower monitoring is off unless you opt in with `ENABLE_POWER = True`
+- Bridges that are not paired to an air conditioner (UID `000000000`) are
+  ignored or rejected instead of showing up as broken controllers
+
+## Bridge connection reliability
+
+Some ASH bridges misbehave when HTTP connections are reused. This release:
+
+- Sends `Connection: close` on every HTTP GET (polling and discovery probes)
+- Closes TCP connections after each request when the library creates its own
+  aiohttp session
+
+This reduces how often the bridge stops responding. It does not fix every
+hub-side stall; replacing faulty hardware may still be needed.
+
+## New discovery and refresh API (optional for now)
+
+Integrators can adopt a clearer model without background poll loops inside the
+library:
+
+- `create_discovery()` with callbacks when a controller is found or its IP
+  changes
+- `discover_by_host`, `discover_by_uid`, `discover_all` to find bridges on the
+  network
+- `create_controller(uid, host)` to connect to a known bridge
+- `refresh_all`, `refresh_system`, `refresh_zones`, and related methods so the
+  caller controls when to poll
+
+The previous API (`discovery()`, `fetch_controller`, `Listener`, and so on)
+still works and is what Home Assistant uses today.
+
+## iPower opt-in
+
+`ENABLE_POWER` now defaults to `False`. Power monitor HTTP traffic only runs
+after you set `pizone.ENABLE_POWER = True` before creating or refreshing a
+controller. This avoids extra requests on bridges that advertise iPower but are
+not set up for it. The default may change if more field data shows power
+monitoring is reliable enough to enable by default.
+
+## Unpaired bridges
+
+Wireless ASH bridges with no AC paired report device UID `000000000`. The
+library now:
+
+- Ignores them during passive UDP discovery
+- Raises `UnpairedBridgeError` if you try to connect to that UID on purpose
+- Refuses to cache them after an IP lookup
+
+Paired bridges that temporarily report fault-shaped settings (AC off, reboot,
+and so on) are unchanged: they keep their real UID and show as disconnected
+until the AC data recovers.
+
+## Other changes
+
+- UDP `CHANGED_*` notifications are recognized and ignored (no spurious refresh)
+- Discovery verifies bridge identity over HTTP before trusting UDP replies
+- Development tooling moved to Ruff for lint and format
+
+## Home Assistant
+
+If you maintain the iZone integration or test against this library, pin
+`python-izone==1.3.5` for the connection reuse fix on the current integration
+code path. The new discovery API is included for upcoming integration work but
+is not required for a version bump alone.

python_izone-1.3.6/docs/release-notes/v1.3.6.md

@@ -0,0 +1,98 @@
+# Release notes — v1.3.6
+
+Released 2026-07-19.
+
+**Compare range:** https://github.com/Swamp-Ig/pizone/compare/v1.3.5...v1.3.6
+
+This is a **pre-release** for integrators (especially Home Assistant Phase 2
+work). It is not aimed at end users as a standalone upgrade. Prefer waiting for
+a future stable line unless you are developing against the new discovery API.
+
+## Since v1.3.5
+
+- Discovery scan wait (`SCAN_TIMEOUT`) reduced from 20s to 5s
+- `close()` waits until the UDP transport has finished tearing down before
+  returning, so a following `create_discovery()` can rebind `:7005` immediately
+  (fixes delete → HomeKit rediscovery `EADDRINUSE` races)
+- Failed `create_discovery` / `start_discovery` no longer leaves a sticky
+  process singleton that blocked retries until process restart
+- `PLACEHOLDER_DEVICE_UID` is no longer exported from the public package API
+  (`UnpairedBridgeError` remains the supported signal)
+
+Everything from v1.3.5 below still applies.
+
+## Summary (since v1.3.4)
+
+- HTTP connections are closed after each GET, which greatly reduces stalls on
+  some iZone bridges ([home-assistant/core#176536](https://github.com/home-assistant/core/issues/176536))
+- A new discovery and refresh API is available for integrators (the older API
+  still works for now)
+- iPower monitoring is off unless you opt in with `ENABLE_POWER = True`
+- Bridges that are not paired to an air conditioner (UID `000000000`) are
+  ignored or rejected instead of showing up as broken controllers
+- Faster discovery scans and reliable UDP close → recreate (this release)
+
+## Bridge connection reliability
+
+Some ASH bridges misbehave when HTTP connections are reused. This release
+line:
+
+- Sends `Connection: close` on every HTTP GET (polling and discovery probes)
+- Closes TCP connections after each request when the library creates its own
+  aiohttp session
+
+This reduces how often the bridge stops responding. It does not fix every
+hub-side stall; replacing faulty hardware may still be needed.
+
+## New discovery and refresh API (optional for now)
+
+Integrators can adopt a clearer model without background poll loops inside the
+library:
+
+- `create_discovery()` with callbacks when a controller is found or its IP
+  changes
+- `discover_by_host`, `discover_by_uid`, `discover_all` to find bridges on the
+  network
+- `create_controller(uid, host)` to connect to a known bridge
+- `refresh_all`, `refresh_system`, `refresh_zones`, and related methods so the
+  caller controls when to poll
+
+`close()` on the discovery service now waits for UDP teardown so the next
+`create_discovery()` can bind the discovery port again without racing the OS
+socket release.
+
+The previous API (`discovery()`, `fetch_controller`, `Listener`, and so on)
+still works.
+
+## iPower opt-in
+
+`ENABLE_POWER` now defaults to `False`. Power monitor HTTP traffic only runs
+after you set `pizone.ENABLE_POWER = True` before creating or refreshing a
+controller. This avoids extra requests on bridges that advertise iPower but are
+not set up for it. The default may change if more field data shows power
+monitoring is reliable enough to enable by default.
+
+## Unpaired bridges
+
+Wireless ASH bridges with no AC paired report device UID `000000000`. The
+library now:
+
+- Ignores them during passive UDP discovery
+- Raises `UnpairedBridgeError` if you try to connect to that UID on purpose
+- Refuses to cache them after an IP lookup
+
+Paired bridges that temporarily report fault-shaped settings (AC off, reboot,
+and so on) are unchanged: they keep their real UID and show as disconnected
+until the AC data recovers.
+
+## Other changes
+
+- UDP `CHANGED_*` notifications are recognized and ignored (no spurious refresh)
+- Discovery verifies bridge identity over HTTP before trusting UDP replies
+- Development tooling moved to Ruff for lint and format
+
+## Home Assistant
+
+Pin `python-izone==1.3.6` when adopting the Phase 2 discovery / coordinator
+runtime. This pre-release is intended for that integration work, not as a
+general end-user library upgrade on the legacy path alone.

{python_izone-1.3.5 → python_izone-1.3.6}/pizone/__init__.py

@@ -29,7 +29,6 @@ from types import ModuleType
 from typing import Any
 
 from . import power as power_mod
-from .const import PLACEHOLDER_DEVICE_UID
 from .controller import Controller
 from .discovery import DiscoveryService, Listener, create_discovery, discovery
 from .exceptions import ControllerCommandError, ResponseDecodeError, UnpairedBridgeError
@@ -60,7 +59,6 @@ sys.modules[__name__].__class__ = _PizoneModule
 
 __all__ = [
     "ENABLE_POWER",
-    "PLACEHOLDER_DEVICE_UID",
     "BatteryLevel",
     "Controller",
     "ControllerCommandError",

{python_izone-1.3.5 → python_izone-1.3.6}/pizone/discovery.py

@@ -50,7 +50,7 @@ DISCOVERY_RESCAN = 20.0
 RESCAN_COOLDOWN = 5.0
 
 # disposition: 1.4 — active discover_by_uid / discover_all wait
-SCAN_TIMEOUT = 20.0
+SCAN_TIMEOUT = 5.0
 
 _LOG = logging.getLogger("pizone.discovery")
 
@@ -756,8 +756,13 @@ class DiscoveryService:
             return
         _LOG.info("Close called on discovery service.")
         self._close_task = current
-        if self._transport:
+        if self._transport is not None:
+            # DatagramTransport.close() only schedules sock release via
+            # call_soon(_call_connection_lost). Wait until connection_lost
+            # clears _transport so a following create_discovery can bind :7005.
             self._transport.close()
+            while self._transport is not None:
+                await asyncio.sleep(0)
 
         pending = [task for task in list(self._tasks) if task is not current]
         for task in pending:
@@ -773,6 +778,7 @@ class DiscoveryService:
 
     def _on_connection_lost(self, exc: Exception | None) -> None:
         _LOG.debug("Connection Lost")
+        self._transport = None
         if not self._close_task:
             _LOG.error("Connection Lost unexpectedly: %s", repr(exc))
             self.create_task(self.close())
@@ -1002,5 +1008,12 @@ async def create_discovery(
         on_endpoint_discovered=on_endpoint_discovered,
     )
     _active_discovery = service
-    await service.start_discovery()
+    try:
+        await service.start_discovery()
+    except BaseException:
+        # close() clears the global when it finishes; clear again if close never ran.
+        with suppress(BaseException):
+            await service.close()
+        _clear_discovery_global(service)
+        raise
     return service

{python_izone-1.3.5 → python_izone-1.3.6}/pizone/version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.3.5'
-__version_tuple__ = version_tuple = (1, 3, 5)
+__version__ = version = '1.3.6'
+__version_tuple__ = version_tuple = (1, 3, 6)
 
 __commit_id__ = commit_id = None

{python_izone-1.3.5 → python_izone-1.3.6}/tests/test_discovery_api.py

@@ -7,21 +7,22 @@
 #               (sticky within a function until the next disposition tag).
 
 import asyncio
+import errno
 import sys
 from typing import cast
-from unittest.mock import AsyncMock, MagicMock, patch
+from unittest.mock import AsyncMock, patch
 
 from aiohttp import ClientSession
 import pytest
 
 from pizone import (
-    PLACEHOLDER_DEVICE_UID,
     Controller,
     ControllerCommandError,
     ControllerEndpoint,
     UnpairedBridgeError,
     create_discovery,
 )
+from pizone.const import PLACEHOLDER_DEVICE_UID
 from pizone.discovery import DiscoveryService
 
 from .conftest import MockController, MockDiscoveryService
@@ -66,6 +67,164 @@ async def test_create_discovery_singleton() -> None:
     assert discovery_module._active_discovery is None
 
 
+# disposition: 1.4
+@pytest.mark.asyncio
+async def test_close_then_immediate_create_discovery_rebinds() -> None:
+    """close() must release UDP :7005 before returning so a new create can bind.
+
+    Reproduces the delete→HomeKit race: stop discovery then immediately start
+    again on the same event loop without awaiting an extra sleep.
+
+    Use an injected session (as Home Assistant does) so close() does not await
+    an owned ClientSession — that await can mask the teardown race.
+    """
+    session = ClientSession()
+    try:
+        first = await create_discovery(session=session)
+        await first.close()
+        assert discovery_module._active_discovery is None
+
+        second = await create_discovery(session=session)
+        try:
+            assert second is not first
+            assert discovery_module._active_discovery is second
+        finally:
+            await second.close()
+        assert discovery_module._active_discovery is None
+    finally:
+        leftover = discovery_module._active_discovery
+        if leftover is not None:
+            await leftover.close()
+        await session.close()
+
+
+# disposition: 1.4
+@pytest.mark.asyncio
+async def test_owned_session_close_still_needs_udp_teardown_wait() -> None:
+    """Owned-session await must not be treated as sufficient UDP teardown.
+
+    CPython asyncio schedules ``DatagramTransport`` sock close via
+    ``call_soon(_call_connection_lost)``. The next ``await`` (owned
+    ``ClientSession.close``) usually runs that callback first — FIFO
+    ``call_soon`` behaviour, not a language/compiler guarantee. Defer the
+    callback so only waiting on ``connection_lost`` (Fix A) makes rebind safe.
+    """
+    loop = asyncio.get_running_loop()
+    real_call_soon = loop.call_soon
+    teardown_delay = 0.05
+
+    def call_soon(callback: object, *args: object, context: object = None) -> object:
+        if getattr(callback, "__name__", None) == "_call_connection_lost":
+            return loop.call_later(teardown_delay, callback, *args)
+        if context is not None:
+            return real_call_soon(callback, *args, context=context)
+        return real_call_soon(callback, *args)
+
+    first = await create_discovery()
+    try:
+        with patch.object(loop, "call_soon", call_soon):
+            await first.close()
+        assert discovery_module._active_discovery is None
+
+        second = await create_discovery()
+        try:
+            assert second is not first
+            assert discovery_module._active_discovery is second
+        finally:
+            await second.close()
+        assert discovery_module._active_discovery is None
+    finally:
+        await asyncio.sleep(teardown_delay + 0.01)
+        leftover = discovery_module._active_discovery
+        if leftover is not None:
+            await leftover.close()
+
+
+# disposition: 1.4
+@pytest.mark.asyncio
+async def test_create_discovery_failed_start_allows_retry() -> None:
+    """Failed start_discovery must not leave the process singleton set.
+
+    Otherwise later create_discovery calls raise RuntimeError until process
+    restart (HomeKit rediscovery / SETUP_RETRY poisoned after EADDRINUSE).
+    """
+    try:
+        with (
+            patch.object(
+                DiscoveryService,
+                "start_discovery",
+                AsyncMock(
+                    side_effect=OSError(errno.EADDRINUSE, "Address already in use")
+                ),
+            ),
+            pytest.raises(OSError, match="Address already in use"),
+        ):
+            await create_discovery()
+
+        assert discovery_module._active_discovery is None
+
+        with patch.object(DiscoveryService, "start_discovery", AsyncMock()):
+            disco = await create_discovery()
+            try:
+                assert disco is discovery_module._active_discovery
+            finally:
+                await disco.close()
+        assert discovery_module._active_discovery is None
+    finally:
+        leftover = discovery_module._active_discovery
+        if leftover is not None:
+            await leftover.close()
+
+
+# disposition: 1.4
+@pytest.mark.asyncio
+async def test_failed_start_holds_singleton_until_close_finishes() -> None:
+    """Overlapping create during failed-start cleanup must hit already-created.
+
+    ``create_discovery`` must not clear the process singleton before ``close()``
+    finishes, so a client that serializes create→close→create cannot bind
+    against a service still tearing down.
+    """
+    original_close = DiscoveryService.close
+    close_entered = asyncio.Event()
+    finish_close = asyncio.Event()
+    held_during_close: list[bool] = []
+
+    async def gated_close(self: DiscoveryService) -> None:
+        held_during_close.append(discovery_module._active_discovery is self)
+        close_entered.set()
+        await finish_close.wait()
+        await original_close(self)
+
+    try:
+        with (
+            patch.object(
+                DiscoveryService,
+                "start_discovery",
+                AsyncMock(
+                    side_effect=OSError(errno.EADDRINUSE, "Address already in use")
+                ),
+            ),
+            patch.object(DiscoveryService, "close", gated_close),
+        ):
+            create_task = asyncio.create_task(create_discovery())
+            await asyncio.wait_for(close_entered.wait(), timeout=1)
+            assert discovery_module._active_discovery is not None
+            with pytest.raises(RuntimeError, match="already created"):
+                await create_discovery()
+            finish_close.set()
+            with pytest.raises(OSError, match="Address already in use"):
+                await create_task
+
+        assert held_during_close == [True]
+        assert discovery_module._active_discovery is None
+    finally:
+        finish_close.set()
+        leftover = discovery_module._active_discovery
+        if leftover is not None:
+            await leftover.close()
+
+
 # disposition: 1.4
 @pytest.mark.asyncio
 async def test_discover_by_host() -> None:
@@ -464,7 +623,7 @@ async def test_discover_all_includes_closed_controllers() -> None:
 @pytest.mark.asyncio
 async def test_scan_sends_broadcast() -> None:
     service = MockDiscoveryService(legacy_pathway=False)
-    service._transport = MagicMock()
+    await service.start_discovery()
     with patch.object(service, "_send_broadcasts") as send_broadcasts:
         await service.scan()
     send_broadcasts.assert_called_once()

python_izone-1.3.5/docs/release-notes/v1.3.5.md

@@ -1,92 +0,0 @@
-# Release notes — v1.3.5
-
-Released 2026-07-17. **Beta release** for the upcoming Home Assistant iZone
-Phase 2 integration work (izone 1.4 program). The version number stays on the
-**1.3.x** line for now; the program name is “1.4” internally.
-
-**Compare range:** https://github.com/Swamp-Ig/pizone/compare/v1.3.4...v1.3.5
-
-## Beta status
-
-This release ships the full dual-track library on `main` so Home Assistant can
-pin a real PyPI version while Phase 2a/2b land. The **current HA integration
-still uses the legacy API** (`discovery()`, `fetch_*`, `Listener`). The new
-consumer-driven API is available for new integration code but is not required
-for a pin-only HA bump.
-
-**`1.4.0`** (planned after HA Phase 2 merges) will remove the legacy surface
-(`discovery()`, `fetch_*`, `Listener`, and related poll/scan loops).
-
-## Summary
-
-Since `v1.3.4`, this release adds the izone 1.4 discovery and refresh model
-alongside the legacy path, gates iPower behind an opt-in flag, rejects
-unpaired-bridge placeholder UIDs, and mitigates HTTP keepalive stalls on some
-ASH bridges.
-
-## Connection: close (core#176536)
-
-- HTTP **GET** requests send `Connection: close` (controller reads and
-  discovery probes)
-- When pizone owns the aiohttp session, `TCPConnector(force_close=True)` is used
-- Mitigation for hubs that stall under connection reuse; does not fix hub-side
-  stalls reported in [home-assistant/core#176536](https://github.com/home-assistant/core/issues/176536)
-
-## New 1.4 API (dual-track — beta)
-
-Available now; legacy path remains for existing consumers:
-
-- **`create_discovery()`** — one-shot discovery service with callbacks
-- **`discover_by_host`**, **`discover_by_uid`**, **`discover_all`** — ephemeral
-  or service-scoped endpoint discovery with HTTP verify
-- **`create_controller(uid, host)`** — explicit controller factory after
-  discovery
-- **`refresh_all`**, **`refresh_system`**, **`refresh_zones`**, etc. —
-  consumer-owned polling on the 1.4 path (no library debounce loops)
-- **`ControllerEndpoint`**, **`on_endpoint_discovered`**, **`on_address_changed`**
-  callbacks for integration discovery flows
-
-Legacy **`discovery()`**, **`fetch_controller`**, **`fetch_controllers`**, and
-**`Listener`** continue to work unchanged on the deprecated pathway.
-
-## Power gate
-
-- **`ENABLE_POWER`** defaults to **`False`**; no iPower HTTP I/O until set at
-  runtime (for example `pizone.ENABLE_POWER = True` before create/refresh)
-- Home Assistant does not expose power entities yet; this avoids surprise I/O on
-  bridges that advertise iPower in UDP
-
-## Unpaired bridge UID
-
-- **`PLACEHOLDER_DEVICE_UID`** (`"000000000"`) — exact match for ASH bridges
-  with no paired AC
-- Passive UDP discovery ignores this UID (no cache, no notify)
-- **`discover_by_uid`** / **`create_controller`** reject immediately with
-  **`UnpairedBridgeError`** (no network I/O)
-- **`discover_by_host`** raises after HTTP probe if the UID is the placeholder
-  (no cache)
-
-## UDP and discovery (1.4 path)
-
-- **`CHANGED_*`** push datagrams recognized and ignored (no refresh)
-- ASPort passive discovery caches unclaimed endpoints and fans out
-  **`on_endpoint_discovered`** for new or host-changed endpoints
-- **`discover_all`** HTTP-verifies collected hosts and dedupes notifications
-
-## Other
-
-- Live fault-shaped **SystemSettings** fixtures for unpaired and paired cold-restart
-  specimens (tests)
-- Test suite labelled with disposition comments (`1.4` vs `deprecate`) for
-  dual-track cleanup
-- Ruff replaces Black and pylint for lint and format
-
-## For Home Assistant integrators
-
-Pin **`python-izone==1.3.5`** for:
-
-1. **Immediate:** Connection: close mitigation on the existing legacy integration
-   path (pin-only bump)
-2. **Upcoming:** Access to the 1.4 API when Phase 2 runtime and config flow land
-
-Do not expect breaking changes on the legacy API until **`1.4.0`**.