aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/central/decorators.py

@@ -0,0 +1,184 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""Decorators for central used within aiohomematic."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from datetime import datetime
+from functools import partial, wraps
+import inspect
+import logging
+from typing import Any, Final, cast
+
+from aiohomematic import client as hmcl, i18n
+from aiohomematic.central import rpc_server as rpc
+from aiohomematic.const import SystemEventType
+from aiohomematic.exceptions import AioHomematicException
+from aiohomematic.support import extract_exc_args
+from aiohomematic.type_aliases import CallableAny, CallableNone
+
+_LOGGER: Final = logging.getLogger(__name__)
+_INTERFACE_ID: Final = "interface_id"
+_CHANNEL_ADDRESS: Final = "channel_address"
+_PARAMETER: Final = "parameter"
+_VALUE: Final = "value"
+
+
+def callback_backend_system(system_event: SystemEventType) -> Callable[[CallableAny], CallableAny]:  # kwonly: disable
+    """Check if backend_system_callback is set and call it AFTER original function."""
+
+    def decorator_backend_system_callback[**P, R](
+        func: Callable[P, R | Awaitable[R]],
+    ) -> Callable[P, R | Awaitable[R]]:
+        """Decorate callback system events."""
+
+        @wraps(func)
+        async def async_wrapper_backend_system_callback(*args: P.args, **kwargs: P.kwargs) -> R:
+            """Wrap async callback system events."""
+            return_value = cast(R, await func(*args, **kwargs))  # type: ignore[misc]
+            await _exec_backend_system_callback(*args, **kwargs)
+            return return_value
+
+        @wraps(func)
+        def wrapper_backend_system_callback(*args: P.args, **kwargs: P.kwargs) -> R:
+            """Wrap callback system events."""
+            return_value = cast(R, func(*args, **kwargs))
+            try:
+                unit = args[0]
+                looper: Any = None
+                # Check for CentralUnit (by duck typing - has looper attribute)
+                if hasattr(unit, "looper"):
+                    looper = unit.looper
+                # Check for coordinator with _task_scheduler
+                elif hasattr(unit, "_task_scheduler"):
+                    looper = unit._task_scheduler  # pylint: disable=protected-access
+                # Check for RPCFunctions
+                elif isinstance(unit, rpc.RPCFunctions) and (
+                    entry := unit.get_central_entry(interface_id=str(args[1]))
+                ):
+                    looper = entry.looper
+                if looper:
+                    # Use partial to avoid lambda closure capturing args/kwargs
+                    looper.create_task(
+                        target=partial(_exec_backend_system_callback, *args, **kwargs),
+                        name="wrapper_backend_system_callback",
+                    )
+            except Exception as exc:
+                _LOGGER.warning(
+                    i18n.tr(
+                        key="exception.central.decorators.backend_system_handler.identify_central_failed",
+                        reason=extract_exc_args(exc=exc),
+                    )
+                )
+            return return_value
+
+        async def _exec_backend_system_callback(*args: Any, **kwargs: Any) -> None:
+            """Execute the callback for a system event."""
+            if not ((len(args) > 1 and not kwargs) or (len(args) == 1 and kwargs)):
+                _LOGGER.error(  # i18n-log: ignore
+                    "EXEC_BACKEND_SYSTEM_CALLBACK failed: *args not supported for callback_system_event"
+                )
+            try:
+                args = args[1:]
+                interface_id: str = args[0] if len(args) > 0 else str(kwargs[_INTERFACE_ID])
+                if client := hmcl.get_client(interface_id=interface_id):
+                    client.modified_at = datetime.now()
+                    client.central.event_coordinator.publish_system_event(system_event=system_event, **kwargs)
+            except Exception as exc:  # pragma: no cover
+                _LOGGER.error(  # i18n-log: ignore
+                    "EXEC_BACKEND_SYSTEM_CALLBACK failed: Unable to reduce kwargs for backend_system_callback"
+                )
+                raise AioHomematicException(
+                    i18n.tr(
+                        key="exception.central.decorators.backend_system_handler.args_exception",
+                        reason=extract_exc_args(exc=exc),
+                    )
+                ) from exc
+
+        if inspect.iscoroutinefunction(func):
+            return async_wrapper_backend_system_callback
+        return wrapper_backend_system_callback
+
+    return decorator_backend_system_callback
+
+
+def callback_event[**P, R](func: Callable[P, R]) -> Callable[P, R | Awaitable[R]]:  # kwonly: disable
+    """Check if event_callback is set and call it AFTER original function."""
+
+    def _exec_event_callback(*args: Any, **kwargs: Any) -> None:
+        """Execute the callback for a data_point event."""
+        try:
+            # Expected signature: (self, interface_id, channel_address, parameter, value)
+            interface_id: str
+            if len(args) > 1:
+                interface_id = cast(str, args[1])
+                channel_address = cast(str, args[2])
+                parameter = cast(str, args[3])
+                value = args[4] if len(args) > 4 else kwargs.get(_VALUE)
+            else:
+                interface_id = cast(str, kwargs[_INTERFACE_ID])
+                channel_address = cast(str, kwargs[_CHANNEL_ADDRESS])
+                parameter = cast(str, kwargs[_PARAMETER])
+                value = kwargs[_VALUE]
+
+            if client := hmcl.get_client(interface_id=interface_id):
+                client.modified_at = datetime.now()
+                client.central.event_coordinator.publish_backend_parameter_event(
+                    interface_id=interface_id, channel_address=channel_address, parameter=parameter, value=value
+                )
+        except Exception as exc:  # pragma: no cover
+            _LOGGER.error(  # i18n-log: ignore
+                "EXEC_DATA_POINT_EVENT_CALLBACK failed: Unable to process args/kwargs for event_callback"
+            )
+            raise AioHomematicException(
+                i18n.tr(
+                    key="exception.central.decorators.event_handler.args_exception",
+                    reason=extract_exc_args(exc=exc),
+                )
+            ) from exc
+
+    def _schedule_or_exec(*args: Any, **kwargs: Any) -> None:
+        """Schedule event callback on looper when possible, else execute inline."""
+        try:
+            unit = args[0]
+            looper: Any = None
+            # Check for CentralUnit (by duck typing - has looper attribute)
+            if hasattr(unit, "looper"):
+                looper = unit.looper
+            # Check for coordinator with _task_scheduler
+            elif hasattr(unit, "_task_scheduler"):
+                looper = unit._task_scheduler  # pylint: disable=protected-access
+            if looper:
+                # Use partial to avoid lambda closure capturing args/kwargs
+                looper.create_task(
+                    target=partial(_async_wrap_sync, _exec_event_callback, *args, **kwargs),
+                    name="wrapper_event_callback",
+                )
+                return
+        except Exception:
+            # Fall through to inline execution on any error
+            pass
+        _exec_event_callback(*args, **kwargs)
+
+    @wraps(func)
+    async def async_wrapper_event_callback(*args: P.args, **kwargs: P.kwargs) -> R:
+        """Wrap async callback events."""
+        return_value = cast(R, await func(*args, **kwargs))  # type: ignore[misc]
+        _schedule_or_exec(*args, **kwargs)
+        return return_value
+
+    @wraps(func)
+    def wrapper_event_callback(*args: P.args, **kwargs: P.kwargs) -> R:
+        """Wrap sync callback events."""
+        return_value = func(*args, **kwargs)
+        _schedule_or_exec(*args, **kwargs)
+        return return_value
+
+    # Helper to create a trivial coroutine from a sync callable
+    async def _async_wrap_sync(cb: CallableNone, *a: Any, **kw: Any) -> None:
+        cb(*a, **kw)
+
+    if inspect.iscoroutinefunction(func):
+        return async_wrapper_event_callback
+    return wrapper_event_callback

