aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/decorators.py

@@ -0,0 +1,390 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Common Decorators used within aiohomematic.
+
+Public API of this module is defined by __all__.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import wraps
+import inspect
+import logging
+from time import monotonic
+from typing import Any, Final, cast, overload
+from weakref import WeakKeyDictionary
+
+from aiohomematic.const import ServiceScope
+from aiohomematic.context import RequestContext, is_in_service, reset_request_context, set_request_context
+from aiohomematic.exceptions import BaseHomematicException
+from aiohomematic.metrics import MetricKeys, emit_counter, emit_latency
+from aiohomematic.support import LogContextMixin, log_boundary_error
+from aiohomematic.type_aliases import CallableAny, ServiceMethodMap
+
+_LOGGER_PERFORMANCE: Final = logging.getLogger(f"{__package__}.performance")
+
+# Cache for per-class service call method names to avoid repeated scans.
+# Structure: {cls: (method_name1, method_name2, ...)}
+_SERVICE_CALLS_CACHE: WeakKeyDictionary[type, tuple[str, ...]] = WeakKeyDictionary()
+
+
+@overload
+def inspector[**P, R](  # kwonly: disable
+    func: Callable[P, R],
+    /,
+    *,
+    log_level: int = ...,
+    re_raise: bool = ...,
+    no_raise_return: Any = ...,
+    measure_performance: bool = ...,
+    scope: ServiceScope = ...,
+) -> Callable[P, R]: ...
+
+
+@overload
+def inspector[**P, R](  # kwonly: disable
+    func: None = ...,
+    /,
+    *,
+    log_level: int = ...,
+    re_raise: bool = ...,
+    no_raise_return: Any = ...,
+    measure_performance: bool = ...,
+    scope: ServiceScope = ...,
+) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+
+
+def inspector[**P, R](  # noqa: C901, kwonly: disable
+    func: Callable[P, R] | None = None,
+    /,
+    *,
+    log_level: int = logging.ERROR,
+    re_raise: bool = True,
+    no_raise_return: Any = None,
+    measure_performance: bool = False,
+    scope: ServiceScope = ServiceScope.EXTERNAL,
+) -> Callable[[Callable[P, R]], Callable[P, R]] | Callable[P, R]:
+    """
+    Support with exception handling and performance measurement.
+
+    A decorator that works for both synchronous and asynchronous functions,
+    providing common functionality such as exception handling and performance measurement.
+
+    Can be used both with and without parameters:
+      - @inspector
+      - @inspector(log_level=logging.ERROR, re_raise=True, ...)
+      - @inspector(scope=ServiceScope.INTERNAL)
+
+    Args:
+        func: The function to decorate when used without parameters.
+        log_level: Logging level for exceptions.
+        re_raise: Whether to re-raise exceptions.
+        no_raise_return: Value to return when an exception is caught and not re-raised.
+        measure_performance: Whether to measure function execution time.
+        scope: The scope of this service method (see ServiceScope enum).
+            EXTERNAL: Methods for external consumers (HA) - user-invokable commands
+                like turn_on, turn_off, set_temperature. Appears in service_method_names.
+            INTERNAL: Infrastructure methods for library operation like
+                load_data_point_value, fetch_*_data. Does NOT appear in service_method_names.
+
+    Returns:
+        Either the decorated function (when used without parameters) or
+        a decorator that wraps sync or async functions (when used with parameters).
+
+    """
+
+    def create_wrapped_decorator(func: Callable[P, R]) -> Callable[P, R]:  # noqa: C901
+        """
+        Decorate function for wrapping sync or async functions.
+
+        Args:
+            func: The function to decorate.
+
+        Returns:
+            The decorated function.
+
+        """
+
+        def handle_exception(
+            exc: Exception,
+            func: CallableAny,
+            is_sub_service_call: bool,
+            is_homematic: bool,
+            context_obj: Any | None,
+        ) -> R:
+            """Handle exceptions for decorated functions with structured logging."""
+            if not is_sub_service_call and log_level > logging.NOTSET:
+                logger = logging.getLogger(func.__module__)
+                log_context = context_obj.log_context if isinstance(context_obj, LogContextMixin) else None
+                # Reuse centralized boundary logging to ensure consistent 'extra' structure
+                log_boundary_error(
+                    logger=logger,
+                    boundary="service",
+                    action=func.__name__,
+                    err=exc,
+                    level=log_level,
+                    log_context=log_context,
+                )
+            if re_raise or not is_homematic:
+                raise exc
+            return cast(R, no_raise_return)
+
+        @wraps(func)
+        def wrap_sync_function(*args: P.args, **kwargs: P.kwargs) -> R:
+            """Wrap sync functions with minimized per-call overhead."""
+            # Start timing if measure_performance is enabled (for metrics and/or logging)
+            start = monotonic() if measure_performance else None
+            had_error = False
+
+            # Check if already in a service call context
+            in_service = is_in_service()
+            token = None
+            if not in_service:
+                # Create new request context for this service call
+                ctx = RequestContext(operation=f"service:{func.__name__}")
+                token = set_request_context(ctx=ctx)
+            context_obj = args[0] if args else None
+            try:
+                return_value: R = func(*args, **kwargs)
+            except BaseHomematicException as bhexc:
+                had_error = True
+                if token is not None:
+                    reset_request_context(token=token)
+                return handle_exception(
+                    exc=bhexc,
+                    func=func,
+                    is_sub_service_call=in_service,
+                    is_homematic=True,
+                    context_obj=context_obj,
+                )
+            except Exception as exc:
+                had_error = True
+                if token is not None:
+                    reset_request_context(token=token)
+                return handle_exception(
+                    exc=exc,
+                    func=func,
+                    is_sub_service_call=in_service,
+                    is_homematic=False,
+                    context_obj=context_obj,
+                )
+            else:
+                if token is not None:
+                    reset_request_context(token=token)
+                return return_value
+            finally:
+                if start is not None:
+                    duration_ms = (monotonic() - start) * 1000
+                    # Emit service call metrics if event_bus is available
+                    _emit_service_metrics(
+                        context_obj=context_obj,
+                        method_name=func.__name__,
+                        duration_ms=duration_ms,
+                        had_error=had_error,
+                    )
+                    # Log performance if debug logging is enabled
+                    if _LOGGER_PERFORMANCE.isEnabledFor(level=logging.DEBUG):
+                        _log_performance_message(func, start, *args, **kwargs)
+
+        @wraps(func)
+        async def wrap_async_function(*args: P.args, **kwargs: P.kwargs) -> R:
+            """Wrap async functions with minimized per-call overhead."""
+            # Start timing if measure_performance is enabled (for metrics and/or logging)
+            start = monotonic() if measure_performance else None
+            had_error = False
+
+            # Check if already in a service call context
+            in_service = is_in_service()
+            token = None
+            if not in_service:
+                # Create new request context for this service call
+                ctx = RequestContext(operation=f"service:{func.__name__}")
+                token = set_request_context(ctx=ctx)
+            context_obj = args[0] if args else None
+            try:
+                return_value = await func(*args, **kwargs)  # type: ignore[misc]
+            except BaseHomematicException as bhexc:
+                had_error = True
+                if token is not None:
+                    reset_request_context(token=token)
+                return handle_exception(
+                    exc=bhexc,
+                    func=func,
+                    is_sub_service_call=in_service,
+                    is_homematic=True,
+                    context_obj=context_obj,
+                )
+            except Exception as exc:
+                had_error = True
+                if token is not None:
+                    reset_request_context(token=token)
+                return handle_exception(
+                    exc=exc,
+                    func=func,
+                    is_sub_service_call=in_service,
+                    is_homematic=False,
+                    context_obj=context_obj,
+                )
+            else:
+                if token is not None:
+                    reset_request_context(token=token)
+                return cast(R, return_value)
+            finally:
+                if start is not None:
+                    duration_ms = (monotonic() - start) * 1000
+                    # Emit service call metrics if event_bus is available
+                    _emit_service_metrics(
+                        context_obj=context_obj,
+                        method_name=func.__name__,
+                        duration_ms=duration_ms,
+                        had_error=had_error,
+                    )
+                    # Log performance if debug logging is enabled
+                    if _LOGGER_PERFORMANCE.isEnabledFor(level=logging.DEBUG):
+                        _log_performance_message(func, start, *args, **kwargs)
+
+        # Check if the function is a coroutine or not and select the appropriate wrapper
+        is_external = scope == ServiceScope.EXTERNAL
+        if inspect.iscoroutinefunction(func):
+            if is_external:
+                setattr(wrap_async_function, "lib_service", True)
+            return wrap_async_function  # type: ignore[return-value]
+        if is_external:
+            setattr(wrap_sync_function, "lib_service", True)
+        return wrap_sync_function
+
+    # If used without parameters: @inspector
+    if func is not None:
+        return create_wrapped_decorator(func)
+
+    # If used with parameters: @inspector(...)
+    return create_wrapped_decorator
+
+
+def _emit_service_metrics(
+    *,
+    context_obj: Any,
+    method_name: str,
+    duration_ms: float,
+    had_error: bool,
+) -> None:
+    """
+    Emit service call metrics via EventBus if available.
+
+    Args:
+        context_obj: The object the method was called on (first arg)
+        method_name: Name of the service method
+        duration_ms: Execution duration in milliseconds
+        had_error: Whether the call raised an exception
+
+    """
+    # Get event_bus from context object if available
+    if (event_bus_provider := getattr(context_obj, "_event_bus_provider", None)) is None:
+        return
+
+    if (event_bus := getattr(event_bus_provider, "event_bus", None)) is None:
+        return
+
+    # Emit latency for all calls
+    emit_latency(
+        event_bus=event_bus,
+        key=MetricKeys.service_call(method=method_name),
+        duration_ms=duration_ms,
+    )
+
+    # Emit error counter if there was an error
+    if had_error:
+        emit_counter(
+            event_bus=event_bus,
+            key=MetricKeys.service_error(method=method_name),
+        )
+
+
+def _log_performance_message[**P](func: Callable[P, Any], start: float, *args: P.args, **kwargs: P.kwargs) -> None:
+    delta = monotonic() - start
+    caller = str(args[0]) if len(args) > 0 else ""
+
+    iface: str = ""
+    if interface := str(kwargs.get("interface", "")):
+        iface = f"interface: {interface}"
+    if interface_id := kwargs.get("interface_id", ""):
+        iface = f"interface_id: {interface_id}"
+
+    message = f"Execution of {func.__name__.upper()} took {delta}s from {caller}"
+    if iface:
+        message += f"/{iface}"
+
+    _LOGGER_PERFORMANCE.info(message)
+
+
+def get_service_calls(*, obj: object) -> ServiceMethodMap:
+    """
+    Get all methods decorated with the service decorator (lib_service attribute).
+
+    To reduce overhead, we cache the discovered method names per class using a WeakKeyDictionary.
+    """
+    cls = obj.__class__
+
+    # Try cache first
+    if (names := _SERVICE_CALLS_CACHE.get(cls)) is None:
+        # Compute method names using class attributes to avoid creating bound methods during checks
+        exclusions = {"service_methods", "service_method_names"}
+        computed: list[str] = []
+        for name in dir(cls):
+            if name.startswith("_") or name in exclusions:
+                continue
+            try:
+                # Check the attribute on the class (function/descriptor)
+                attr = getattr(cls, name)
+            except Exception:
+                continue
+            # Only consider callables exposed on the instance and marked with lib_service on the function/wrapper
+            if callable(getattr(obj, name, None)) and hasattr(attr, "lib_service"):
+                computed.append(name)
+        names = tuple(computed)
+        _SERVICE_CALLS_CACHE[cls] = names
+
+    # Return a mapping of bound methods for this instance
+    return {name: getattr(obj, name) for name in names}
+
+
+def measure_execution_time[CallableT: CallableAny](func: CallableT) -> CallableT:  # kwonly: disable
+    """Decorate function to measure the function execution time."""
+
+    @wraps(func)
+    async def async_measure_wrapper(*args: Any, **kwargs: Any) -> Any:
+        """Wrap method."""
+        start = monotonic() if _LOGGER_PERFORMANCE.isEnabledFor(level=logging.DEBUG) else None
+        try:
+            return await func(*args, **kwargs)
+        finally:
+            if start:
+                _log_performance_message(func, start, *args, **kwargs)
+
+    @wraps(func)
+    def measure_wrapper(*args: Any, **kwargs: Any) -> Any:
+        """Wrap method."""
+        start = monotonic() if _LOGGER_PERFORMANCE.isEnabledFor(level=logging.DEBUG) else None
+        try:
+            return func(*args, **kwargs)
+        finally:
+            if start:
+                _log_performance_message(func, start, *args, **kwargs)
+
+    if inspect.iscoroutinefunction(func):
+        return cast(CallableT, async_measure_wrapper)
+    return cast(CallableT, measure_wrapper)
+
+
+# Define public API for this module
+__all__ = tuple(
+    sorted(
+        name
+        for name, obj in globals().items()
+        if not name.startswith("_")
+        and (inspect.isfunction(obj) or inspect.isclass(obj))
+        and getattr(obj, "__module__", __name__) == __name__
+    )
+)

