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

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

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

@@ -0,0 +1,70 @@
+# 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 adopting the newer discovery API. It is not aimed at end users as a standalone upgrade. Prefer waiting for a future stable line unless you are developing against that 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 moving the iZone integration onto the newer discovery and coordinator path. 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.7/docs/release-notes/v1.3.7.md

@@ -0,0 +1,7 @@
+# Release notes — v1.3.7
+
+**Compare range:** https://github.com/Swamp-Ig/pizone/compare/v1.3.6...v1.3.7
+
+## Since v1.3.6
+
+- Add `ControllerAlreadyClaimedError` for duplicate controller claim/discovery attempts (replaces bare `RuntimeError` with message `already created` on controller paths; discovery-service singleton errors unchanged)

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

@@ -29,10 +29,14 @@ 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
+from .exceptions import (
+    ControllerAlreadyClaimedError,
+    ControllerCommandError,
+    ResponseDecodeError,
+    UnpairedBridgeError,
+)
 from .power import BatteryLevel, Power, PowerChannel, PowerDevice, PowerGroup
 from .types import ControllerEndpoint
 from .zone import Zone
@@ -60,9 +64,9 @@ sys.modules[__name__].__class__ = _PizoneModule
 
 __all__ = [
     "ENABLE_POWER",
-    "PLACEHOLDER_DEVICE_UID",
     "BatteryLevel",
     "Controller",
+    "ControllerAlreadyClaimedError",
     "ControllerCommandError",
     "ControllerEndpoint",
     "DiscoveryService",

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

@@ -24,7 +24,7 @@ import ifaddr
 
 from .const import PLACEHOLDER_DEVICE_UID
 from .controller import Controller
-from .exceptions import raise_if_placeholder_uid
+from .exceptions import ControllerAlreadyClaimedError, raise_if_placeholder_uid
 from .types import ControllerEndpoint
 from .zone import Zone
 
@@ -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")
 
@@ -405,7 +405,9 @@ class DiscoveryService:
     def _ensure_endpoint_available(self, endpoint: ControllerEndpoint) -> None:
         """Raise if *endpoint* is already claimed."""
         if endpoint.uid in self._claimed_endpoints:
-            raise RuntimeError(f"Controller {endpoint.uid} already created")
+            raise ControllerAlreadyClaimedError(
+                f"Controller {endpoint.uid} already created"
+            )
 
     # disposition: 1.4
     def _claim_endpoint(self, endpoint: ControllerEndpoint) -> None:
@@ -451,7 +453,9 @@ class DiscoveryService:
         """
         claimed = self._endpoint_by_host(self._claimed_endpoints, host)
         if claimed is not None:
-            raise RuntimeError(f"Controller {claimed.uid} already created")
+            raise ControllerAlreadyClaimedError(
+                f"Controller {claimed.uid} already created"
+            )
         known = self._endpoint_by_host(self._known_endpoints, host)
         if known is not None:
             return known
@@ -476,7 +480,7 @@ class DiscoveryService:
         """
         raise_if_placeholder_uid(uid)
         if uid in self._claimed_endpoints:
-            raise RuntimeError(f"Controller {uid} already created")
+            raise ControllerAlreadyClaimedError(f"Controller {uid} already created")
         endpoint = self._known_endpoints.get(uid)
         if endpoint is not None:
             return endpoint
@@ -569,7 +573,7 @@ class DiscoveryService:
 
         Raises:
             UnpairedBridgeError: If *uid* is the unpaired placeholder (no I/O).
-            RuntimeError: If a controller with *uid* already exists.
+            ControllerAlreadyClaimedError: If a controller with *uid* already exists.
             ConnectionError: If the controller cannot be reached after
                 address fallback.
             ControllerCommandError: If the device rejects the protocol request.
@@ -579,7 +583,7 @@ class DiscoveryService:
         """
         raise_if_placeholder_uid(uid)
         if uid in self._claimed_endpoints:
-            raise RuntimeError(f"Controller {uid} already created")
+            raise ControllerAlreadyClaimedError(f"Controller {uid} already created")
         pending_address_changed: ControllerEndpoint | None = None
 
         try:
@@ -756,8 +760,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 +782,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 +1012,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.7}/pizone/exceptions.py

@@ -28,6 +28,14 @@ class UnpairedBridgeError(ValueError):
     """
 
 
+class ControllerAlreadyClaimedError(Exception):
+    """A controller UID or host is already claimed on this discovery service.
+
+    Raised when ``discover_by_host``, ``discover_by_uid``, or ``create_controller``
+    would duplicate an active controller registration.
+    """
+
+
 def raise_if_placeholder_uid(uid: str) -> None:
     """Raise :exc:`UnpairedBridgeError` if *uid* is the unpaired placeholder."""
     if uid == PLACEHOLDER_DEVICE_UID:

{python_izone-1.3.5 → python_izone-1.3.7}/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.7'
+__version_tuple__ = version_tuple = (1, 3, 7)
 
 __commit_id__ = commit_id = None

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

@@ -7,21 +7,23 @@
 #               (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,
+    ControllerAlreadyClaimedError,
     ControllerCommandError,
     ControllerEndpoint,
     UnpairedBridgeError,
     create_discovery,
 )
+from pizone.const import PLACEHOLDER_DEVICE_UID
 from pizone.discovery import DiscoveryService
 
 from .conftest import MockController, MockDiscoveryService
@@ -66,6 +68,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:
@@ -123,7 +283,7 @@ async def test_discover_by_host_raises_if_controller_exists() -> None:
         ClientSession,
         FakeHttpSession(get_error=OSError("should not probe")),
     )
-    with pytest.raises(RuntimeError, match="already created"):
+    with pytest.raises(ControllerAlreadyClaimedError, match="already created"):
         await service.discover_by_host("10.0.0.90")
     await service.close()
 
@@ -165,7 +325,7 @@ async def test_discover_by_uid_raises_if_controller_exists() -> None:
     scan = AsyncMock()
     with (
         patch.object(service, "scan", scan),
-        pytest.raises(RuntimeError, match="already created"),
+        pytest.raises(ControllerAlreadyClaimedError, match="already created"),
     ):
         await service.discover_by_uid("000025841")
     scan.assert_not_awaited()
@@ -464,7 +624,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()
@@ -497,7 +657,7 @@ async def test_create_controller_raises_if_uid_exists() -> None:
         FakeHttpSession(get_response=_system_settings_response("000025841")),
     )
     await service.create_controller("000025841", "10.0.0.90")
-    with pytest.raises(RuntimeError, match="already created"):
+    with pytest.raises(ControllerAlreadyClaimedError, match="already created"):
         await service.create_controller("000025841", "10.0.0.90")
     await service.close()
 

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`**.