aiohomematic 2025.11.3__py3-none-any.whl

aiohomematic/central/decorators.py

@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""Decorators for central used within aiohomematic."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from datetime import datetime
+from functools import wraps
+import inspect
+import logging
+from typing import Any, Final, cast
+
+from aiohomematic import central as hmcu, client as hmcl
+from aiohomematic.central import rpc_server as rpc
+from aiohomematic.const import BackendSystemEvent
+from aiohomematic.exceptions import AioHomematicException
+from aiohomematic.support import extract_exc_args
+
+_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: BackendSystemEvent) -> Callable:
+    """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]
+                central: hmcu.CentralUnit | None = None
+                if isinstance(unit, hmcu.CentralUnit):
+                    central = unit
+                if central is None and isinstance(unit, rpc.RPCFunctions):
+                    central = unit.get_central(interface_id=str(args[1]))
+                if central:
+                    central.looper.create_task(
+                        target=lambda: _exec_backend_system_callback(*args, **kwargs),
+                        name="wrapper_backend_system_callback",
+                    )
+            except Exception as exc:
+                _LOGGER.warning(
+                    "EXEC_BACKEND_SYSTEM_CALLBACK failed: Problem with identifying central: %s",
+                    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.warning("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.emit_backend_system_callback(system_event=system_event, **kwargs)
+            except Exception as exc:  # pragma: no cover
+                _LOGGER.warning(
+                    "EXEC_BACKEND_SYSTEM_CALLBACK failed: Unable to reduce kwargs for backend_system_callback"
+                )
+                raise AioHomematicException(
+                    f"args-exception backend_system_callback [{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:
+    """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.emit_backend_parameter_callback(
+                    interface_id=interface_id, channel_address=channel_address, parameter=parameter, value=value
+                )
+        except Exception as exc:  # pragma: no cover
+            _LOGGER.warning("EXEC_DATA_POINT_EVENT_CALLBACK failed: Unable to process args/kwargs for event_callback")
+            raise AioHomematicException(f"args-exception event_callback [{extract_exc_args(exc=exc)}]") from exc
+
+    def _schedule_or_exec(*args: Any, **kwargs: Any) -> None:
+        """Schedule event callback on central looper when possible, else execute inline."""
+        try:
+            # Prefer scheduling on the CentralUnit looper when available to avoid blocking hot path
+            unit = args[0]
+            if isinstance(unit, hmcu.CentralUnit):
+                unit.looper.create_task(
+                    target=lambda: _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: Callable[..., None], *a: Any, **kw: Any) -> None:
+        cb(*a, **kw)
+
+    if inspect.iscoroutinefunction(func):
+        return async_wrapper_event_callback
+    return wrapper_event_callback

aiohomematic/central/rpc_server.py

