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

{python_izone-1.3.3 → python_izone-1.3.5}/.github/workflows/main.yml

@@ -23,8 +23,10 @@ jobs:
           cache-suffix: build
       - name: Install dependencies
         run: uv sync --frozen --all-extras --group dev
-      - name: Lint with Pylint
-        run: uv run pylint pizone
+      - name: Lint with Ruff
+        run: |
+          uv run ruff check pizone tests
+          uv run ruff format --check pizone tests
       - name: Type check with mypy
         run: uv run mypy pizone
       - name: Test with pytest

python_izone-1.3.5/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.21
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

python_izone-1.3.5/.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "charliermarsh.ruff",
+    "ms-python.python",
+    "ms-python.mypy-type-checker"
+  ]
+}

python_izone-1.3.5/.vscode/settings.json

@@ -0,0 +1,34 @@
+{
+    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+    "python.testing.pytestEnabled": true,
+    "python.globalModuleInstallation": false,
+    "[python]": {
+        "editor.defaultFormatter": "charliermarsh.ruff",
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+            "source.fixAll.ruff": "explicit",
+            "source.organizeImports.ruff": "explicit"
+        }
+    },
+    "ruff.enable": true,
+    "ruff.nativeServer": "on",
+    "ruff.configurationPreference": "filesystemFirst",
+    "ruff.interpreter": ["${workspaceFolder}/.venv/bin/python"],
+    "python.analysis.typeCheckingMode": "off",
+    "cursorpyright.analysis.typeCheckingMode": "off",
+    "pylint.enabled": false,
+    "mypy-type-checker.interpreter": ["${workspaceFolder}/.venv/bin/python"],
+    "mypy-type-checker.args": ["--config-file=${workspaceFolder}/pyproject.toml"],
+    "cSpell.words": [
+        "inetaddrs",
+        "inetaddr",
+        "ifaddresses",
+        "rescan",
+        "pizone",
+        "ipower",
+        "COOLDOWN",
+        "coro",
+        "datagram",
+        "fanout"
+    ]
+}

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-izone
-Version: 1.3.3
+Version: 1.3.5
 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>
@@ -68,7 +68,8 @@ The iZone Ethernet interface is documented in
 Individual commands:
 
 - `uv run pytest tests/`
-- `uv run pylint pizone`
+- `uv run ruff check pizone tests`
+- `uv run ruff format pizone tests`
 - `uv run mypy pizone`
 - `uv build`
 

{python_izone-1.3.3 → python_izone-1.3.5}/README.md

@@ -42,7 +42,8 @@ The iZone Ethernet interface is documented in
 Individual commands:
 
 - `uv run pytest tests/`
-- `uv run pylint pizone`
+- `uv run ruff check pizone tests`
+- `uv run ruff format pizone tests`
 - `uv run mypy pizone`
 - `uv build`
 

python_izone-1.3.5/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.5/docs/release-notes/v1.3.5.md

@@ -0,0 +1,92 @@
+# 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`**.

python_izone-1.3.5/pizone/__init__.py

@@ -0,0 +1,79 @@
+"""Interface to the iZone air conditioner controller.
+
+Prefer :func:`~pizone.discovery.create_discovery` or
+:func:`~pizone.discovery.discovery` to obtain a discovery service, then create
+or discover :class:`~pizone.controller.Controller` instances through that
+service. Zones and power monitors are owned by their controller.
+
+Synchronous property reads return cached device data and do not raise
+:exc:`ConnectionError`. Async command and refresh methods perform HTTP I/O and
+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)
+
+Power support is off by default. Enable at runtime before create/refresh when
+the consumer needs iPower (for example future Home Assistant power entities)::
+
+    import pizone
+    pizone.ENABLE_POWER = True
+"""
+
+import sys
+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 .power import BatteryLevel, Power, PowerChannel, PowerDevice, PowerGroup
+from .types import ControllerEndpoint
+from .zone import Zone
+
+
+def __getattr__(name: str) -> Any:
+    if name == "ENABLE_POWER":
+        return power_mod.ENABLE_POWER
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+class _PizoneModule(ModuleType):
+    """Allow ``pizone.ENABLE_POWER = True`` to update :mod:`pizone.power`."""
+
+    @property
+    def ENABLE_POWER(self) -> bool:
+        return power_mod.ENABLE_POWER
+
+    @ENABLE_POWER.setter
+    def ENABLE_POWER(self, value: bool) -> None:
+        power_mod.ENABLE_POWER = bool(value)
+
+
+sys.modules[__name__].__class__ = _PizoneModule
+
+__all__ = [
+    "ENABLE_POWER",
+    "PLACEHOLDER_DEVICE_UID",
+    "BatteryLevel",
+    "Controller",
+    "ControllerCommandError",
+    "ControllerEndpoint",
+    "DiscoveryService",
+    "Listener",
+    "Power",
+    "PowerChannel",
+    "PowerDevice",
+    "PowerGroup",
+    "ResponseDecodeError",
+    "UnpairedBridgeError",
+    "Zone",
+    "create_discovery",
+    "discovery",
+]

python_izone-1.3.5/pizone/const.py

@@ -0,0 +1,4 @@
+"""Shared constants for pizone."""
+
+# Exact AirStreamDeviceUId when an ASH bridge has no paired AC (desk evidence).
+PLACEHOLDER_DEVICE_UID = "000000000"