aiohomematic/central/device_registry.py

@@ -0,0 +1,229 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Device registry for managing device and channel collections.
+
+This module provides a centralized registry for device management within the central unit.
+It separates device storage concerns from device lifecycle management.
+
+The DeviceRegistry provides:
+- Device storage and lookup by address
+- Channel lookup by channel address
+- Device iteration and filtering
+- Channel identification within text
+- Virtual remote device access
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Final
+
+from aiohomematic.interfaces import CentralInfoProtocol, ChannelProtocol, ClientProviderProtocol, DeviceProtocol
+from aiohomematic.support import get_device_address
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class DeviceRegistry:
+    """Registry for device and channel management."""
+
+    __slots__ = (
+        "_central_info",
+        "_client_provider",
+        "_devices",
+        "_lock",
+    )
+
+    def __init__(
+        self,
+        *,
+        central_info: CentralInfoProtocol,
+        client_provider: ClientProviderProtocol,
+    ) -> None:
+        """
+        Initialize the device registry.
+
+        Args:
+        ----
+            central_info: Provider for central system information
+            client_provider: Provider for client access
+
+        """
+        self._central_info: Final = central_info
+        self._client_provider: Final = client_provider
+        # {device_address, device}
+        self._devices: Final[dict[str, DeviceProtocol]] = {}
+        self._lock: Final = asyncio.Lock()
+
+    @property
+    def device_count(self) -> int:
+        """
+        Return the count of devices in the registry.
+
+        Returns
+        -------
+            Number of devices
+
+        """
+        return len(self._devices)
+
+    @property
+    def devices(self) -> tuple[DeviceProtocol, ...]:
+        """
+        Return all devices as a tuple.
+
+        Returns
+        -------
+            Tuple of all Device instances
+
+        """
+        return tuple(self._devices.values())
+
+    @property
+    def models(self) -> tuple[str, ...]:
+        """
+        Return the models of the devices in the registry.
+
+        Returns
+        -------
+            Models of all devices
+
+        """
+        return tuple(sorted({d.model for d in self.devices}))
+
+    async def add_device(self, *, device: DeviceProtocol) -> None:
+        """
+        Add a device to the registry.
+
+        Args:
+        ----
+            device: Device instance to add
+
+        """
+        async with self._lock:
+            self._devices[device.address] = device
+        _LOGGER.debug(
+            "ADD_DEVICE: Added device %s to registry for %s",
+            device.address,
+            self._central_info.name,
+        )
+
+    async def clear(self) -> None:
+        """Clear all devices from the registry."""
+        async with self._lock:
+            self._devices.clear()
+        _LOGGER.debug("CLEAR: Cleared device registry for %s", self._central_info.name)
+
+    def get_channel(self, *, channel_address: str) -> ChannelProtocol | None:
+        """
+        Get a channel by channel address.
+
+        Args:
+        ----
+            channel_address: Channel address (e.g., "VCU0000001:1")
+
+        Returns:
+        -------
+            Channel instance or None if not found
+
+        """
+        if device := self.get_device(address=channel_address):
+            return device.get_channel(channel_address=channel_address)
+        return None
+
+    def get_device(self, *, address: str) -> DeviceProtocol | None:
+        """
+        Get a device by address.
+
+        Args:
+        ----
+            address: Device address or channel address
+
+        Returns:
+        -------
+            Device instance or None if not found
+
+        """
+        d_address = get_device_address(address=address)
+        return self._devices.get(d_address)
+
+    def get_device_addresses(self) -> frozenset[str]:
+        """
+        Get all device addresses in the registry.
+
+        Returns
+        -------
+            Frozen set of device addresses
+
+        """
+        return frozenset(self._devices.keys())
+
+    def get_virtual_remotes(self) -> tuple[DeviceProtocol, ...]:
+        """
+        Get all virtual remote devices from clients.
+
+        Returns
+        -------
+            Tuple of virtual remote Device instances
+
+        """
+        return tuple(vr for cl in self._client_provider.clients if (vr := cl.get_virtual_remote()) is not None)
+
+    def has_device(self, *, address: str) -> bool:
+        """
+        Check if a device exists in the registry.
+
+        Args:
+        ----
+            address: Device address
+
+        Returns:
+        -------
+            True if device exists, False otherwise
+
+        """
+        return address in self._devices
+
+    def identify_channel(self, *, text: str) -> ChannelProtocol | None:
+        """
+        Identify a channel within a text string.
+
+        Args:
+        ----
+            text: Text to search for channel identification
+
+        Returns:
+        -------
+            Channel instance or None if not found
+
+        """
+        for device in self._devices.values():
+            if channel := device.identify_channel(text=text):
+                return channel
+        return None
+
+    async def remove_device(self, *, device_address: str) -> None:
+        """
+        Remove a device from the registry.
+
+        Args:
+        ----
+            device_address: Address of the device to remove
+
+        """
+        async with self._lock:
+            if device_address not in self._devices:
+                _LOGGER.debug(
+                    "REMOVE_DEVICE: Device %s not found in registry for %s",
+                    device_address,
+                    self._central_info.name,
+                )
+                return
+            del self._devices[device_address]
+        _LOGGER.debug(
+            "REMOVE_DEVICE: Removed device %s from registry for %s",
+            device_address,
+            self._central_info.name,
+        )

