zencontrol-python 0.1.1__tar.gz → 0.1.3__tar.gz

{zencontrol_python-0.1.1 → zencontrol_python-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zencontrol-python
-Version: 0.1.1
+Version: 0.1.3
 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
@@ -40,33 +38,46 @@ This is an implementation of the **Zencontrol TPI Advanced** protocol, written i
 
 - zencontrol.io: Implementation of the raw TPI Advanced UDP packet specification;
 - zencontrol.api: Implementation of most TPI Advanced API commands and events;
-- zencontrol.interface: An opinionated abstraction layer suitable for integration into smart building control software. It provides methods, objects, and callbacks for managing lights, groups, profiles, buttons, motion sensors, and system variables. This code is still undergoing significant refinement.
+- zencontrol.interface: An opinionated abstraction layer suitable for integration into smart building control software. It provides methods, objects, and callbacks for managing lights, groups, profiles, buttons, motion sensors, and system variables.
 
-Built on top of this is an example MQTT bridge for Home Assistant. See [examples/mqtt_bridge.md](examples/mqtt_bridge.md).
+This library has now undergone validation in multiple environments. There is an extensive test suite, some of which uses
+[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.
 
 ## Requirements
 
-* Python 3.11 (or later)
-* Controller firmware 2.2.11 (or later)
+* Python 3.14 (or later)
+* Controller firmware 2.2.130 or later is strongly recommended (minimum 2.2.11 required)
 
 ## Install
 
-Refer to zencontrol-tpi project for now.
-For integrators, the library is also published on PyPI.
+This library is available on PyPI.
+
+## Testing
+
+Integration tests start [zencontrol-simulator](https://github.com/sjwright/zencontrol-simulator) on an ephemeral local port and exercise a real UDP TPI protocol path. Either install the simulator, or check it out as a sibling directory (`../zencontrol-simulator`); tests will pick it up automatically. Note that PyYAML is a simulator dependency.
+
+```bash
+pip install -e ".[dev]"
+pip install PyYAML
+# optional if not using a sibling checkout:
+# pip install -e ../zencontrol-simulator
+pytest -m simulator
+pytest -m "not simulator"
+# or run everything:
+pytest
+```
 
 ## Limitations
 
-Implemented but untested:
-  
-* Dealing with multiple controllers (I only have one controller)
-* RGB+ and XY colour commands (I don't have any compatible lights)
-* Numerical (absolute) instances (I don't have any such ECDs)
-* Event filtering (I haven't tested it)
+* 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)
 
-Not implemented:
+## 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.1 → zencontrol_python-0.1.3}/README.md

@@ -4,33 +4,46 @@ This is an implementation of the **Zencontrol TPI Advanced** protocol, written i
 
 - zencontrol.io: Implementation of the raw TPI Advanced UDP packet specification;
 - zencontrol.api: Implementation of most TPI Advanced API commands and events;
-- zencontrol.interface: An opinionated abstraction layer suitable for integration into smart building control software. It provides methods, objects, and callbacks for managing lights, groups, profiles, buttons, motion sensors, and system variables. This code is still undergoing significant refinement.
+- zencontrol.interface: An opinionated abstraction layer suitable for integration into smart building control software. It provides methods, objects, and callbacks for managing lights, groups, profiles, buttons, motion sensors, and system variables.
 
-Built on top of this is an example MQTT bridge for Home Assistant. See [examples/mqtt_bridge.md](examples/mqtt_bridge.md).
+This library has now undergone validation in multiple environments. There is an extensive test suite, some of which uses
+[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.
 
 ## Requirements
 
-* Python 3.11 (or later)
-* Controller firmware 2.2.11 (or later)
+* Python 3.14 (or later)
+* Controller firmware 2.2.130 or later is strongly recommended (minimum 2.2.11 required)
 
 ## Install
 
-Refer to zencontrol-tpi project for now.
-For integrators, the library is also published on PyPI.
+This library is available on PyPI.
+
+## Testing
+
+Integration tests start [zencontrol-simulator](https://github.com/sjwright/zencontrol-simulator) on an ephemeral local port and exercise a real UDP TPI protocol path. Either install the simulator, or check it out as a sibling directory (`../zencontrol-simulator`); tests will pick it up automatically. Note that PyYAML is a simulator dependency.
+
+```bash
+pip install -e ".[dev]"
+pip install PyYAML
+# optional if not using a sibling checkout:
+# pip install -e ../zencontrol-simulator
+pytest -m simulator
+pytest -m "not simulator"
+# or run everything:
+pytest
+```
 
 ## Limitations
 
-Implemented but untested:
-  
-* Dealing with multiple controllers (I only have one controller)
-* RGB+ and XY colour commands (I don't have any compatible lights)
-* Numerical (absolute) instances (I don't have any such ECDs)
-* Event filtering (I haven't tested it)
+* 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)
 
-Not implemented:
+## 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.1/tests/test_controller.py → zencontrol_python-0.1.3/examples/live/controller.py

@@ -1,11 +1,12 @@
 import asyncio
 import yaml
+from pathlib import Path
 from zencontrol import ZenProtocol, ZenController, run_with_keyboard_interrupt
 
 async def main():
     """Test the async ZenProtocol with controller queries"""
     # Load configuration
-    config = yaml.safe_load(open("tests/config.yaml"))
+    config = yaml.safe_load(open(Path(__file__).resolve().parents[2] / "tests" / "config.yaml"))
     
     # Create protocol and controller
     async with ZenProtocol(print_traffic=True) as tpi:

zencontrol_python-0.1.1/tests/test_devices.py → zencontrol_python-0.1.3/examples/live/devices.py

@@ -1,11 +1,12 @@
 import asyncio
 import yaml
+from pathlib import Path
 from zencontrol import ZenProtocol, ZenController, run_with_keyboard_interrupt
 
 async def main():
     """Test DALI device queries"""
     # Load configuration
-    config = yaml.safe_load(open("tests/config.yaml"))
+    config = yaml.safe_load(open(Path(__file__).resolve().parents[2] / "tests" / "config.yaml"))
     
     # Create protocol and controller
     async with ZenProtocol(print_traffic=False) as tpi:

zencontrol_python-0.1.1/tests/test_events.py → zencontrol_python-0.1.3/examples/live/events.py

@@ -13,7 +13,7 @@ sys.stdout.reconfigure(line_buffering=True)
 
 from zencontrol import ZenProtocol, ZenController, ZenAddress, ZenInstance, run_with_keyboard_interrupt
 
-CONFIG_PATH = Path(__file__).parent / "config.yaml"
+CONFIG_PATH = Path(__file__).resolve().parents[2] / "tests" / "config.yaml"
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(levelname)s %(message)s")
 logger = logging.getLogger("test_events")

zencontrol_python-0.1.1/tests/test_gear.py → zencontrol_python-0.1.3/examples/live/gear.py

@@ -1,11 +1,12 @@
 import asyncio
 import yaml
+from pathlib import Path
 from zencontrol import ZenProtocol, ZenController, run_with_keyboard_interrupt
 
 async def main():
     """Test control gear queries"""
     # Load configuration
-    config = yaml.safe_load(open("tests/config.yaml"))
+    config = yaml.safe_load(open(Path(__file__).resolve().parents[2] / "tests" / "config.yaml"))
     
     # Create protocol and controller
     async with ZenProtocol(print_traffic=False) as tpi:

zencontrol_python-0.1.1/tests/test_groups.py → zencontrol_python-0.1.3/examples/live/groups.py

@@ -1,11 +1,12 @@
 import asyncio
 import yaml
+from pathlib import Path
 from zencontrol import ZenProtocol, ZenController, run_with_keyboard_interrupt
 
 async def main():
     """Test group queries"""
     # Load configuration
-    config = yaml.safe_load(open("tests/config.yaml"))
+    config = yaml.safe_load(open(Path(__file__).resolve().parents[2] / "tests" / "config.yaml"))
     
     # Create protocol and controller
     async with ZenProtocol(print_traffic=True) as tpi:

zencontrol_python-0.1.1/tests/test_instances.py → zencontrol_python-0.1.3/examples/live/instances.py

@@ -1,11 +1,12 @@
 import asyncio
 import yaml
+from pathlib import Path
 from zencontrol import ZenProtocol, ZenController, run_with_keyboard_interrupt
 
 async def main():
     """Test instance queries"""
     # Load configuration
-    config = yaml.safe_load(open("tests/config.yaml"))
+    config = yaml.safe_load(open(Path(__file__).resolve().parents[2] / "tests" / "config.yaml"))
     
     # Create protocol and controller
     async with ZenProtocol(print_traffic=False) as tpi:

zencontrol_python-0.1.1/tests/test_interface.py → zencontrol_python-0.1.3/examples/live/interface.py

@@ -1,10 +1,11 @@
 import asyncio
 from zencontrol import ZenControl, run_with_keyboard_interrupt
 import yaml
+from pathlib import Path
 import time
 
 async def main():
-    config = yaml.safe_load(open("tests/config.yaml"))
+    config = yaml.safe_load(open(Path(__file__).resolve().parents[2] / "tests" / "config.yaml"))
     zi = ZenControl(print_traffic=False)
     zi.add_controller(**config.get('zencontrol')[0])
     await zi.start()

zencontrol_python-0.1.1/tests/test_interface_events.py → zencontrol_python-0.1.3/examples/live/interface_events.py

@@ -1,11 +1,11 @@
 import asyncio
 from zencontrol import ZenControl, ZenProfile, ZenGroup, ZenLight, ZenButton, ZenMotionSensor, ZenSystemVariable, ZenColour, run_with_keyboard_interrupt
 import yaml
+from pathlib import Path
 import time
-from typing import Optional
 
 async def main():
-    config = yaml.safe_load(open("tests/config.yaml"))
+    config = yaml.safe_load(open(Path(__file__).resolve().parents[2] / "tests" / "config.yaml"))
     zi = ZenControl(print_traffic=False)
     zi.add_controller(**config.get('zencontrol')[0])
 
@@ -20,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.1/tests/test_leds.py → zencontrol_python-0.1.3/examples/live/leds.py

@@ -1,11 +1,12 @@
 import asyncio
 import yaml
+from pathlib import Path
 from zencontrol import ZenProtocol, ZenController, ZenAddress, ZenAddressType, run_with_keyboard_interrupt
 
 async def main():
     """Test LED control queries"""
     # Load configuration
-    config = yaml.safe_load(open("tests/config.yaml"))
+    config = yaml.safe_load(open(Path(__file__).resolve().parents[2] / "tests" / "config.yaml"))
     
     # Create protocol and controller
     async with ZenProtocol(print_traffic=False) as tpi:

zencontrol_python-0.1.1/tests/test_level_change_v2.py → zencontrol_python-0.1.3/examples/live/level_change_v2.py

@@ -14,7 +14,7 @@ from zencontrol.api.protocol import ZenProtocol
 from zencontrol.api.types import ZenAddressType, ZenEventCode
 from zencontrol.utils import run_with_keyboard_interrupt
 
-CONFIG_PATH = Path(__file__).parent / "config.yaml"
+CONFIG_PATH = Path(__file__).resolve().parents[2] / "tests" / "config.yaml"
 ECG_ADDRESS = 33
 TIMEOUT_SECONDS = 5.0
 

zencontrol_python-0.1.1/tests/test_multicast.py → zencontrol_python-0.1.3/examples/live/multicast.py

@@ -1,11 +1,12 @@
 import asyncio
 import yaml
+from pathlib import Path
 from zencontrol import ZenProtocol, ZenController, ZenAddress, ZenInstance, ZenEventMode, run_with_keyboard_interrupt
 
 async def main():
     """Test multicast event monitoring"""
     # Load configuration
-    config = yaml.safe_load(open("tests/config.yaml"))
+    config = yaml.safe_load(open(Path(__file__).resolve().parents[2] / "tests" / "config.yaml"))
     
     # Create protocol and controller
     async with ZenProtocol(print_traffic=True, unicast=False) as tpi:

zencontrol_python-0.1.1/tests/test_profiles.py → zencontrol_python-0.1.3/examples/live/profiles.py

@@ -1,11 +1,12 @@
 import asyncio
 import yaml
+from pathlib import Path
 from zencontrol import ZenProtocol, ZenController, run_with_keyboard_interrupt
 
 async def main():
     """Test profile queries"""
     # Load configuration
-    config = yaml.safe_load(open("tests/config.yaml"))
+    config = yaml.safe_load(open(Path(__file__).resolve().parents[2] / "tests" / "config.yaml"))
     
     # Create protocol and controller
     async with ZenProtocol(print_traffic=False) as tpi:

zencontrol_python-0.1.1/tests/test_variables.py → zencontrol_python-0.1.3/examples/live/variables.py

@@ -1,11 +1,12 @@
 import asyncio
 import yaml
+from pathlib import Path
 from zencontrol import ZenProtocol, ZenController, run_with_keyboard_interrupt
 
 async def main():
     """Test system variable queries and sets"""
     # Load configuration
-    config = yaml.safe_load(open("tests/config.yaml"))
+    config = yaml.safe_load(open(Path(__file__).resolve().parents[2] / "tests" / "config.yaml"))
     
     # Create protocol and controller
     async with ZenProtocol(print_traffic=True) as tpi:

{zencontrol_python-0.1.1 → zencontrol_python-0.1.3}/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
@@ -157,36 +157,6 @@ class ZenMQTTBridge:
             pickle.dump(self.zen.cache, f)
 
 
-
-        """
-        controllers:
-          - id: 1
-            name: zen1
-            label: Zencontrol 1
-            groups:
-              - id: 0
-                name: All Lights
-                hide_group: True
-                hide_members: True
-              - id: 1
-                name: Ground
-            lights:
-              - ecg: 14
-                name: Lounge NW
-                room: Downstairs
-                groups:
-                  - 15
-              - ecg: 21
-                name: Guest NE
-                room: Guest Bedroom
-                groups:
-                  - 15
-              - ecg: 42
-                name: Garage
-                override_name: Garage Downlights
-                room: Garage
-        """
-        
         clist = []
         for c in sorted(self.control, key=lambda x: x.id):
             c: ZenController
@@ -844,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:
@@ -865,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 '--'}")
@@ -960,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
@@ -1139,4 +1109,4 @@ async def main():
         await bridge.stop()
 
 if __name__ == "__main__":
-    asyncio.run(main())
+    asyncio.run(main())

{zencontrol_python-0.1.1 → zencontrol_python-0.1.3}/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",
@@ -43,6 +41,9 @@ mqtt = [
     "aiomqtt>=2.1.0",
     "PyYAML>=6.0",
 ]
+# Simulator integration tests (tests/test_sim_*.py) need zencontrol-simulator
+# (pip install -e ../zencontrol-simulator, or a sibling ../zencontrol-simulator
+# checkout) plus PyYAML.
 
 [project.scripts]
 zencontrol-mqtt = "examples.mqtt_bridge:main"
@@ -64,7 +65,7 @@ zencontrol = ["py.typed"]
 
 [tool.black]
 line-length = 88
-target-version = ['py311']
+target-version = ['py314']
 include = '\.pyi?$'
 extend-exclude = '''
 /(
@@ -81,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
@@ -102,3 +103,13 @@ python_classes = ["Test*"]
 python_functions = ["test_*"]
 addopts = "-v --tb=short"
 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.1 → zencontrol_python-0.1.3}/tests/test_entity_scope.py

@@ -77,6 +77,9 @@ def test_controller_same_name_same_protocol_is_singleton() -> None:
         host="127.0.0.1",
         port=5108,
     )
+    a.client = object()  # type: ignore[assignment]
+    a.version = "1.2.3"
+    a.startup_complete = True
     b = ZenController(
         protocol=zen.protocol,
         id=2,
@@ -88,4 +91,8 @@ def test_controller_same_name_same_protocol_is_singleton() -> None:
     assert a is b
     assert a.label == "Second"
     assert a.host == "10.0.0.1"
+    # Re-construct must not wipe live transport / interview state
+    assert a.client is not None
+    assert a.version == "1.2.3"
+    assert a.startup_complete is True
     zen.clear_entity_caches()