aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/async_support.py

@@ -0,0 +1,250 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Async event loop utilities and task management.
+
+Public API of this module is defined by __all__.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Collection
+from concurrent.futures import ThreadPoolExecutor
+from concurrent.futures._base import CancelledError
+import contextlib
+from functools import wraps
+import logging
+from time import monotonic
+from typing import Any, Final, cast
+
+from aiohomematic.const import BLOCK_LOG_TIMEOUT
+from aiohomematic.exceptions import AioHomematicException
+from aiohomematic.interfaces import TaskSchedulerProtocol
+import aiohomematic.support as hms
+from aiohomematic.support import extract_exc_args
+from aiohomematic.type_aliases import AsyncTaskFactoryAny, CallableAny, CoroutineAny
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class Looper(TaskSchedulerProtocol):
+    """Helper class for event loop support."""
+
+    __slots__ = ("_loop_store", "_tasks")
+
+    def __init__(self) -> None:
+        """Initialize the loop helper."""
+        self._tasks: Final[set[asyncio.Future[Any]]] = set()
+        self._loop_store: asyncio.AbstractEventLoop | None = None
+
+    @property
+    def _loop(self) -> asyncio.AbstractEventLoop:
+        """
+        Get the event loop, lazily acquiring it on first use.
+
+        Uses get_running_loop() when called from async context (preferred),
+        falls back to get_event_loop() for cross-thread scheduling scenarios.
+        """
+        if self._loop_store is None:
+            try:
+                self._loop_store = asyncio.get_running_loop()
+            except RuntimeError:
+                # Called from non-async context (e.g., during startup or from another thread)
+                # This path is used by call_soon_threadsafe for cross-thread task scheduling
+                self._loop_store = asyncio.get_event_loop()
+        return self._loop_store
+
+    def async_add_executor_job[T](
+        self,
+        target: Callable[..., T],
+        *args: Any,
+        name: str,
+        executor: ThreadPoolExecutor | None = None,
+    ) -> asyncio.Future[T]:
+        """Add an executor job from within the event_loop."""
+        try:
+            task = self._loop.run_in_executor(executor, target, *args)
+            self._tasks.add(task)
+            task.add_done_callback(self._tasks.remove)
+        except (TimeoutError, CancelledError) as err:  # pragma: no cover
+            message = f"async_add_executor_job: task cancelled for {name} [{extract_exc_args(exc=err)}]"
+            _LOGGER.debug(message)
+            raise AioHomematicException(message) from err
+        return task
+
+    async def block_till_done(self, *, wait_time: float | None = None) -> None:
+        """
+        Block until all pending work is done.
+
+        If wait_time is set, stop waiting after the given number of seconds and log remaining tasks.
+        """
+        # To flush out any call_soon_threadsafe
+        await asyncio.sleep(0)
+        start_time: float | None = None
+        deadline: float | None = (monotonic() + wait_time) if wait_time is not None else None
+        current_task = asyncio.current_task()
+        while tasks := [task for task in self._tasks if task is not current_task and not cancelling(task=task)]:
+            # If we have a deadline and have exceeded it, log remaining tasks and break
+            if deadline is not None and monotonic() >= deadline:
+                for task in tasks:
+                    _LOGGER.warning(  # i18n-log: ignore
+                        "Shutdown timeout reached; task still pending: %s", task
+                    )
+                break
+
+            pending_after_wait = await self._await_and_log_pending(pending=tasks, deadline=deadline)
+
+            # If deadline has been reached and tasks are still pending, log and break
+            if deadline is not None and monotonic() >= deadline and pending_after_wait:
+                for task in pending_after_wait:
+                    _LOGGER.warning(  # i18n-log: ignore
+                        "Shutdown timeout reached; task still pending: %s", task
+                    )
+                break
+
+            if start_time is None:
+                # Avoid calling monotonic() until we know
+                # we may need to start logging blocked tasks.
+                start_time = 0
+            elif start_time == 0:
+                # If we have waited twice then we set the start
+                # time
+                start_time = monotonic()
+            elif monotonic() - start_time > BLOCK_LOG_TIMEOUT:
+                # We have waited at least three loops and new tasks
+                # continue to block. At this point we start
+                # logging all waiting tasks.
+                for task in tasks:
+                    _LOGGER.debug("Waiting for task: %s", task)
+
+    def cancel_tasks(self) -> None:
+        """Cancel running tasks."""
+        for task in self._tasks.copy():
+            if not task.cancelled():
+                task.cancel()
+
+    def create_task(self, *, target: CoroutineAny | AsyncTaskFactoryAny, name: str) -> None:
+        """
+        Schedule a coroutine to run in the loop.
+
+        Accepts either an already-created coroutine object or a zero-argument
+        callable that returns a coroutine. The callable form defers coroutine
+        creation until inside the event loop, which avoids "was never awaited"
+        warnings if callers only inspect the parameters (e.g. in tests).
+        """
+        try:
+            self._loop.call_soon_threadsafe(self._async_create_task, target, name)
+        except CancelledError:
+            # Scheduling failed; if a coroutine object was provided, close it to
+            # avoid 'was never awaited' warnings.
+            if asyncio.iscoroutine(target):
+                with contextlib.suppress(Exception):
+                    getattr(target, "close", lambda: None)()
+            _LOGGER.debug("create_task: task cancelled for %s", name)
+            return
+
+    def run_coroutine(self, *, coro: CoroutineAny, name: str) -> Any:
+        """Call coroutine from sync."""
+        try:
+            return asyncio.run_coroutine_threadsafe(coro, self._loop).result()
+        except CancelledError:  # pragma: no cover
+            _LOGGER.debug(
+                "run_coroutine: coroutine interrupted for %s",
+                name,
+            )
+            return None
+
+    def _async_create_task(  # kwonly: disable
+        self, target: CoroutineAny | AsyncTaskFactoryAny, name: str
+    ) -> asyncio.Task[Any]:
+        """Create a task from within the event loop. Must be run in the event loop."""
+        # If target is a callable, call it here to create the coroutine inside the loop
+        coro: CoroutineAny = target if asyncio.iscoroutine(target) else target()
+        task = self._loop.create_task(coro, name=name)
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.remove)
+        task.add_done_callback(_log_task_exception)
+        return task
+
+    async def _await_and_log_pending(
+        self, *, pending: Collection[asyncio.Future[Any]], deadline: float | None
+    ) -> set[asyncio.Future[Any]]:
+        """
+        Await and log tasks that take a long time, respecting an optional deadline.
+
+        Returns the set of pending tasks if the deadline has been reached (or zero timeout),
+        allowing the caller to decide about timeout logging. Returns an empty set if no tasks are pending.
+        """
+        wait_time = 0.0
+        pending_set: set[asyncio.Future[Any]] = set(pending)
+        while pending_set:
+            if deadline is None:
+                timeout = BLOCK_LOG_TIMEOUT
+            else:
+                remaining = int(max(0.0, deadline - monotonic()))
+                if (timeout := min(BLOCK_LOG_TIMEOUT, remaining)) == 0.0:
+                    # Deadline reached; return current pending to caller for warning log
+                    return pending_set
+            done, still_pending = await asyncio.wait(pending_set, timeout=timeout)
+            if not (pending_set := set(still_pending)):
+                return set()
+            wait_time += timeout
+            for task in pending_set:
+                _LOGGER.debug("Waited %s seconds for task: %s", wait_time, task)
+            # If the deadline was reached during the wait, let caller handle warning
+            if deadline is not None and monotonic() >= deadline:
+                return pending_set
+        return set()
+
+
+def _log_task_exception(task: asyncio.Task[Any]) -> None:  # kwonly: disable
+    """Log unhandled exceptions in background tasks."""
+    if task.cancelled():
+        return
+    if exc := task.exception():
+        _LOGGER.exception(  # i18n-log: ignore
+            "TASK_EXCEPTION: Unhandled exception in task '%s'",
+            task.get_name(),
+            exc_info=exc,
+        )
+
+
+def cancelling(*, task: asyncio.Future[Any]) -> bool:
+    """Return True if task is cancelling."""
+    return bool((cancelling_ := getattr(task, "cancelling", None)) and cancelling_())
+
+
+def loop_check[**P, R](func: Callable[P, R]) -> Callable[P, R]:  # kwonly: disable
+    """
+    Annotation to mark method that must be run within the event loop.
+
+    Always wraps the function, but only performs loop checks when debug is enabled.
+    This allows tests to monkeypatch aiohomematic.support.debug_enabled at runtime.
+    """
+    _with_loop: set[CallableAny] = set()
+
+    @wraps(func)
+    def wrapper_loop_check(*args: P.args, **kwargs: P.kwargs) -> R:
+        """Wrap loop check."""
+        return_value = func(*args, **kwargs)
+
+        # Only perform the (potentially expensive) loop check when debug is enabled.
+        if hms.debug_enabled():
+            try:
+                asyncio.get_running_loop()
+                loop_running = True
+            except Exception:
+                loop_running = False
+
+            if not loop_running and func not in _with_loop:
+                _with_loop.add(func)
+                _LOGGER.error(  # i18n-log: ignore
+                    "Method %s must run in the event_loop. No loop detected.",
+                    func.__name__,
+                )
+
+        return return_value
+
+    setattr(func, "_loop_check", True)
+    return cast(Callable[P, R], wrapper_loop_check)