@@ -0,0 +1,295 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""
+XML-RPC server module.
+
+Provides the XML-RPC server which handles communication
+with the backend.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import threading
+from typing import Any, Final, cast
+from xmlrpc.server import SimpleXMLRPCRequestHandler, SimpleXMLRPCServer
+
+from aiohomematic import central as hmcu
+from aiohomematic.central.decorators import callback_backend_system
+from aiohomematic.const import IP_ANY_V4, PORT_ANY, BackendSystemEvent
+from aiohomematic.support import log_boundary_error
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+# pylint: disable=invalid-name
+class RPCFunctions:
+    """The RPC functions the backend will expect."""
+
+    # Disable kw-only linter
+    __kwonly_check__ = False
+
+    def __init__(self, *, rpc_server: RpcServer) -> None:
+        """Init RPCFunctions."""
+        self._rpc_server: Final = rpc_server
+
+    def event(self, interface_id: str, channel_address: str, parameter: str, value: Any, /) -> None:
+        """If a device emits some sort event, we will handle it here."""
+        if central := self.get_central(interface_id=interface_id):
+            central.looper.create_task(
+                target=central.data_point_event(
+                    interface_id=interface_id,
+                    channel_address=channel_address,
+                    parameter=parameter,
+                    value=value,
+                ),
+                name=f"event-{interface_id}-{channel_address}-{parameter}",
+            )
+
+    @callback_backend_system(system_event=BackendSystemEvent.ERROR)
+    def error(self, interface_id: str, error_code: str, msg: str, /) -> None:
+        """When some error occurs the backend will send its error message here."""
+        # Structured boundary log (warning level). RPC server received error notification.
+        try:
+            raise RuntimeError(str(msg))
+        except RuntimeError as err:
+            log_boundary_error(
+                logger=_LOGGER,
+                boundary="rpc-server",
+                action="error",
+                err=err,
+                level=logging.WARNING,
+                log_context={"interface_id": interface_id, "error_code": int(error_code)},
+            )
+        _LOGGER.warning(
+            "ERROR failed: interface_id = %s, error_code = %i, message = %s",
+            interface_id,
+            int(error_code),
+            str(msg),
+        )
+
+    def listDevices(self, interface_id: str, /) -> list[dict[str, Any]]:
+        """Return already existing devices to the backend."""
+        if central := self.get_central(interface_id=interface_id):
+            return [dict(device_description) for device_description in central.list_devices(interface_id=interface_id)]
+        return []
+
+    def newDevices(self, interface_id: str, device_descriptions: list[dict[str, Any]], /) -> None:
+        """Add new devices send from the backend."""
+        central: hmcu.CentralUnit | None
+        if central := self.get_central(interface_id=interface_id):
+            central.looper.create_task(
+                target=central.add_new_devices(
+                    interface_id=interface_id, device_descriptions=tuple(device_descriptions)
+                ),
+                name=f"newDevices-{interface_id}",
+            )
+
+    def deleteDevices(self, interface_id: str, addresses: list[str], /) -> None:
+        """Delete devices send from the backend."""
+        central: hmcu.CentralUnit | None
+        if central := self.get_central(interface_id=interface_id):
+            central.looper.create_task(
+                target=central.delete_devices(interface_id=interface_id, addresses=tuple(addresses)),
+                name=f"deleteDevices-{interface_id}",
+            )
+
+    @callback_backend_system(system_event=BackendSystemEvent.UPDATE_DEVICE)
+    def updateDevice(self, interface_id: str, address: str, hint: int, /) -> None:
+        """
+        Update a device.
+
+        Irrelevant, as currently only changes to link
+        partners are reported.
+        """
+        _LOGGER.debug(
+            "UPDATEDEVICE: interface_id = %s, address = %s, hint = %s",
+            interface_id,
+            address,
+            str(hint),
+        )
+
+    @callback_backend_system(system_event=BackendSystemEvent.REPLACE_DEVICE)
+    def replaceDevice(self, interface_id: str, old_device_address: str, new_device_address: str, /) -> None:
+        """Replace a device. Probably irrelevant for us."""
+        _LOGGER.debug(
+            "REPLACEDEVICE: interface_id = %s, oldDeviceAddress = %s, newDeviceAddress = %s",
+            interface_id,
+            old_device_address,
+            new_device_address,
+        )
+
+    @callback_backend_system(system_event=BackendSystemEvent.RE_ADDED_DEVICE)
+    def readdedDevice(self, interface_id: str, addresses: list[str], /) -> None:
+        """
+        Re-Add device from the backend.
+
+        Probably irrelevant for us.
+        Gets called when a known devices is put into learn-mode
+        while installation mode is active.
+        """
+        _LOGGER.debug(
+            "READDEDDEVICES: interface_id = %s, addresses = %s",
+            interface_id,
+            str(addresses),
+        )
+
+    def get_central(self, *, interface_id: str) -> hmcu.CentralUnit | None:
+        """Return the central by interface_id."""
+        return self._rpc_server.get_central(interface_id=interface_id)
+
+
+# Restrict to specific paths.
+class RequestHandler(SimpleXMLRPCRequestHandler):
+    """We handle requests to / and /RPC2."""
+
+    rpc_paths = (
+        "/",
+        "/RPC2",
+    )
+
+
+class HomematicXMLRPCServer(SimpleXMLRPCServer):
+    """
+    Simple XML-RPC server.
+
+    Simple XML-RPC server that allows functions and a single instance
+    to be installed to handle requests. The default implementation
+    attempts to dispatch XML-RPC calls to the functions or instance
+    installed in the server. Override the _dispatch method inherited
+    from SimpleXMLRPCDispatcher to change this behavior.
+
+    This implementation adds an additional method:
+    system_listMethods(self, interface_id: str.
+    """
+
+    __kwonly_check__ = False
+
+    def system_listMethods(self, interface_id: str | None = None, /) -> list[str]:
+        """Return a list of the methods supported by the server."""
+        return SimpleXMLRPCServer.system_listMethods(self)
+
+
+class RpcServer(threading.Thread):
+    """RPC server thread to handle messages from the backend."""
+
+    _initialized: bool = False
+    _instances: Final[dict[tuple[str, int], RpcServer]] = {}
+
+    def __init__(self, *, server: SimpleXMLRPCServer) -> None:
+        """Init XmlRPC server."""
+        self._server = server
+        self._server.register_introspection_functions()
+        self._server.register_multicall_functions()
+        self._server.register_instance(RPCFunctions(rpc_server=self), allow_dotted_names=True)
+        self._initialized = True
+        self._address: Final[tuple[str, int]] = cast(tuple[str, int], server.server_address)
+        self._listen_ip_addr: Final = self._address[0]
+        self._listen_port: Final = self._address[1]
+        self._centrals: Final[dict[str, hmcu.CentralUnit]] = {}
+        self._instances[self._address] = self
+        threading.Thread.__init__(self, name=f"RpcServer {self._listen_ip_addr}:{self._listen_port}")
+
+    def run(self) -> None:
+        """Run the RPC-Server thread."""
+        _LOGGER.debug(
+            "RUN: Starting RPC-Server listening on %s:%i",
+            self._listen_ip_addr,
+            self._listen_port,
+        )
+        if self._server:
+            self._server.serve_forever()
+
+    def stop(self) -> None:
+        """Stop the RPC-Server."""
+        _LOGGER.debug("STOP: Shutting down RPC-Server")
+        self._server.shutdown()
+        _LOGGER.debug("STOP: Stopping RPC-Server")
+        self._server.server_close()
+        # Ensure the server thread has actually terminated to avoid slow teardown
+        with contextlib.suppress(RuntimeError):
+            self.join(timeout=1.0)
+        _LOGGER.debug("STOP: RPC-Server stopped")
+        if self._address in self._instances:
+            del self._instances[self._address]
+
+    @property
+    def listen_ip_addr(self) -> str:
+        """Return the local ip address."""
+        return self._listen_ip_addr
+
+    @property
+    def listen_port(self) -> int:
+        """Return the local port."""
+        return self._listen_port
+
+    @property
+    def started(self) -> bool:
+        """Return if thread is active."""
+        return self._started.is_set() is True  # type: ignore[attr-defined]
+
+    def add_central(self, *, central: hmcu.CentralUnit) -> None:
+        """Register a central in the RPC-Server."""
+        if not self._centrals.get(central.name):
+            self._centrals[central.name] = central
+
+    def remove_central(self, *, central: hmcu.CentralUnit) -> None:
+        """Unregister a central from RPC-Server."""
+        if self._centrals.get(central.name):
+            del self._centrals[central.name]
+
+    def get_central(self, *, interface_id: str) -> hmcu.CentralUnit | None:
+        """Return a central by interface_id."""
+        for central in self._centrals.values():
+            if central.has_client(interface_id=interface_id):
+                return central
+        return None
+
+    @property
+    def no_central_assigned(self) -> bool:
+        """Return if no central is assigned."""
+        return len(self._centrals) == 0
+
+
+class XmlRpcServer(RpcServer):
+    """XML-RPC server thread to handle messages from the backend."""
+
+    def __init__(
+        self,
+        *,
+        ip_addr: str,
+        port: int,
+    ) -> None:
+        """Init XmlRPC server."""
+
+        if self._initialized:
+            return
+        super().__init__(
+            server=HomematicXMLRPCServer(
+                addr=(ip_addr, port),
+                requestHandler=RequestHandler,
+                logRequests=False,
+                allow_none=True,
+            )
+        )
+
+    def __new__(cls, ip_addr: str, port: int) -> XmlRpcServer:  # noqa: PYI034  # kwonly: disable
+        """Create new RPC server."""
+        if (rpc := cls._instances.get((ip_addr, port))) is None:
+            _LOGGER.debug("Creating XmlRpc server")
+            return super().__new__(cls)
+        return cast(XmlRpcServer, rpc)
+
+
+def create_xml_rpc_server(*, ip_addr: str = IP_ANY_V4, port: int = PORT_ANY) -> XmlRpcServer:
+    """Register the rpc server."""
+    rpc = XmlRpcServer(ip_addr=ip_addr, port=port)
+    if not rpc.started:
+        rpc.start()
+        _LOGGER.debug(
+            "CREATE_XML_RPC_SERVER: Starting XmlRPC-Server listening on %s:%i",
+            rpc.listen_ip_addr,
+            rpc.listen_port,
+        )
+    return rpc