aiohomematic/exceptions.py

@@ -0,0 +1,185 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Module for AioHomematicExceptions.
+
+Public API of this module is defined by __all__.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from functools import wraps
+import inspect
+import logging
+from typing import Any, Final, cast
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class BaseHomematicException(Exception):
+    """aiohomematic base exception."""
+
+    def __init__(self, name: str, *args: Any) -> None:
+        """Initialize the AioHomematicException."""
+        if args and isinstance(args[0], BaseException):
+            self.name = args[0].__class__.__name__
+            args = _reduce_args(args=args[0].args)
+        else:
+            self.name = name
+        super().__init__(_reduce_args(args=args))
+
+
+class ClientException(BaseHomematicException):
+    """aiohomematic Client exception."""
+
+    def __init__(self, *args: Any) -> None:
+        """Initialize the ClientException."""
+        super().__init__("ClientException", *args)
+
+
+class UnsupportedException(BaseHomematicException):
+    """aiohomematic unsupported exception."""
+
+    def __init__(self, *args: Any) -> None:
+        """Initialize the UnsupportedException."""
+        super().__init__("UnsupportedException", *args)
+
+
+class ValidationException(BaseHomematicException):
+    """aiohomematic validation exception."""
+
+    def __init__(self, *args: Any) -> None:
+        """Initialize the ValidationException."""
+        super().__init__("ValidationException", *args)
+
+
+class NoConnectionException(BaseHomematicException):
+    """aiohomematic NoConnectionException exception."""
+
+    def __init__(self, *args: Any) -> None:
+        """Initialize the NoConnection."""
+        super().__init__("NoConnectionException", *args)
+
+
+class CircuitBreakerOpenException(BaseHomematicException):
+    """
+    Exception raised when the circuit breaker is open.
+
+    This exception is NOT retryable because the circuit breaker has its own
+    recovery mechanism (transitions to HALF_OPEN after recovery_timeout).
+    Retrying immediately would just waste resources.
+    """
+
+    def __init__(self, *args: Any) -> None:
+        """Initialize the CircuitBreakerOpenException."""
+        super().__init__("CircuitBreakerOpenException", *args)
+
+
+class NoClientsException(BaseHomematicException):
+    """aiohomematic NoClientsException exception."""
+
+    def __init__(self, *args: Any) -> None:
+        """Initialize the NoClientsException."""
+        super().__init__("NoClientsException", *args)
+
+
+class AuthFailure(BaseHomematicException):
+    """aiohomematic AuthFailure exception."""
+
+    def __init__(self, *args: Any) -> None:
+        """Initialize the AuthFailure."""
+        super().__init__("AuthFailure", *args)
+
+
+class AioHomematicException(BaseHomematicException):
+    """aiohomematic AioHomematicException exception."""
+
+    def __init__(self, *args: Any) -> None:
+        """Initialize the AioHomematicException."""
+        super().__init__("AioHomematicException", *args)
+
+
+class AioHomematicConfigException(BaseHomematicException):
+    """aiohomematic AioHomematicConfigException exception."""
+
+    def __init__(self, *args: Any) -> None:
+        """Initialize the AioHomematicConfigException."""
+        super().__init__("AioHomematicConfigException", *args)
+
+
+class InternalBackendException(BaseHomematicException):
+    """aiohomematic InternalBackendException exception."""
+
+    def __init__(self, *args: Any) -> None:
+        """Initialize the InternalBackendException."""
+        super().__init__("InternalBackendException", *args)
+
+
+class DescriptionNotFoundException(BaseHomematicException):
+    """Exception raised when a device/channel description is not found in the cache."""
+
+    def __init__(self, *args: Any) -> None:
+        """Initialize the DescriptionNotFoundException."""
+        super().__init__("DescriptionNotFoundException", *args)
+
+
+def _reduce_args(*, args: tuple[Any, ...]) -> tuple[Any, ...] | Any:
+    """Return the first arg, if there is only one arg."""
+    return args[0] if len(args) == 1 else args
+
+
+def log_exception[**P, R](
+    *,
+    exc_type: type[BaseException],
+    logger: logging.Logger = _LOGGER,
+    level: int = logging.ERROR,
+    extra_msg: str = "",
+    re_raise: bool = False,
+    exc_return: Any = None,
+) -> Callable[[Callable[P, R | Awaitable[R]]], Callable[P, R | Awaitable[R]]]:
+    """Decorate methods for exception logging."""
+
+    def decorator_log_exception(
+        func: Callable[P, R | Awaitable[R]],
+    ) -> Callable[P, R | Awaitable[R]]:
+        """Decorate log exception method."""
+        function_name = func.__name__
+
+        @wraps(func)
+        async def async_wrapper_log_exception(*args: P.args, **kwargs: P.kwargs) -> R:
+            """Wrap async methods."""
+            try:
+                return_value = cast(R, await func(*args, **kwargs))  # type: ignore[misc]
+            except exc_type as exc:
+                message = (
+                    f"{function_name.upper()} failed: {exc_type.__name__} [{_reduce_args(args=exc.args)}] {extra_msg}"
+                )
+                logger.log(level, message)
+                if re_raise:
+                    raise
+                return cast(R, exc_return)
+            return return_value
+
+        @wraps(func)
+        def wrapper_log_exception(*args: P.args, **kwargs: P.kwargs) -> R:
+            """Wrap sync methods."""
+            return cast(R, func(*args, **kwargs))
+
+        if inspect.iscoroutinefunction(func):
+            return async_wrapper_log_exception
+        return wrapper_log_exception
+
+    return decorator_log_exception
+
+
+# Define public API for this module
+__all__ = tuple(
+    sorted(
+        name
+        for name, obj in globals().items()
+        if not name.startswith("_")
+        and (name.isupper() or inspect.isclass(obj) or inspect.isfunction(obj))
+        and getattr(obj, "__module__", __name__) == __name__
+    )
+)