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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zencontrol-python
-Version: 0.1.4
+Version: 0.1.7
 Summary: Python implementation of the Zencontrol TPI Advanced protocol for DALI lighting controllers.
 Author: Simon Wright
 License-Expression: MIT
@@ -19,17 +19,20 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: colorama>=0.4.6
+Provides-Extra: colorama
+Requires-Dist: colorama>=0.4.6; extra == "colorama"
 Provides-Extra: dev
 Requires-Dist: pytest>=6.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
-Requires-Dist: black>=22.0; extra == "dev"
-Requires-Dist: flake8>=4.0; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
 Requires-Dist: mypy>=0.950; extra == "dev"
+Requires-Dist: types-colorama; extra == "dev"
 Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: colorama>=0.4.6; extra == "dev"
 Provides-Extra: mqtt
 Requires-Dist: aiomqtt>=2.1.0; extra == "mqtt"
 Requires-Dist: PyYAML>=6.0; extra == "mqtt"
+Requires-Dist: colorama>=0.4.6; extra == "mqtt"
 Dynamic: license-file
 
 # zencontrol-python
@@ -49,10 +52,12 @@ A practical demonstration is [zencontrol-homeassistant](https://github.com/sjwri
 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
+* **Object-based entity model** — Optional. Expresses lights, groups, profiles, buttons, motion sensors, absolute inputs, and system variables as rich objects with interview/discovery helpers
 * **UDP transport resilience** — request retries and queue-failure backoff
+* **Event keepalive** — periodic emit-state ping; re-enables TPI events (and unicast target) if a controller reboots while the listener stays up
 * **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
+* **Absolute inputs** — discovery of numerical ECD instances (dials/sliders) with 16-bit value-change 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

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

@@ -15,10 +15,12 @@ A practical demonstration is [zencontrol-homeassistant](https://github.com/sjwri
 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
+* **Object-based entity model** — Optional. Expresses lights, groups, profiles, buttons, motion sensors, absolute inputs, and system variables as rich objects with interview/discovery helpers
 * **UDP transport resilience** — request retries and queue-failure backoff
+* **Event keepalive** — periodic emit-state ping; re-enables TPI events (and unicast target) if a controller reboots while the listener stays up
 * **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
+* **Absolute inputs** — discovery of numerical ECD instances (dials/sliders) with 16-bit value-change 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

{zencontrol_python-0.1.4 → zencontrol_python-0.1.7}/examples/live/level_change_v2.py

@@ -9,7 +9,7 @@ if str(ROOT) not in sys.path:
 
 import yaml
 
-from zencontrol.api.models import ZenAddress, ZenController
+from zencontrol import ZenAddress, ZenController
 from zencontrol.api.protocol import ZenProtocol
 from zencontrol.api.types import ZenAddressType, ZenEventCode
 from zencontrol.utils import run_with_keyboard_interrupt

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

@@ -10,12 +10,18 @@ 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
 import aiomqtt
-from colorama import Fore, Back, Style
 import logging
 from logging.handlers import RotatingFileHandler
 import math
 import pickle
 import traceback
+try:
+    from colorama import Fore, Style
+except ImportError:
+    class _NoColor:
+        def __getattr__(self, _name: str) -> str:
+            return ""
+    Fore = Style = _NoColor()  # type: ignore[assignment]
 
 class RateLimiter:
     """Rate limiter to control concurrent coroutine execution"""

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

@@ -24,22 +24,25 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Typing :: Typed",
 ]
-dependencies = [
-    "colorama>=0.4.6",
-]
+dependencies = []
 
 [project.optional-dependencies]
+colorama = [
+    "colorama>=0.4.6",
+]
 dev = [
     "pytest>=6.0",
     "pytest-asyncio>=0.18.0",
-    "black>=22.0",
-    "flake8>=4.0",
+    "ruff",
     "mypy>=0.950",
+    "types-colorama",
     "build>=1.0",
+    "colorama>=0.4.6",
 ]
 mqtt = [
     "aiomqtt>=2.1.0",
     "PyYAML>=6.0",
+    "colorama>=0.4.6",
 ]
 # Simulator integration tests (tests/test_sim_*.py) need zencontrol-simulator
 # (pip install -e ../zencontrol-simulator, or a sibling ../zencontrol-simulator
@@ -63,24 +66,6 @@ include = ["zencontrol*", "examples*"]
 [tool.setuptools.package-data]
 zencontrol = ["py.typed"]
 
-[tool.black]
-line-length = 88
-target-version = ['py314']
-include = '\.pyi?$'
-extend-exclude = '''
-/(
-  # directories
-  \.eggs
-  | \.git
-  | \.hg
-  | \.mypy_cache
-  | \.tox
-  | \.venv
-  | build
-  | dist
-)/
-'''
-
 [tool.mypy]
 python_version = "3.14"
 warn_return_any = true
@@ -109,7 +94,13 @@ markers = [
 
 [tool.ruff]
 target-version = "py314"
-line-length = 88
+line-length = 130
+exclude = ["examples"]
 
 [tool.ruff.lint]
 select = ["ASYNC", "B", "E", "F", "I", "UP"]
+ignore = [
+    "ASYNC109", # Timeout parameters are part of the public async API.
+    "E501",     # Preserve existing protocol logging and payload formatting.
+    "E701",     # Allow readable single-line conditionals.
+]

zencontrol_python-0.1.7/tests/test_absolute_input.py

@@ -0,0 +1,96 @@
+"""Unit tests for ZenAbsoluteInput discovery and events."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock
+
+import pytest
+
+from zencontrol.api.models import ZenAddress, ZenInstance
+from zencontrol.api.types import ZenAddressType, ZenInstanceType
+from zencontrol.interface.interface import ZenAbsoluteInput, ZenControl
+
+
+def _ecd_instance(zen: ZenControl, *, number: int = 0, inst: int = 1) -> ZenInstance:
+    ctrl = zen.add_controller(
+        id=1, name="house", label="House", host="127.0.0.1", port=5108
+    )
+    addr = ZenAddress(controller=ctrl, type=ZenAddressType.ECD, number=number)
+    return ZenInstance(address=addr, type=ZenInstanceType.ABSOLUTE_INPUT, number=inst)
+
+
+@pytest.mark.asyncio
+async def test_absolute_input_event_parses_16bit_value() -> None:
+    zen = ZenControl()
+    instance = _ecd_instance(zen)
+    changes: list[tuple[ZenAbsoluteInput, int]] = []
+
+    async def on_change(absolute_input: ZenAbsoluteInput, value: int) -> None:
+        changes.append((absolute_input, value))
+
+    zen.absolute_input_change = on_change
+    absolute = ZenAbsoluteInput(protocol=zen.protocol, instance=instance)
+    assert absolute.interview_hydrate(
+        {"serial": "1", "label": "Panel", "instance_label": "Dial"}
+    )
+
+    await zen.absolute_input_event(instance, bytes([1, 0x12, 0x34]))
+    assert absolute.value == 0x1234
+    assert changes == [(absolute, 0x1234)]
+
+    await zen.absolute_input_event(instance, bytes([1, 0x12, 0x34]))
+    assert changes == [(absolute, 0x1234)]
+
+    await zen.absolute_input_event(instance, bytes([1, 0x00, 0x01]))
+    assert absolute.value == 1
+    assert changes[-1] == (absolute, 1)
+
+
+@pytest.mark.asyncio
+async def test_absolute_input_event_ignores_short_payload() -> None:
+    zen = ZenControl()
+    instance = _ecd_instance(zen)
+    absolute = ZenAbsoluteInput(protocol=zen.protocol, instance=instance)
+    await zen.absolute_input_event(instance, bytes([1]))
+    assert absolute.value is None
+
+
+@pytest.mark.asyncio
+async def test_get_absolute_inputs_filters_instance_type() -> None:
+    zen = ZenControl()
+    ctrl = zen.add_controller(
+        id=1, name="house", label="House", host="127.0.0.1", port=5108
+    )
+    addr = ZenAddress(controller=ctrl, type=ZenAddressType.ECD, number=2)
+    abs_inst = ZenInstance(
+        address=addr, type=ZenInstanceType.ABSOLUTE_INPUT, number=0
+    )
+    btn_inst = ZenInstance(
+        address=addr, type=ZenInstanceType.PUSH_BUTTON, number=1
+    )
+
+    zen._get_addresses_with_instances = AsyncMock(return_value=[addr])  # noqa: SLF001
+    zen.protocol.query_instances_by_address = AsyncMock(
+        return_value=[abs_inst, btn_inst]
+    )
+    zen.protocol.query_dali_device_label = AsyncMock(return_value="Wall")
+    zen.protocol.query_dali_serial = AsyncMock(return_value="ABC")
+    zen.protocol.query_dali_instance_label = AsyncMock(return_value="Slider")
+
+    found = await zen.get_absolute_inputs(controller=ctrl)
+    assert len(found) == 1
+    item = next(iter(found))
+    assert item.instance.type == ZenInstanceType.ABSOLUTE_INPUT
+    assert item.label == "Wall"
+    assert item.instance_label == "Slider"
+    assert item in ctrl.absolute_inputs
+
+
+@pytest.mark.asyncio
+async def test_absolute_input_singleton_per_protocol() -> None:
+    zen = ZenControl()
+    instance = _ecd_instance(zen)
+    a = ZenAbsoluteInput(protocol=zen.protocol, instance=instance)
+    b = ZenAbsoluteInput(protocol=zen.protocol, instance=instance)
+    assert a is b
+    assert "house 0 1" in zen.protocol.entity_registry.absolute_inputs

{zencontrol_python-0.1.4 → zencontrol_python-0.1.7}/tests/test_discovery.py

@@ -6,7 +6,8 @@ from unittest.mock import AsyncMock, patch
 
 import pytest
 
-from zencontrol.api.models import DiscoveredController, ZenController
+from zencontrol import ZenController
+from zencontrol.api.models import DiscoveredController
 from zencontrol.api.protocol import ZenProtocol
 from zencontrol.io.event import ZenEvent
 
@@ -76,7 +77,7 @@ async def test_second_packet_from_same_mac_or_ip_is_ignored() -> None:
 async def test_registered_controller_is_not_discovered() -> None:
     protocol = ZenProtocol()
     ctrl = ZenController(
-        id="1",
+        id=1,
         name="known",
         label="Known",
         host="192.168.1.50",
@@ -105,7 +106,7 @@ async def test_registering_controller_forgets_identified() -> None:
     assert len(protocol.identified_controllers) == 1
 
     ctrl = ZenController(
-        id="1",
+        id=1,
         name="kitchen",
         label="Kitchen",
         host="192.168.1.50",
@@ -136,7 +137,7 @@ async def test_label_query_failure_still_remembers_controller() -> None:
 async def test_new_controller_discovered_while_one_is_registered() -> None:
     protocol = ZenProtocol()
     known = ZenController(
-        id="1",
+        id=1,
         name="known",
         label="Known",
         host="192.168.1.10",

zencontrol_python-0.1.7/tests/test_event_keepalive.py

@@ -0,0 +1,174 @@
+"""Unit tests for TPI event emit keepalive / re-assert."""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from zencontrol.api.types import ZenEventMode
+from zencontrol.interface.interface import ZenControl
+
+
+class _BlockingListener:
+    def __init__(self) -> None:
+        self.listen_port = 6969
+
+    async def events(self):
+        try:
+            while True:
+                await asyncio.sleep(3600)
+                yield  # pragma: no cover
+        except asyncio.CancelledError:
+            raise
+
+    async def close(self):
+        return None
+
+
+def _controller(name: str = "ctrl") -> SimpleNamespace:
+    return SimpleNamespace(name=name, filtering=False, mac="AA:BB:CC:DD:EE:01")
+
+
+@pytest.mark.asyncio
+async def test_assert_reconfigures_when_emit_disabled() -> None:
+    zen = ZenControl()
+    zen.protocol.event_listener = object()  # pretend listener is up
+    ctrl = _controller()
+    ctrl.is_controller_ready = AsyncMock(return_value=True)
+    zen.controllers = [ctrl]  # type: ignore[list-item]
+
+    zen.protocol.query_tpi_event_unicast_address = AsyncMock(return_value=None)
+    zen.protocol.query_tpi_event_emit_state = AsyncMock(return_value=False)
+    zen.configure_controller_events = AsyncMock(return_value=True)
+
+    assert await zen.assert_controller_events(ctrl) is True  # type: ignore[arg-type]
+    zen.configure_controller_events.assert_awaited_once_with(ctrl)
+
+
+@pytest.mark.asyncio
+async def test_assert_marks_unreachable_when_reassert_fails() -> None:
+    zen = ZenControl()
+    zen.protocol.event_listener = object()
+    ctrl = _controller()
+    ctrl.is_controller_ready = AsyncMock(return_value=True)
+    zen.protocol.query_tpi_event_unicast_address = AsyncMock(return_value=None)
+    zen.protocol.query_tpi_event_emit_state = AsyncMock(return_value=False)
+    zen.configure_controller_events = AsyncMock(return_value=False)
+    status_cb = AsyncMock()
+    zen.controller_status_change = status_cb
+
+    assert await zen.assert_controller_events(ctrl) is False  # type: ignore[arg-type]
+    status_cb.assert_awaited_once_with(ctrl, "unreachable")
+
+
+@pytest.mark.asyncio
+async def test_assert_defers_while_controller_not_ready() -> None:
+    zen = ZenControl()
+    zen.protocol.event_listener = object()
+    ctrl = _controller()
+    ctrl.is_controller_ready = AsyncMock(return_value=False)
+    zen.configure_controller_events = AsyncMock()
+    zen.protocol.query_tpi_event_unicast_address = AsyncMock()
+    status_cb = AsyncMock()
+    zen.controller_status_change = status_cb
+
+    assert await zen.assert_controller_events(ctrl) is True  # type: ignore[arg-type]
+    zen.configure_controller_events.assert_not_awaited()
+    zen.protocol.query_tpi_event_unicast_address.assert_not_awaited()
+    status_cb.assert_awaited_once_with(ctrl, "starting")
+
+
+@pytest.mark.asyncio
+async def test_assert_noop_when_emit_enabled() -> None:
+    zen = ZenControl()
+    zen.protocol.event_listener = object()
+    ctrl = _controller()
+    ctrl.is_controller_ready = AsyncMock(return_value=True)
+
+    zen.protocol.query_tpi_event_unicast_address = AsyncMock(
+        return_value={
+            "mode": ZenEventMode(enabled=True, unicast=False, multicast=True),
+            "port": 0,
+            "ip": "0.0.0.0",
+        }
+    )
+    zen.configure_controller_events = AsyncMock()
+
+    assert await zen.assert_controller_events(ctrl) is True  # type: ignore[arg-type]
+    zen.configure_controller_events.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_assert_reconfigures_on_unicast_target_mismatch() -> None:
+    zen = ZenControl(unicast=True)
+    zen.protocol.event_listener = object()
+    zen.protocol.local_ip = "192.168.1.10"
+    zen.protocol.listen_port = 6970
+    ctrl = _controller()
+    ctrl.is_controller_ready = AsyncMock(return_value=True)
+
+    zen.protocol.query_tpi_event_unicast_address = AsyncMock(
+        return_value={
+            "mode": ZenEventMode(enabled=True, unicast=True, multicast=False),
+            "port": 6970,
+            "ip": "192.168.1.99",  # stale target after HA IP change / reboot
+        }
+    )
+    zen.configure_controller_events = AsyncMock(return_value=True)
+
+    assert await zen.assert_controller_events(ctrl) is True  # type: ignore[arg-type]
+    zen.configure_controller_events.assert_awaited_once_with(ctrl)
+
+
+@pytest.mark.asyncio
+async def test_assert_returns_false_when_ping_fails() -> None:
+    zen = ZenControl()
+    zen.protocol.event_listener = object()
+    ctrl = _controller()
+    ctrl.is_controller_ready = AsyncMock(return_value=None)
+    zen.configure_controller_events = AsyncMock()
+
+    assert await zen.assert_controller_events(ctrl) is False  # type: ignore[arg-type]
+    zen.configure_controller_events.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_keepalive_loop_reasserts_and_stops_cleanly() -> None:
+    zen = ZenControl()
+    zen.event_keepalive_interval = 0.05
+    zen.reconnect_min_delay = 0.01
+    ctrl = _controller()
+    zen.add_controller(
+        id=1,
+        name=ctrl.name,
+        label="Controller",
+        host="127.0.0.1",
+        mac=ctrl.mac,
+    )
+
+    configure = AsyncMock()
+    zen.configure_controller_events = configure
+    zen.protocol.query_tpi_event_unicast_address = AsyncMock(return_value=None)
+    zen.protocol.query_tpi_event_emit_state = AsyncMock(return_value=False)
+    zen.protocol.query_controller_startup_complete = AsyncMock(return_value=True)
+    # start_event_monitoring configures controllers itself; stub the UDP path.
+    zen.protocol.set_tpi_event_unicast_address = AsyncMock()
+    zen.protocol.tpi_event_emit = AsyncMock(return_value=True)
+
+    with patch(
+        "zencontrol.api.protocol.ZenListener.create",
+        new=AsyncMock(return_value=_BlockingListener()),
+    ):
+        await zen.start()
+        for _ in range(40):
+            if configure.await_count >= 1:
+                break
+            await asyncio.sleep(0.05)
+        else:
+            pytest.fail("keepalive did not re-assert events")
+
+        await zen.stop()
+        assert zen._keepalive_task is None or zen._keepalive_task.done()

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

@@ -67,7 +67,7 @@ async def test_aclose_closes_clients_and_clears_instances() -> None:
     ctrl.client = fake_client
 
     address = ZenAddress(controller=ctrl, type=ZenAddressType.ECG, number=1)
-    light = ZenLight(protocol=zen.protocol, address=address)
+    ZenLight(protocol=zen.protocol, address=address)
     assert "ctrl-a 1" in zen.protocol.entity_registry.lights
     assert "ctrl-a" in zen.protocol.entity_registry.controllers
 

{zencontrol_python-0.1.4 → zencontrol_python-0.1.7}/tests/test_sim_events.py

@@ -3,11 +3,10 @@
 from __future__ import annotations
 
 import pytest
+from helpers import LEGACY_ACK, wait_until
 
 from zencontrol import ZenColour, ZenColourType
 
-from helpers import wait_until
-
 pytestmark = pytest.mark.simulator
 
 
@@ -26,7 +25,7 @@ async def test_scene_and_colour_events_via_protocol(live_sim):
     p.set_callbacks(scene_change_callback=on_scene, colour_change_callback=on_colour)
     await p.start_event_monitoring()
 
-    assert await p.dali_scene(live_sim.ecg(0), 1) is True
+    assert await p.dali_scene(live_sim.ecg(0), 1) is LEGACY_ACK
     await wait_until(
         lambda: any(t == "ECG" and n == 0 and s == 1 for t, n, s in scenes),
         message="expected scene-change event for ECG 0 → scene 1",
@@ -61,7 +60,7 @@ async def test_group_level_event_via_protocol(live_sim):
     )
     await p.start_event_monitoring()
 
-    assert await p.dali_arc_level(live_sim.group(0), 44) is True
+    assert await p.dali_arc_level(live_sim.group(0), 44) is LEGACY_ACK
     await wait_until(
         lambda: any(n == 0 and level == 44 for n, level in group_events),
         message="expected group level-change event for group 0 → 44",
@@ -83,7 +82,7 @@ async def test_member_events_on_group_scene(live_sim):
     p.set_callbacks(scene_change_callback=on_scene, level_change_callback=on_level)
     await p.start_event_monitoring()
 
-    assert await p.dali_scene(live_sim.group(0), 1) is True
+    assert await p.dali_scene(live_sim.group(0), 1) is LEGACY_ACK
     await wait_until(
         lambda: (
             any(t == "GROUP" and n == 0 and s == 1 for t, n, s in scenes)
@@ -158,6 +157,28 @@ async def test_button_hold_and_occupancy_inject(live_sim):
     )
 
 
+@pytest.mark.asyncio
+async def test_absolute_input_inject(live_sim):
+    p = live_sim.protocol
+    events: list[tuple[int, int, bytes]] = []
+
+    async def on_absolute(*, instance, payload):
+        events.append((instance.address.number, instance.number, bytes(payload)))
+
+    p.set_callbacks(absolute_input_callback=on_absolute)
+    await p.start_event_monitoring()
+
+    live_sim.sim.inject_absolute_input(13, 0, 0xABCD)
+    await wait_until(
+        lambda: any(
+            ecd == 13 and inst == 0 and payload == bytes([0, 0xAB, 0xCD])
+            for ecd, inst, payload in events
+        ),
+        message="expected absolute-input inject event for ECD 13",
+    )
+    assert live_sim.world.instance(13, 0).value == 0xABCD
+
+
 @pytest.mark.asyncio
 async def test_inject_level_scene_colour_profile_events(live_sim):
     from zencontrol_simulator.world import Colour