zencontrol-python 0.1.6__py3-none-any.whl → 0.1.7__py3-none-any.whl

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

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/__init__.py

@@ -33,33 +33,53 @@ Example usage:
 """
 
 # High-level interface (recommended for most users)
+# API-level models (used by zen_api)
+from .api.models import DiscoveredController, ZenAddress, ZenColour, ZenInstance
+from .api.protocol import ZenProtocol
+
+# Shared types and exceptions
+from .api.types import (
+    ZenAddressType,
+    ZenColourType,
+    ZenEventCode,
+    ZenEventMask,
+    ZenEventMode,
+    ZenInstanceType,
+)
+from .exceptions import (
+    ZenConfigurationError,
+    ZenConnectionError,
+    ZenError,
+    ZenResponseError,
+    ZenTimeoutError,
+)
 from .interface import (
+    ZenAbsoluteInput,
+    ZenButton,
     ZenControl,
     ZenController,
-    ZenProfile,
-    ZenLight,
     ZenGroup,
-    ZenButton,
-    ZenAbsoluteInput,
+    ZenLight,
     ZenMotionSensor,
+    ZenProfile,
     ZenSystemVariable,
 )
 
-# API-level models (used by zen_api)
-from .api.models import ZenAddress, ZenInstance, ZenColour, DiscoveredController
-from .api.protocol import ZenProtocol
-
 # Low-level models (used by zen_io)
-from .io import ZenClient, ZenListener, ZenEvent, Request, Response, ResponseType, RequestType
-
-# Shared types and exceptions
-from .api.types import ZenAddressType, ZenInstanceType, ZenColourType, ZenEventCode, ZenEventMask, ZenEventMode
-from .exceptions import ZenError, ZenTimeoutError, ZenResponseError, ZenConnectionError, ZenConfigurationError
+from .io import (
+    Request,
+    RequestType,
+    Response,
+    ResponseType,
+    ZenClient,
+    ZenEvent,
+    ZenListener,
+)
 
 # Utilities
 from .utils import run_with_keyboard_interrupt
 
-__version__ = "0.1.6"
+__version__ = "0.1.7"
 __author__ = "Simon Wright"
 
 # Public API - these are the main classes users should import

zencontrol/api/__init__.py

@@ -8,9 +8,22 @@ This module contains models and types that belong to the API layer:
 - Types and enums used by the API layer
 """
 
-from .models import ZenController, ZenAddress, ZenInstance, ZenColour, ZenProfile, DiscoveredController
+from .models import (
+    DiscoveredController,
+    ZenAddress,
+    ZenColour,
+    ZenController,
+    ZenInstance,
+    ZenProfile,
+)
 from .protocol import ZenProtocol
