zencontrol-python 0.1.2__tar.gz → 0.1.4__tar.gz

{zencontrol_python-0.1.2 → zencontrol_python-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zencontrol-python
-Version: 0.1.2
+Version: 0.1.4
 Summary: Python implementation of the Zencontrol TPI Advanced protocol for DALI lighting controllers.
 Author: Simon Wright
 License-Expression: MIT
@@ -12,13 +12,11 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Home Automation
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
-Requires-Python: >=3.11
+Requires-Python: >=3.14
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: colorama>=0.4.6
@@ -46,9 +44,33 @@ This library has now undergone validation in multiple environments. There is an
 [zencontrol-simulator](https://github.com/sjwright/zencontrol-simulator), a nearly feature-complete simulator of zencontrol hardware.
 A practical demonstration is [zencontrol-homeassistant](https://github.com/sjwright/zencontrol-homeassistant), a comprehensive Home Assistant integration.
 
+## Features
+
+Beyond basic lighting control, this library supports:
+
+* **Broad command surface** — inhibit, custom fade, step/up/down helpers, colour scene membership queries, EAN/serial, and most related TPI Advanced commands
+* **Object-based entity model** — Optional. Expresses lights, groups, profiles, buttons, motion sensors, and system variables as rich objects with interview/discovery helpers
+* **UDP transport resilience** — request retries and queue-failure backoff
+* **Multicast controller discovery** — find controllers on the LAN without a preconfigured host
+* **Button events** — discovery of control-device button instances, plus press and long-press event callbacks
+* **Event filtering** — configure which TPI events the controller emits
+* **System variables** — labelled SV discovery, read/write, and change events
+* **Profiles** — query, change, and return to the scheduled profile
+* **Simulator-backed tests** — protocol path exercised against [zencontrol-simulator](https://github.com/sjwright/zencontrol-simulator)
+
+## Known limitations
+
+* RGB+ and XY colour commands have not been tested with hardware
+* Numerical (absolute) instances have not been tested with hardware
+
+## Out of scope
+
+* Any commands involving DMX, Control4, or virtual instances (I don't have licenses for any of these so I couldn't test them even if I wanted to, but the scaffolding is there if anyone wishes to add support)
+* Any commands described in the documentation as "legacy" (they aren't useful)
+
 ## Requirements
 
-* Python 3.11 (or later)
+* Python 3.14 (or later)
 * Controller firmware 2.2.130 or later is strongly recommended (minimum 2.2.11 required)
 
 ## Install
@@ -70,16 +92,6 @@ pytest -m "not simulator"
 pytest
 ```
 
-## Limitations
-
-* RGB+ and XY colour commands are not tested (I don't have any compatible lights)
-* Numerical (absolute) instances are not tested (I don't have any such ECDs)
-
-## Out of scope
-
-* Any commands involving DMX, Control4, or virtual instances (I don't have licenses for any of these so I couldn't test them even if I wanted to, but the scaffolding is there if anyone wishes to add support)
-* Any commands described in the documentation as "legacy" (they aren't useful)
-
 ## TPI Advanced wishlist
 
 * Command to return a controller's MAC address used for multicast packets _(There are other ways to get or infer the MAC access, but they're unreliable.)_

{zencontrol_python-0.1.2 → zencontrol_python-0.1.4}/README.md

@@ -10,9 +10,33 @@ This library has now undergone validation in multiple environments. There is an
 [zencontrol-simulator](https://github.com/sjwright/zencontrol-simulator), a nearly feature-complete simulator of zencontrol hardware.
 A practical demonstration is [zencontrol-homeassistant](https://github.com/sjwright/zencontrol-homeassistant), a comprehensive Home Assistant integration.
 
+## Features
+
+Beyond basic lighting control, this library supports:
+
+* **Broad command surface** — inhibit, custom fade, step/up/down helpers, colour scene membership queries, EAN/serial, and most related TPI Advanced commands
+* **Object-based entity model** — Optional. Expresses lights, groups, profiles, buttons, motion sensors, and system variables as rich objects with interview/discovery helpers
+* **UDP transport resilience** — request retries and queue-failure backoff
+* **Multicast controller discovery** — find controllers on the LAN without a preconfigured host
+* **Button events** — discovery of control-device button instances, plus press and long-press event callbacks
+* **Event filtering** — configure which TPI events the controller emits
+* **System variables** — labelled SV discovery, read/write, and change events
+* **Profiles** — query, change, and return to the scheduled profile
+* **Simulator-backed tests** — protocol path exercised against [zencontrol-simulator](https://github.com/sjwright/zencontrol-simulator)
+
+## Known limitations
+
+* RGB+ and XY colour commands have not been tested with hardware
+* Numerical (absolute) instances have not been tested with hardware
+
+## Out of scope
+
+* Any commands involving DMX, Control4, or virtual instances (I don't have licenses for any of these so I couldn't test them even if I wanted to, but the scaffolding is there if anyone wishes to add support)
+* Any commands described in the documentation as "legacy" (they aren't useful)
+
 ## Requirements
 
-* Python 3.11 (or later)
+* Python 3.14 (or later)
 * Controller firmware 2.2.130 or later is strongly recommended (minimum 2.2.11 required)
 
 ## Install
@@ -34,16 +58,6 @@ pytest -m "not simulator"
 pytest
 ```
 
-## Limitations
-
-* RGB+ and XY colour commands are not tested (I don't have any compatible lights)
-* Numerical (absolute) instances are not tested (I don't have any such ECDs)
-
-## Out of scope
-
-* Any commands involving DMX, Control4, or virtual instances (I don't have licenses for any of these so I couldn't test them even if I wanted to, but the scaffolding is there if anyone wishes to add support)
-* Any commands described in the documentation as "legacy" (they aren't useful)
-
 ## TPI Advanced wishlist
 
 * Command to return a controller's MAC address used for multicast packets _(There are other ways to get or infer the MAC access, but they're unreliable.)_

{zencontrol_python-0.1.2 → zencontrol_python-0.1.4}/examples/dump_simulator_config.py

@@ -11,14 +11,12 @@ Example:
       -o ../zencontrol-simulator/config.from-live.yaml
 """
 
-from __future__ import annotations
-
 import argparse
 import asyncio
 import logging
 import sys
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 import yaml
 
@@ -42,12 +40,10 @@ INSTANCE_TYPE_NAMES = {
     ZenInstanceType.GENERAL_SENSOR: "general_sensor",
 }
 
-
 def _hex_int(value: int) -> str:
     return f"0x{value:X}"
 
-
-def _colour_dict(colour: Optional[ZenColour]) -> Optional[dict[str, Any]]:
+def _colour_dict(colour: ZenColour | None) -> dict[str, Any] | None:
     if colour is None or colour.type is None:
         return None
     if colour.type == ZenColourType.TC:
@@ -66,32 +62,28 @@ def _colour_dict(colour: Optional[ZenColour]) -> Optional[dict[str, Any]]:
         return {"type": "xy", "x": colour.x, "y": colour.y}
     return None
 
-
-def _scene_levels(levels: list[Optional[int]] | None) -> list[Optional[int]]:
-    out: list[Optional[int]] = [None] * 12
+def _scene_levels(levels: list[int | None] | None) -> list[int | None]:
+    out: list[int | None] = [None] * 12
     if not levels:
         return out
     for i, level in enumerate(levels[:12]):
         out[i] = None if level is None else int(level)
     return out
 
-
-def _scene_colours(colours: list[Optional[ZenColour]] | None) -> list[Optional[dict[str, Any]]]:
-    out: list[Optional[dict[str, Any]]] = [None] * 12
+def _scene_colours(colours: list[ZenColour | None] | None) -> list[dict[str, Any] | None]:
+    out: list[dict[str, Any] | None] = [None] * 12
     if not colours:
         return out
     for i, colour in enumerate(colours[:12]):
         out[i] = _colour_dict(colour)
     return out
 
-
-async def _raw_byte(tpi: ZenProtocol, controller: ZenController, command: int, address: int = 0) -> Optional[int]:
+async def _raw_byte(tpi: ZenProtocol, controller: ZenController, command: int, address: int = 0) -> int | None:
     response = await tpi._send_basic(controller, command, address)
     if response and len(response) >= 1:
         return int(response[0])
     return None
 
-
 async def dump_controller(tpi: ZenProtocol, controller: ZenController) -> dict[str, Any]:
     LOGGER.info("Querying controller %s (%s:%s)", controller.mac, controller.host, controller.port)
 
@@ -343,15 +335,12 @@ async def dump_controller(tpi: ZenProtocol, controller: ZenController) -> dict[s
 
     return world
 
-
 class _HexInt(int):
     """YAML representable int that dumps as 0x…."""
 
-
 def _represent_hex_int(dumper: yaml.Dumper, data: _HexInt) -> Any:
     return dumper.represent_scalar("tag:yaml.org,2002:int", f"0x{int(data):X}")
 
-
 def _prepare_for_yaml(obj: Any) -> Any:
     """Convert serial hex strings back to ints tagged for hex dump where useful."""
     if isinstance(obj, dict):
@@ -370,7 +359,6 @@ def _prepare_for_yaml(obj: Any) -> Any:
         return [_prepare_for_yaml(x) for x in obj]
     return obj
 
-
 def write_yaml(path: Path, world: dict[str, Any]) -> None:
     class Dumper(yaml.SafeDumper):
         pass
@@ -395,7 +383,6 @@ def write_yaml(path: Path, world: dict[str, Any]) -> None:
             width=100,
         )
 
-
 def build_parser() -> argparse.ArgumentParser:
     example_dir = Path(__file__).resolve().parent
     default_config = example_dir / "config.yaml"
@@ -431,7 +418,6 @@ def build_parser() -> argparse.ArgumentParser:
     )
     return parser
 
-
 async def main(argv: list[str] | None = None) -> None:
     args = build_parser().parse_args(argv)
     logging.basicConfig(
@@ -484,6 +470,5 @@ async def main(argv: list[str] | None = None) -> None:
         len(world["system_variables"]),
     )
 
-
 if __name__ == "__main__":
     run_with_keyboard_interrupt(main)

{zencontrol_python-0.1.2 → zencontrol_python-0.1.4}/examples/live/interface_events.py

@@ -3,7 +3,6 @@ from zencontrol import ZenControl, ZenProfile, ZenGroup, ZenLight, ZenButton, Ze
 import yaml
 from pathlib import Path
 import time
-from typing import Optional
 
 async def main():
     config = yaml.safe_load(open(Path(__file__).resolve().parents[2] / "tests" / "config.yaml"))
@@ -21,11 +20,11 @@ async def main():
         ms()
         print(f"Profile Change Event     - {profile}")
 
-    async def _zen_group_change(group: ZenGroup, level: Optional[int] = None, colour: Optional[ZenColour] = None, scene: Optional[int] = None, discoordinated: bool = False) -> None:
+    async def _zen_group_change(group: ZenGroup, level: int | None = None, colour: ZenColour | None = None, scene: int | None = None, discoordinated: bool = False) -> None:
         ms()
         print(f"Group Change Event       - {group} level {level} colour {colour} scene {scene} {'discoordinated' if discoordinated else ''}")
 
-    async def _zen_light_change(light: ZenLight, level: Optional[int] = None, colour: Optional[ZenColour] = None, scene: Optional[int] = None) -> None:
+    async def _zen_light_change(light: ZenLight, level: int | None = None, colour: ZenColour | None = None, scene: int | None = None) -> None:
         ms()
         print(f"Light Change Event       - {light} level {level} colour {colour} scene {scene}")
 

{zencontrol_python-0.1.2 → zencontrol_python-0.1.4}/examples/mqtt_bridge.py

@@ -5,7 +5,7 @@ import json
 import yaml
 import re
 from pathlib import Path
-from typing import Optional, Any
+from typing import Any
 import zencontrol
 from zencontrol import ZenController, ZenProtocol, ZenClient, ZenColour, ZenColourType, ZenProfile, ZenLight, ZenGroup, ZenButton, ZenMotionSensor, ZenSystemVariable, ZenTimeoutError, ZenAddressType
 from zencontrol.api.types import Const as ApiConst
@@ -814,9 +814,9 @@ class ZenMQTTBridge:
     async def _mqtt_light_change(self, light: ZenLight|ZenGroup, payload: dict[str, Any]) -> None:
         addr = light.address
         ctrl = addr.controller
-        state: Optional[str] = payload.get("state", None)
-        brightness: Optional[int] = payload.get("brightness", None)
-        mireds: Optional[int] = payload.get("color_temp", None)
+        state: str | None = payload.get("state", None)
+        brightness: int | None = payload.get("brightness", None)
+        mireds: int | None = payload.get("color_temp", None)
 
         # If brightness or temperature is set
         if brightness is not None or mireds is not None:
@@ -835,7 +835,7 @@ class ZenMQTTBridge:
             self.logger.info(f"♥️💡 Command from HA: {ctrl.name} turning gear {addr.number} ON")
             await light.on()
 
-    async def _zen_light_change(self, light: ZenLight, level: Optional[int] = None, colour: Optional[ZenColour] = None, scene: Optional[int] = None) -> None:
+    async def _zen_light_change(self, light: ZenLight, level: int | None = None, colour: ZenColour | None = None, scene: int | None = None) -> None:
         typestr = "group" if light.address.type == ZenAddressType.GROUP else "light"
         emoji = "👥" if light.address.type == ZenAddressType.GROUP else "💡"
         self.logger.info(f"🩵{emoji} Event from Zen: {typestr} {light.address.number}  level {level if level is not None else '--'}  colour {colour if colour is not None else '--'}  scene {scene if scene is not None else '--'}")
@@ -930,7 +930,7 @@ class ZenMQTTBridge:
     
     # mqtt group light change calls _mqtt_light_change
         
-    async def _zen_group_change(self, group: ZenGroup, level: Optional[int] = None, colour: Optional[ZenColour] = None, scene: Optional[int] = None, discoordinated: Optional[bool] = None) -> None:
+    async def _zen_group_change(self, group: ZenGroup, level: int | None = None, colour: ZenColour | None = None, scene: int | None = None, discoordinated: bool | None = None) -> None:
         select_mqtt_topic = group.client_data.get("select", {}).get('mqtt_topic', None)
 
         # Get the scene label for the ID from the group
@@ -1109,4 +1109,4 @@ async def main():
         await bridge.stop()
 
 if __name__ == "__main__":
-    asyncio.run(main())
+    asyncio.run(main())

{zencontrol_python-0.1.2 → zencontrol_python-0.1.4}/pyproject.toml

@@ -7,7 +7,7 @@ name = "zencontrol-python"
 dynamic = ["version"]
 description = "Python implementation of the Zencontrol TPI Advanced protocol for DALI lighting controllers."
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.14"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [
@@ -19,9 +19,7 @@ classifiers = [
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Home Automation",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Typing :: Typed",
@@ -67,7 +65,7 @@ zencontrol = ["py.typed"]
 
 [tool.black]
 line-length = 88
-target-version = ['py311']
+target-version = ['py314']
 include = '\.pyi?$'
 extend-exclude = '''
 /(
@@ -84,7 +82,7 @@ extend-exclude = '''
 '''
 
 [tool.mypy]
-python_version = "3.11"
+python_version = "3.14"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true
@@ -108,3 +106,10 @@ asyncio_mode = "auto"
 markers = [
     "simulator: integration tests that start zencontrol-simulator (installed or sibling ../zencontrol-simulator checkout)",
 ]
+
+[tool.ruff]
+target-version = "py314"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["ASYNC", "B", "E", "F", "I", "UP"]

{zencontrol_python-0.1.2 → zencontrol_python-0.1.4}/tests/test_lifecycle.py

@@ -11,7 +11,6 @@ from zencontrol.api.models import ZenAddress
 from zencontrol.api.types import ZenAddressType
 from zencontrol.interface.interface import (
     ZenControl,
-    ZenController,
     ZenLight,
 )
 
@@ -24,6 +23,34 @@ async def test_zencontrol_async_context_manager_calls_aclose() -> None:
         aclose.assert_awaited_once()
 
 
+@pytest.mark.asyncio
+async def test_remove_controller_closes_client_and_purges_cache() -> None:
+    zen = ZenControl()
+    ctrl_a = zen.add_controller(
+        id=1, name="ctrl-a", label="A", host="127.0.0.1", port=5108
+    )
+    ctrl_b = zen.add_controller(
+        id=2, name="ctrl-b", label="B", host="127.0.0.2", port=5108
+    )
+    fake_client = MagicMock()
+    fake_client.close = AsyncMock()
+    ctrl_a.client = fake_client
+    address = ZenAddress(controller=ctrl_a, type=ZenAddressType.ECG, number=1)
+    ZenLight(protocol=zen.protocol, address=address)
+    assert "ctrl-a 1" in zen.protocol.entity_registry.lights
+
+    await zen.remove_controller(ctrl_a)
+
+    fake_client.close.assert_awaited()
+    assert ctrl_a.client is None
+    assert zen.controllers == [ctrl_b]
+    assert "ctrl-a" not in zen.protocol.entity_registry.controllers
+    assert "ctrl-a 1" not in zen.protocol.entity_registry.lights
+    assert "ctrl-b" in zen.protocol.entity_registry.controllers
+
+    await zen.aclose()
+
+
 @pytest.mark.asyncio
 async def test_aclose_closes_clients_and_clears_instances() -> None:
     zen = ZenControl()

{zencontrol_python-0.1.2 → zencontrol_python-0.1.4}/zencontrol/__init__.py

@@ -58,7 +58,7 @@ from .exceptions import ZenError, ZenTimeoutError, ZenResponseError, ZenConnecti
 # Utilities
 from .utils import run_with_keyboard_interrupt
 
-__version__ = "0.1.2"
+__version__ = "0.1.4"
 __author__ = "Simon Wright"
 
 # Public API - these are the main classes users should import