aiohomematic/backend_detection.py

@@ -0,0 +1,462 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Backend detection module for aiohomematic.
+
+Detect Homematic backend type (CCU or Homegear/PyDevCCU) and discover
+available interfaces without requiring a fully initialized environment.
+
+Public API of this module is defined by __all__.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+import logging
+from typing import Final
+
+from aiohttp import ClientSession
+
+from aiohomematic import i18n
+from aiohomematic.central import CentralConnectionState
+from aiohomematic.client import AioJsonRpcAioHttpClient
+from aiohomematic.client.rpc_proxy import AioXmlRpcProxy
+from aiohomematic.const import (
+    DETECTION_PORT_BIDCOS_RF,
+    DETECTION_PORT_BIDCOS_WIRED,
+    DETECTION_PORT_HMIP_RF,
+    DETECTION_PORT_JSON_RPC,
+    Backend,
+    Interface,
+)
+from aiohomematic.exceptions import AuthFailure, BaseHomematicException, NoConnectionException
+from aiohomematic.support import build_xml_rpc_headers, build_xml_rpc_uri, validate_host
+
+__all__ = [
+    "BackendDetectionResult",
+    "DetectionConfig",
+    "detect_backend",
+]
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+# Detection timeout per request (shorter than normal operation)
+_DETECTION_TIMEOUT: Final = 5.0
+
+# Total detection timeout (max time for entire detection process)
+_DETECTION_TOTAL_TIMEOUT: Final = 15.0
+
+# XML-RPC method names
+_XML_METHOD_GET_VERSION: Final = "getVersion"
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class DetectionConfig:
+    """Configuration for backend detection."""
+
+    host: str
+    username: str = ""
+    password: str = ""
+    request_timeout: float = _DETECTION_TIMEOUT
+    total_timeout: float = _DETECTION_TOTAL_TIMEOUT
+    verify_tls: bool = False
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class BackendDetectionResult:
+    """Result of backend detection."""
+
+    backend: Backend
+    available_interfaces: tuple[Interface, ...]
+    detected_port: int
+    tls: bool
+    host: str
+    version: str | None = None
+    auth_enabled: bool | None = None
+    https_redirect_enabled: bool | None = None
+
+
+async def detect_backend(
+    *,
+    config: DetectionConfig,
+    client_session: ClientSession | None = None,
+) -> BackendDetectionResult | None:
+    """
+    Detect backend type and available interfaces.
+
+    Probe XML-RPC ports to find a working connection, determine if the backend
+    is CCU or Homegear/PyDevCCU, and query available interfaces.
+
+    Args:
+        config: Detection configuration with host and credentials.
+        client_session: Optional aiohttp ClientSession for JSON-RPC requests.
+
+    Returns:
+        BackendDetectionResult if a backend was found, None otherwise.
+
+    Raises:
+        ValidationException: If host format is invalid.
+        AuthFailure: If authentication fails with the provided credentials.
+
+    """
+    # Validate input
+    validate_host(host=config.host)
+
+    _LOGGER.info(
+        i18n.tr(
+            key="log.backend_detection.detect_backend.starting",
+            host=config.host,
+            total_timeout=config.total_timeout,
+        )
+    )
+
+    try:
+        async with asyncio.timeout(config.total_timeout):
+            return await _do_detect_backend(config=config, client_session=client_session)
+    except TimeoutError:
+        _LOGGER.warning(
+            i18n.tr(
+                key="log.backend_detection.detect_backend.total_timeout",
+                host=config.host,
+                total_timeout=config.total_timeout,
+            )
+        )
+        return None
+
+
+async def _do_detect_backend(
+    *,
+    config: DetectionConfig,
+    client_session: ClientSession | None = None,
+) -> BackendDetectionResult | None:
+    """Perform the actual backend detection logic."""
+    # Define ports to probe: (Interface, port, tls)
+    ports_to_probe: list[tuple[Interface, int, bool]] = [
+        # Try non-TLS ports first
+        (Interface.HMIP_RF, DETECTION_PORT_HMIP_RF[0], False),
+        (Interface.BIDCOS_RF, DETECTION_PORT_BIDCOS_RF[0], False),
+        (Interface.BIDCOS_WIRED, DETECTION_PORT_BIDCOS_WIRED[0], False),
+        # Then TLS ports
+        (Interface.HMIP_RF, DETECTION_PORT_HMIP_RF[1], True),
+        (Interface.BIDCOS_RF, DETECTION_PORT_BIDCOS_RF[1], True),
+        (Interface.BIDCOS_WIRED, DETECTION_PORT_BIDCOS_WIRED[1], True),
+    ]
+
+    for interface, port, tls in ports_to_probe:
+        _LOGGER.info(
+            i18n.tr(
+                key="log.backend_detection.detect_backend.probing",
+                host=config.host,
+                port=port,
+                tls=tls,
+                interface=interface,
+            )
+        )
+
+        version = await _probe_xml_rpc_port(
+            host=config.host,
+            port=port,
+            tls=tls,
+            username=config.username,
+            password=config.password,
+            verify_tls=config.verify_tls,
+            request_timeout=config.request_timeout,
+        )
+
+        if version is None:
+            continue
+
+        _LOGGER.info(i18n.tr(key="log.backend_detection.detect_backend.found_version", version=version, port=port))
+
+        # Determine backend type from version string
+        backend = _determine_backend(version=version)
+        _LOGGER.info(i18n.tr(key="log.backend_detection.detect_backend.backend_type", backend=backend))
+
+        if backend in (Backend.HOMEGEAR, Backend.PYDEVCCU):
+            # Homegear/PyDevCCU only supports BidCos-RF
+            return BackendDetectionResult(
+                backend=backend,
+                available_interfaces=(Interface.BIDCOS_RF,),
+                detected_port=port,
+                tls=tls,
+                host=config.host,
+                version=version,
+                auth_enabled=None,
+            )
+
+        # CCU: Query JSON-RPC for available interfaces
+        # This may raise AuthFailure if authentication fails
+        interfaces, auth_enabled, https_redirect_enabled = await _query_ccu_interfaces(
+            host=config.host,
+            username=config.username,
+            password=config.password,
+            verify_tls=config.verify_tls,
+            client_session=client_session,
+        )
+
+        if interfaces:
+            _LOGGER.info(i18n.tr(key="log.backend_detection.detect_backend.found_interfaces", interfaces=interfaces))
+        else:
+            # Fallback: use the interface we connected to
+            _LOGGER.info(i18n.tr(key="log.backend_detection.detect_backend.json_rpc_fallback"))
+            interfaces = (interface,)
+
+        return BackendDetectionResult(
+            backend=Backend.CCU,
+            available_interfaces=interfaces,
+            detected_port=port,
+            tls=tls,
+            host=config.host,
+            version=version,
+            auth_enabled=auth_enabled,
+            https_redirect_enabled=https_redirect_enabled,
+        )
+
+    _LOGGER.info(i18n.tr(key="log.backend_detection.detect_backend.no_backend_found", host=config.host))
+    return None
+
+
+def _determine_backend(*, version: str) -> Backend:
+    """Determine backend type from version string."""
+    version_lower = version.lower()
+    if "homegear" in version_lower:
+        return Backend.HOMEGEAR
+    if "pydevccu" in version_lower:
+        return Backend.PYDEVCCU
+    return Backend.CCU
+
+
+async def _probe_xml_rpc_port(
+    *,
+    host: str,
+    port: int,
+    tls: bool,
+    username: str,
+    password: str,
+    verify_tls: bool,
+    request_timeout: float,
+) -> str | None:
+    """
+    Probe a single XML-RPC port and return the version string if successful.
+
+    Uses AioXmlRpcProxy for consistent error handling with the rest of the client.
+
+    Returns:
+        Version string if connection successful, None otherwise.
+
+    Raises:
+        AuthFailure: If authentication fails with the provided credentials.
+
+    """
+    uri = build_xml_rpc_uri(host=host, port=port, path=None, tls=tls)
+    headers = build_xml_rpc_headers(username=username, password=password) if username else []
+    interface_id = f"detect-{host}:{port}"
+
+    proxy: AioXmlRpcProxy | None = None
+    try:
+        proxy = AioXmlRpcProxy(
+            max_workers=1,
+            interface_id=interface_id,
+            connection_state=CentralConnectionState(),
+            uri=uri,
+            headers=headers,
+            tls=tls,
+            verify_tls=verify_tls,
+        )
+
+        # Initialize proxy and get supported methods
+        await asyncio.wait_for(proxy.do_init(), timeout=request_timeout)
+
+        # Try to get version if available
+        if _XML_METHOD_GET_VERSION in (proxy.supported_methods or ()):
+            version = await asyncio.wait_for(proxy.getVersion(), timeout=request_timeout)
+            return str(version) if version else ""
+        # If getVersion not available, return empty string to indicate connection worked
+        return ""  # noqa: TRY300
+
+    except AuthFailure:
+        # Re-raise authentication failures - wrong credentials should not try other ports
+        raise
+    except NoConnectionException as exc:
+        # Connection failed on this port - log and try next port
+        _LOGGER.info(
+            i18n.tr(
+                key="log.backend_detection.xml_rpc.probe_failed",
+                host=host,
+                port=port,
+                exc_type=type(exc).__name__,
+                reason=exc,
+            )
+        )
+        return None
+    except TimeoutError:
+        _LOGGER.info(i18n.tr(key="log.backend_detection.xml_rpc.probe_timeout", host=host, port=port))
+        return None
+    except BaseHomematicException as exc:
+        _LOGGER.info(
+            i18n.tr(
+                key="log.backend_detection.xml_rpc.probe_failed",
+                host=host,
+                port=port,
+                exc_type=type(exc).__name__,
+                reason=exc,
+            )
+        )
+        return None
+    except Exception as exc:  # noqa: BLE001
+        _LOGGER.info(
+            i18n.tr(
+                key="log.backend_detection.xml_rpc.probe_error",
+                host=host,
+                port=port,
+                exc_type=type(exc).__name__,
+                reason=exc,
+            )
+        )
+        return None
+    finally:
+        if proxy:
+            await proxy.stop()
+
+
+async def _query_ccu_interfaces(
+    *,
+    host: str,
+    username: str,
+    password: str,
+    verify_tls: bool,
+    client_session: ClientSession | None,
+) -> tuple[tuple[Interface, ...], bool | None, bool | None]:
+    """
+    Query CCU for available interfaces via JSON-RPC.
+
+    Uses AioJsonRpcAioHttpClient to query system information.
+    Tries both HTTP (port 80) and HTTPS (port 443).
+
+    Returns:
+        Tuple of (interfaces, auth_enabled, https_redirect_enabled).
+        Returns empty tuple if query fails.
+
+    Raises:
+        AuthFailure: If authentication fails with the provided credentials.
+
+    """
+    for port, tls in DETECTION_PORT_JSON_RPC:
+        result = await _query_json_rpc_interfaces(
+            host=host,
+            port=port,
+            tls=tls,
+            username=username,
+            password=password,
+            verify_tls=verify_tls,
+            client_session=client_session,
+        )
+        if result is not None:
+            return result
+
+    return ((), None, None)
+
+
+async def _query_json_rpc_interfaces(
+    *,
+    host: str,
+    port: int,
+    tls: bool,
+    username: str,
+    password: str,
+    verify_tls: bool,
+    client_session: ClientSession | None,
+) -> tuple[tuple[Interface, ...], bool | None, bool | None] | None:
+    """
+    Query interfaces via JSON-RPC on a specific port using AioJsonRpcAioHttpClient.
+
+    This function performs two checks:
+    1. Queries available_interfaces from system information (installed interfaces)
+    2. Verifies each interface is actually running via is_present() check
+
+    Returns:
+        Tuple of (interfaces, auth_enabled, https_redirect_enabled) if successful, None if failed.
+
+    Raises:
+        AuthFailure: If authentication fails with the provided credentials.
+
+    """
+    scheme = "https" if tls else "http"
+    device_url = f"{scheme}://{host}:{port}"
+
+    _LOGGER.info(i18n.tr(key="log.backend_detection.json_rpc.querying", url=device_url))
+
+    json_rpc_client: AioJsonRpcAioHttpClient | None = None
+    try:
+        json_rpc_client = AioJsonRpcAioHttpClient(
+            username=username,
+            password=password,
+            device_url=device_url,
+            connection_state=CentralConnectionState(),
+            client_session=client_session,
+            tls=tls,
+            verify_tls=verify_tls,
+        )
+
+        system_info = await json_rpc_client.get_system_information()
+
+        # Convert interface strings to Interface enums
+        installed_interfaces: list[Interface] = []
+        for iface_name in system_info.available_interfaces:
+            try:
+                installed_interfaces.append(Interface(iface_name))
+            except ValueError:
+                _LOGGER.info(i18n.tr(key="log.backend_detection.json_rpc.unknown_interface", interface=iface_name))
+
+        # Verify each interface is actually running via is_present check
+        present_interfaces: list[Interface] = []
+        for interface in installed_interfaces:
+            try:
+                if await json_rpc_client.is_present(interface=interface):
+                    present_interfaces.append(interface)
+                    _LOGGER.debug(
+                        i18n.tr(
+                            key="log.backend_detection.json_rpc.interface_present",
+                            interface=interface.value,
+                        )
+                    )
+                else:
+                    _LOGGER.warning(
+                        i18n.tr(
+                            key="log.backend_detection.json_rpc.interface_not_present",
+                            interface=interface.value,
+                        )
+                    )
+            except Exception as exc:  # noqa: BLE001
+                _LOGGER.warning(
+                    i18n.tr(
+                        key="log.backend_detection.json_rpc.is_present_failed",
+                        interface=interface.value,
+                        reason=str(exc),
+                    )
+                )
+
+        return tuple(present_interfaces), system_info.auth_enabled, system_info.https_redirect_enabled  # noqa: TRY300
+
+    except AuthFailure:
+        # Re-raise authentication failures so they can be handled by the caller
+        _LOGGER.warning(i18n.tr(key="log.backend_detection.json_rpc.auth_failed", url=device_url))
+        raise
+    except NoConnectionException:
+        # Connection failed on this port - log and try next port
+        _LOGGER.info(i18n.tr(key="log.backend_detection.json_rpc.connection_failed", url=device_url))
+        return None
+    except Exception as exc:  # noqa: BLE001
+        _LOGGER.info(
+            i18n.tr(
+                key="log.backend_detection.json_rpc.query_failed",
+                url=device_url,
+                exc_type=type(exc).__name__,
+                reason=exc,
+            )
+        )
+        return None
+    finally:
+        if json_rpc_client:
+            await json_rpc_client.logout()