-from .types import ZenAddressType, ZenInstanceType, ZenColourType, ZenEventMask, ZenEventMode
+from .types import (
+    ZenAddressType,
+    ZenColourType,
+    ZenEventMask,
+    ZenEventMode,
+    ZenInstanceType,
+)
 
 __all__ = [
     # API-level models

zencontrol/api/models.py

@@ -12,10 +12,16 @@ import socket
 import struct
 import time
 from dataclasses import dataclass, field
-from typing import Any, Self
+from typing import TYPE_CHECKING, Any, Self
 
 from ..io import ZenClient
-from .types import ZenAddressType, ZenInstanceType, ZenColourType, Const
+from .types import Const, ZenAddressType, ZenColourType, ZenInstanceType
+
+if TYPE_CHECKING:
+    # Addresses are only ever built from registered controllers, which are
+    # interface-layer objects. Type-only import; at runtime the interface layer
+    # imports this module, so importing it here would be circular.
+    from ..interface.interface import ZenController as ZenInterfaceController
 
 
 DEFAULT_CONTROLLER_PORT = 5108
@@ -33,8 +39,13 @@ class DiscoveredController:
 
 @dataclass
 class ZenController:
-    """Represents a ZenControl controller
-    
+    """Base class holding a controller's config and transport state.
+
+    ``zencontrol.ZenController`` (the interface layer) subclasses this and adds
+    entity state; that subclass is what ``ZenControl.add_controller()`` returns
+    and what registered controllers always are. This base exists so the API
+    layer can talk about controllers without importing the interface layer.
+
     The 'host' field can be any resolvable hostname or IP address.
     The 'ip' property will resolve the hostname to an IP address and cache it.
     """
@@ -55,7 +66,7 @@ class ZenController:
     client: ZenClient | None = None
     _ip: str | None = field(init=False, repr=False, default=None)
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         self._update_mac_bytes(self.mac)
 
     def __setattr__(self, name: str, value: object) -> None:
@@ -104,14 +115,14 @@ class ZenController:
 @dataclass(slots=True)
 class ZenAddress:
     """Represents a DALI address"""
-    controller: ZenController
+    controller: ZenInterfaceController
     type: ZenAddressType
     number: int
     label: str | None = field(default=None, init=False)
     serial: str | None = field(default=None, init=False)
     
     @classmethod
-    def broadcast(cls, controller: ZenController) -> Self:
+    def broadcast(cls, controller: ZenInterfaceController) -> Self:
         return cls(controller=controller, type=ZenAddressType.BROADCAST, number=255)
     
     def ecg(self) -> int:
@@ -152,7 +163,7 @@ class ZenAddress:
         """Return a stable HA-friendly identifier for this address."""
         return f"{self.type.name.casefold()}{self.number}"
     
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         match self.type:
             case ZenAddressType.BROADCAST:
                 if self.number != 255:
@@ -176,7 +187,7 @@ class ZenInstance:
     number: int
     active: bool | None = None
     error: bool | None = None
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         if not 0 <= self.number < Const.MAX_INSTANCE: 
             raise ValueError(f"Instance number must be between 0 and {Const.MAX_INSTANCE-1}, received {self.number}")
 
@@ -202,7 +213,11 @@ class ZenColour:
     @classmethod
     def from_bytes(cls, data: bytes) -> Self | None:
         match list(data):
-            case [ZenColourType.RGBWAF.value, r, g, b, w, a, f]:
+            case [ZenColourType.RGBWAF.value, r, g, b, *rest] if len(rest) <= 3:
+                # COLOUR_CHANGED_EVENT from a fixture with fewer than six channels
+                # carries only channels + 1 bytes, so an RGB fixture sends
+                # [0x80, R, G, B]. Channels the fixture does not have stay None.
+                w, a, f = (list(rest) + [None, None, None])[:3]
                 return cls(type=ZenColourType.RGBWAF, r=r, g=g, b=b, w=w, a=a, f=f)
             case [ZenColourType.TC.value, hi, lo] | [ZenColourType.TC.value, hi, lo, *_]:
                 if len(data) not in (3, 7):
@@ -215,7 +230,7 @@ class ZenColour:
             case _:
                 return None
     
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         match self.type:
             case ZenColourType.TC:
                 kelvin = self.kelvin
@@ -310,6 +325,6 @@ class ZenProfile:
     address: ZenAddress
     profile: int
     
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         if not (0 <= self.profile <= 255):
             raise ValueError(f"Profile must be 0-255, got {self.profile}")

zencontrol/api/protocol.py

@@ -1,29 +1,57 @@
-from collections.abc import Callable, Awaitable, Coroutine
 import asyncio
-import socket
+import logging
 import struct
 import time
-import logging
 import traceback
+from collections.abc import Awaitable, Callable, Coroutine
 from datetime import datetime as dt
-from typing import Any, Self, Literal, overload
-from enum import Enum
-from colorama import Fore, Back, Style
-from dataclasses import dataclass, field
-
-from ..io import ZenClient, ZenListener, ZenEvent, Request, Response, ResponseType, RequestType, EventConst, ClientConst
+from typing import TYPE_CHECKING, Any, Literal, Self, overload
+
+from ..exceptions import ZenTimeoutError
+from ..io import (
+    ClientConst,
+    EventConst,
+    Request,
+    RequestType,
+    Response,
+    ResponseType,
+    ZenClient,
+    ZenEvent,
+    ZenListener,
+)
+from ..utils import local_ip_for_remote
 from .models import (
     DEFAULT_CONTROLLER_PORT,
     DiscoveredController,
-    ZenController,
     ZenAddress,
-    ZenInstance,
     ZenColour,
-    ZenProfile,
+    ZenController,
+    ZenInstance,
 )
-from .types import ZenAddressType, ZenInstanceType, ZenColourType, ZenEventCode, ZenEventMask, ZenEventMode, ZenErrorCode, Const
-from ..exceptions import ZenError, ZenTimeoutError
-from ..utils import local_ip_for_remote
+from .types import (
+    Const,
+    ZenAddressType,
+    ZenErrorCode,
+    ZenEventCode,
+    ZenEventMask,
+    ZenEventMode,
+    ZenInstanceType,
+)
+
+# Magic import to avoid dependency on colorama
+try:
+    from colorama import Fore, Style
+except ImportError:
+    class _NoColor:
+        def __getattr__(self, _name: str) -> str:
+            return ""
+    Fore = Style = _NoColor()  # type: ignore[assignment]
+
+if TYPE_CHECKING:
+    # Registered controllers are always interface-layer objects, so anything
+    # that hands out ZenAddress instances is typed with that class. Type-only
+    # import; importing the interface layer at runtime would be circular.
+    from ..interface.interface import ZenController as ZenInterfaceController
 
 
 def _mac_bytes_to_str(mac: bytes) -> str:
@@ -218,7 +246,7 @@ class ZenProtocol:
                  unicast: bool = False,
                  listen_ip: str | None = None,
                  listen_port: int | None = None,
-                 cache: dict[bytes, dict[str, Any]] | None = None):
+                 cache: dict[bytes, dict[str, Any]] | None = None) -> None:
         self.logger = logger or logging.getLogger('null')
         if logger is None:
             self.logger.addHandler(logging.NullHandler())
@@ -236,7 +264,7 @@ class ZenProtocol:
             self.local_ip = self.listen_ip
         # Setup event monitoring using ZenListener
         self.event_listener: ZenListener | None = None
-        self.event_task = None
+        self.event_task: asyncio.Task[None] | None = None
         # Prevents double on_disconnect if stop races with listener death
         self._disconnect_notified = False
 
@@ -254,7 +282,7 @@ class ZenProtocol:
         self.disconnect_callback: Callable[[], Awaitable[None]] | None = None
         
         # Controllers will be assigned later
-        self.controllers = []
+        self.controllers: list[ZenInterfaceController] = []
         # Controllers identified via multicast but not yet registered
         self.identified_controllers: list[DiscoveredController] = []
         self._discovery_pending_macs: set[str] = set()
@@ -267,11 +295,11 @@ class ZenProtocol:
         # Fire-and-forget work (delayed events, refresh timers, motion holds)
         self._bg_tasks: set[asyncio.Task[Any]] = set()
 
-    async def __aenter__(self):
+    async def __aenter__(self) -> Self:
         """Async context manager entry"""
         return self
     
-    async def __aexit__(self, exc_type, exc_val, exc_tb):
+    async def __aexit__(self, exc_type: object, exc_val: object, exc_tb: object) -> None:
         """Async context manager exit"""
         await self.aclose()
     
@@ -306,7 +334,7 @@ class ZenProtocol:
             await asyncio.gather(*tasks, return_exceptions=True)
         self._bg_tasks.clear()
 
-    async def aclose(self):
+    async def aclose(self) -> None:
         """Stop monitoring, cancel background tasks, and close UDP clients."""
         await self.stop_event_monitoring()
         await self._cancel_background_tasks()
@@ -321,7 +349,7 @@ class ZenProtocol:
                 pass
         self.clear_entity_cache()
 
-    def set_controllers(self, controllers: list[ZenController]):
+    def set_controllers(self, controllers: list[ZenInterfaceController]) -> None:
         self.controllers = controllers # Used to match events to controllers, and include controller objects in callbacks
         # Drop identified entries that are now registered
         for ctrl in controllers:
@@ -438,8 +466,6 @@ class ZenProtocol:
                    ) -> (bytes | str | list[int] | int | bool) | None:
         request: Request = Request(command=command, data=[address] + (data or []), request_type=RequestType.BASIC)
         response_data, response_code = await self._send_packet(controller, request, cacheable=cacheable)
-        if response_data is None and response_code is None:
-            return None
         match response_code:
             case 0xA0: # OK
                 match return_type:
@@ -527,7 +553,7 @@ class ZenProtocol:
                 pass  # Answer is in data bytes
             case 0xA2: # NO_ANSWER
                 if response_data is not None and len(response_data) > 0:
-                    self.logger.error(f"No answer with code: {response_data}")
+                    self.logger.error("No answer with code: %r", response_data)
                 return None
             case 0xA3: # ERROR
                 self._log_response_error(response_data)
@@ -565,7 +591,7 @@ class ZenProtocol:
                     if self.print_traffic:
                         cached_packet = bytes([cached_response_type & 0xFF, len(cached_data) & 0xFF]) + cached_data
                         print(Fore.MAGENTA + f"FOUND:   [----, {' '.join(f'0x{b:02X}' for b in cache_key)}, ----]  "
-                            + Fore.RED + Style.DIM + f" CACHE HIT"
+                            + Fore.RED + Style.DIM + " CACHE HIT"
                             + Style.BRIGHT + Fore.CYAN + f"  [{' '.join(f'0x{b:02X}' for b in cached_packet)}, ----]"
                             + Style.RESET_ALL)
                     return cached_data, cached_response_type
@@ -661,7 +687,7 @@ class ZenProtocol:
                             profile_change_callback: Callable[..., Awaitable[None]] | None = None,
                             system_variable_change_callback: Callable[..., Awaitable[None]] | None = None,
                             disconnect_callback: Callable[[], Awaitable[None]] | None = None,
-                            ):
+                            ) -> None:
         self.button_press_callback = button_press_callback
         self.button_hold_callback = button_hold_callback
         self.absolute_input_callback = absolute_input_callback
@@ -674,7 +700,7 @@ class ZenProtocol:
         self.system_variable_change_callback = system_variable_change_callback
         self.disconnect_callback = disconnect_callback
         
-    async def start_event_monitoring(self):
+    async def start_event_monitoring(self) -> None:
         if self.event_task and not self.event_task.done():
             # Event monitoring already running
             return
@@ -714,7 +740,7 @@ class ZenProtocol:
         except Exception as err:
             self.logger.error(f"disconnect_callback error: {err}")
 
-    async def _async_event_listener(self):
+    async def _async_event_listener(self) -> None:
         """Async event listener using ZenListener"""
         # True unless stop_event_monitoring cancelled us intentionally
         unexpected = True
@@ -750,7 +776,7 @@ class ZenProtocol:
             if unexpected:
                 await self.notify_disconnect()
     
-    def get_controller_by_ip_mac(self, ip: str | None = None, mac: bytes | None = None):
+    def get_controller_by_ip_mac(self, ip: str | None = None, mac: bytes | None = None) -> ZenInterfaceController | None:
         """Find a controller by IP address or MAC address"""
         if ip is not None:
             for ctrl in self.controllers:
@@ -763,7 +789,7 @@ class ZenProtocol:
         return None
 
     def _ecd_address_from_target(
-        self, controller: ZenController, target: int
+        self, controller: ZenInterfaceController, target: int
     ) -> ZenAddress | None:
         """Map an event target byte to an ECD ZenAddress, or None if out of range."""
         number = target - 64
@@ -853,7 +879,7 @@ class ZenProtocol:
                     pass
                 temp.client = None
 
-    async def _process_zen_event(self, event: ZenEvent):
+    async def _process_zen_event(self, event: ZenEvent) -> None:
         """Process received ZenEvent from ZenListener"""
         typecast = "unicast" if self.unicast else "multicast"
         
@@ -864,7 +890,6 @@ class ZenProtocol:
             return
 
         ip_address = event.ip_address
-        ip_port = event.ip_port
         target = event.target
         payload = event.payload
         event_code = event.event_code
@@ -890,9 +915,6 @@ class ZenProtocol:
         if len(payload) < min_payload:
             self.logger.warning(f"Event {event_enum.name} payload too short: {len(payload)} < {min_payload}")
             return
-        # Get event name from ZenEventCode, with fallback to unknown, underscores replaced with spaces, and first letter capitalized
-        event_name = event_enum.name.replace("_", " ").title()
-
         # Print the raw packet
         # if self.print_traffic: 
         #     print(Fore.MAGENTA + f"{typecast.upper()} {ip_address}:" + 
@@ -1054,7 +1076,7 @@ class ZenProtocol:
                 pass
 
 
-    async def stop_event_monitoring(self):
+    async def stop_event_monitoring(self) -> None:
         """Stop listening for events"""
         if self.event_task:
             task = self.event_task
@@ -1114,8 +1136,9 @@ class ZenProtocol:
             return None
         return ZenEventMode.from_byte(response[0]).enabled
     
-    async def dali_add_tpi_event_filter(self, address: ZenAddress|ZenInstance, filter: ZenEventMask = ZenEventMask.all_events()) -> bool | None:
+    async def dali_add_tpi_event_filter(self, address: ZenAddress|ZenInstance, filter: ZenEventMask | None = None) -> bool | None:
         """Stop specific events from an address/instance from being sent. Events in mask will be muted. Returns true if filter was added successfully."""
+        if filter is None: filter = ZenEventMask.all_events()
         instance_number = 0xFF
         if isinstance(address, ZenInstance):
             instance: ZenInstance = address
@@ -1127,8 +1150,9 @@ class ZenProtocol:
                              [instance_number, filter.upper(), filter.lower()],
                              return_type='bool')
     
-    async def dali_clear_tpi_event_filter(self, address: ZenAddress|ZenInstance, unfilter: ZenEventMask = ZenEventMask.all_events()) -> bool | None:
+    async def dali_clear_tpi_event_filter(self, address: ZenAddress|ZenInstance, unfilter: ZenEventMask | None = None) -> bool | None:
         """Allow specific events from an address/instance to be sent again. Events in mask will be unmuted. Returns true if filter was cleared successfully."""
+        if unfilter is None: unfilter = ZenEventMask.all_events()
         instance_number = 0xFF
         if isinstance(address, ZenInstance):
             instance: ZenInstance = address
@@ -1185,8 +1209,9 @@ class ZenProtocol:
                 
         return results
 
-    async def tpi_event_emit(self, controller: ZenController, mode: ZenEventMode = ZenEventMode(enabled=True, filtering=False, unicast=False, multicast=True)) -> bool:
+    async def tpi_event_emit(self, controller: ZenController, mode: ZenEventMode | None = None) -> bool:
         """Enable or disable TPI Event emission. Returns True if successful, else False."""
+        if mode is None: mode = ZenEventMode(enabled=True, filtering=False, unicast=False, multicast=True)
         mask = mode.bitmask()
         # response = await self._send_basic(controller, self.CMD["ENABLE_TPI_EVENT_EMIT"], 0x00) # disable first to clear any existing state... I think this is a bug?
         response = await self._send_basic(controller, self.CMD["ENABLE_TPI_EVENT_EMIT"], mask)
@@ -1195,7 +1220,7 @@ class ZenProtocol:
                 return True
         return False
 
-    async def set_tpi_event_unicast_address(self, controller: ZenController, ipaddr: str | None = None, port: int | None = None):
+    async def set_tpi_event_unicast_address(self, controller: ZenController, ipaddr: str | None = None, port: int | None = None) -> bytes | None:
         """Configure TPI Events for Unicast mode with IP and port as defined in the ZenController instance."""
         data = [0,0,0,0,0,0]
         if port is not None:
@@ -1215,7 +1240,7 @@ class ZenProtocol:
                     raise ValueError
                 data[2:6] = ip_bytes
             except ValueError:
-                raise ValueError("Invalid IP address format")
+                raise ValueError("Invalid IP address format") from None
         
         return await self._send_dynamic(controller, self.CMD["SET_TPI_EVENT_UNICAST_ADDRESS"], data)
 
@@ -1244,7 +1269,7 @@ class ZenProtocol:
             }
         return None
 
-    async def query_group_numbers(self, controller: ZenController) -> list[ZenAddress]:
+    async def query_group_numbers(self, controller: ZenInterfaceController) -> list[ZenAddress]:
         """Query a controller for groups."""
         groups = await self._send_basic(controller, self.CMD["QUERY_GROUP_NUMBERS"], return_type='list')
         zen_groups = []
@@ -1443,7 +1468,7 @@ class ZenProtocol:
             return zen_groups
         return []
 
-    async def query_dali_addresses_with_instances(self, controller: ZenController, start_address: int=0) -> list[ZenAddress]: # TODO: automate iteration over start_address=0, start_address=60, etc.
+    async def query_dali_addresses_with_instances(self, controller: ZenInterfaceController, start_address: int=0) -> list[ZenAddress]: # TODO: automate iteration over start_address=0, start_address=60, etc.
         """Query for DALI addresses that have instances associated with them.
         
         Due to payload restrictions, this needs to be called multiple times with different
@@ -1509,7 +1534,7 @@ class ZenProtocol:
             return f"{response[0]}.{response[1]}.{response[2]}"
         return None
     
-    async def query_control_gear_dali_addresses(self, controller: ZenController) -> list[ZenAddress]:
+    async def query_control_gear_dali_addresses(self, controller: ZenInterfaceController) -> list[ZenAddress]:
         """Query which DALI control gear addresses are present in the database. Returns a list of ZenAddress instances."""
         response = await self._send_basic(controller, self.CMD["QUERY_CONTROL_GEAR_DALI_ADDRESSES"])
         if response and len(response) == 8:  # 8 data bytes representing addresses 0-63

zencontrol/api/types.py

@@ -7,9 +7,9 @@ This module contains types and enums that belong to the API layer:
 - Constants used by the API layer
 """
 
+from dataclasses import dataclass
 from enum import Enum
 from typing import Self
-from dataclasses import dataclass
 
 
 class ZenAddressType(Enum):
@@ -105,7 +105,7 @@ class ZenEventMask:
     level_change_v2: bool = False
     
     @classmethod
-    def all_events(cls):
+    def all_events(cls) -> Self:
         # Exclude deprecated level_change / group_level_change — use level_change_v2 (spec V2.001.121+)
         return cls(
             button_press = True,

zencontrol/exceptions.py

@@ -6,6 +6,7 @@ This module defines all custom exceptions used throughout the library.
 
 from typing import Any
 
+
 class ZenError(Exception):
     """Base exception for Zen protocol errors"""
     pass

zencontrol/interface/__init__.py

@@ -8,14 +8,14 @@ This module contains models that belong to the zen_interface layer:
 """
 
 from .interface import (
+    ZenAbsoluteInput,
+    ZenButton,
     ZenControl,
     ZenController,
-    ZenProfile,
-    ZenLight,
     ZenGroup,
-    ZenButton,
-    ZenAbsoluteInput,
+    ZenLight,
     ZenMotionSensor,
+    ZenProfile,
     ZenSystemVariable,
 )