aiohomematic/central/events/__init__.py

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Events sub-package for the central event system.
+
+This package contains the event bus infrastructure and event type definitions:
+
+- EventBus: Core event bus for type-safe event subscription and publishing
+- Event types: DataPointValueReceivedEvent, DeviceStateChangedEvent, etc.
+- Integration events: SystemStatusChangedEvent for Home Assistant integration
+
+Public API of this module is defined by __all__.
+"""
+
+from __future__ import annotations
+
+from aiohomematic.central.events.bus import (
+    CacheInvalidatedEvent,
+    ConnectionHealthChangedEvent,
+    ConnectionLostEvent,
+    ConnectionStageChangedEvent,
+    DataPointStateChangedEvent,
+    DataPointStatusReceivedEvent,
+    DataPointValueReceivedEvent,
+    DataRefreshCompletedEvent,
+    DataRefreshTriggeredEvent,
+    DeviceRemovedEvent,
+    DeviceStateChangedEvent,
+    EventBatch,
+    EventBus,
+    FirmwareStateChangedEvent,
+    HandlerStats,
+    HeartbeatTimerFiredEvent,
+    LinkPeerChangedEvent,
+    ProgramExecutedEvent,
+    RecoveryAttemptedEvent,
+    RecoveryCompletedEvent,
+    RecoveryFailedEvent,
+    RecoveryStageChangedEvent,
+    RequestCoalescedEvent,
+    RpcParameterReceivedEvent,
+    SysvarStateChangedEvent,
+)
+from aiohomematic.central.events.integration import (
+    DataPointsCreatedEvent,
+    DeviceLifecycleEvent,
+    DeviceLifecycleEventType,
+    DeviceTriggerEvent,
+    IntegrationIssue,
+    SystemStatusChangedEvent,
+)
+from aiohomematic.central.events.types import (
+    CentralStateChangedEvent,
+    CircuitBreakerStateChangedEvent,
+    CircuitBreakerTrippedEvent,
+    ClientStateChangedEvent,
+    Event,
+    EventPriority,
+    HealthRecordedEvent,
+)
+
+__all__ = [
+    # Event types
+    "CacheInvalidatedEvent",
+    "CentralStateChangedEvent",
+    "CircuitBreakerStateChangedEvent",
+    "CircuitBreakerTrippedEvent",
+    "ClientStateChangedEvent",
+    "ConnectionHealthChangedEvent",
+    "ConnectionLostEvent",
+    "ConnectionStageChangedEvent",
+    "DataPointStateChangedEvent",
+    "DataPointStatusReceivedEvent",
+    "DataPointValueReceivedEvent",
+    "DataRefreshCompletedEvent",
+    "DataRefreshTriggeredEvent",
+    "DeviceRemovedEvent",
+    "DeviceStateChangedEvent",
+    "FirmwareStateChangedEvent",
+    "HealthRecordedEvent",
+    "HeartbeatTimerFiredEvent",
+    "LinkPeerChangedEvent",
+    "ProgramExecutedEvent",
+    "RecoveryAttemptedEvent",
+    "RecoveryCompletedEvent",
+    "RecoveryFailedEvent",
+    "RecoveryStageChangedEvent",
+    "RequestCoalescedEvent",
+    "RpcParameterReceivedEvent",
+    "SysvarStateChangedEvent",
+    # EventBus core
+    "Event",
+    "EventBatch",
+    "EventBus",
+    "EventPriority",
+    "HandlerStats",
+    # Integration events
+    "DataPointsCreatedEvent",
+    "DeviceLifecycleEvent",
+    "DeviceLifecycleEventType",
+    "DeviceTriggerEvent",
+    "IntegrationIssue",
+    "SystemStatusChangedEvent",
+]