aiohomematic 2025.11.3__py3-none-any.whl

aiohomematic/context.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""
+Collection of context variables.
+
+Public API of this module is defined by __all__.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+
+# context var for storing if call is running within a service
+IN_SERVICE_VAR: ContextVar[bool] = ContextVar("in_service_var", default=False)
+
+
+# Define public API for this module
+__all__ = ["IN_SERVICE_VAR"]

aiohomematic/converter.py

@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""
+Converters used by aiohomematic.
+
+Public API of this module is defined by __all__.
+"""
+
+from __future__ import annotations
+
+import ast
+from functools import lru_cache
+import inspect
+import logging
+from typing import Any, Final, cast
+
+from aiohomematic.const import Parameter
+from aiohomematic.support import extract_exc_args
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@lru_cache(maxsize=1024)
+def _convert_cpv_to_hm_level(*, value: Any) -> Any:
+    """Convert combined parameter value for hm level."""
+    if isinstance(value, str) and value.startswith("0x"):
+        return ast.literal_eval(value) / 100 / 2
+    return value
+
+
+@lru_cache(maxsize=1024)
+def _convert_cpv_to_hmip_level(*, value: Any) -> Any:
+    """Convert combined parameter value for hmip level."""
+    return int(value) / 100
+
+
+@lru_cache(maxsize=1024)
+def convert_hm_level_to_cpv(*, value: Any) -> Any:
+    """Convert hm level to combined parameter value."""
+    return format(int(value * 100 * 2), "#04x")
+
+
+CONVERTABLE_PARAMETERS: Final = (Parameter.COMBINED_PARAMETER, Parameter.LEVEL_COMBINED)
+
+_COMBINED_PARAMETER_TO_HM_CONVERTER: Final = {
+    Parameter.LEVEL_COMBINED: _convert_cpv_to_hm_level,
+    Parameter.LEVEL: _convert_cpv_to_hmip_level,
+    Parameter.LEVEL_2: _convert_cpv_to_hmip_level,
+}
+
+_COMBINED_PARAMETER_NAMES: Final = {"L": Parameter.LEVEL, "L2": Parameter.LEVEL_2}
+
+
+@lru_cache(maxsize=1024)
+def _convert_combined_parameter_to_paramset(*, value: str) -> dict[str, Any]:
+    """Convert combined parameter to paramset."""
+    paramset: dict[str, Any] = {}
+    for cp_param_value in value.split(","):
+        cp_param, value = cp_param_value.split("=")
+        if parameter := _COMBINED_PARAMETER_NAMES.get(cp_param):
+            if converter := _COMBINED_PARAMETER_TO_HM_CONVERTER.get(parameter):
+                paramset[parameter] = converter(value=value)
+            else:
+                paramset[parameter] = value
+    return paramset
+
+
+@lru_cache(maxsize=1024)
+def _convert_level_combined_to_paramset(*, value: str) -> dict[str, Any]:
+    """Convert combined parameter to paramset."""
+    if "," in value:
+        l1_value, l2_value = value.split(",")
+        if converter := _COMBINED_PARAMETER_TO_HM_CONVERTER.get(Parameter.LEVEL_COMBINED):
+            return {
+                Parameter.LEVEL: converter(value=l1_value),
+                Parameter.LEVEL_SLATS: converter(value=l2_value),
+            }
+    return {}
+
+
+_COMBINED_PARAMETER_TO_PARAMSET_CONVERTER: Final = {
+    Parameter.COMBINED_PARAMETER: _convert_combined_parameter_to_paramset,
+    Parameter.LEVEL_COMBINED: _convert_level_combined_to_paramset,
+}
+
+
+@lru_cache(maxsize=1024)
+def convert_combined_parameter_to_paramset(*, parameter: str, value: str) -> dict[str, Any]:
+    """Convert combined parameter to paramset."""
+    try:
+        if converter := _COMBINED_PARAMETER_TO_PARAMSET_CONVERTER.get(parameter):  # type: ignore[call-overload]
+            return cast(dict[str, Any], converter(value=value))
+        _LOGGER.debug("CONVERT_COMBINED_PARAMETER_TO_PARAMSET: No converter found for %s: %s", parameter, value)
+    except Exception as exc:
+        _LOGGER.debug("CONVERT_COMBINED_PARAMETER_TO_PARAMSET: Convert failed %s", extract_exc_args(exc=exc))
+    return {}
+
+
+# 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.isfunction(obj) or inspect.isclass(obj))
+        and getattr(obj, "__module__", __name__) == __name__
+    )
+)

aiohomematic/decorators.py

@@ -0,0 +1,302 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""
+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.context import IN_SERVICE_VAR
+from aiohomematic.exceptions import BaseHomematicException
+from aiohomematic.support import LogContextMixin, log_boundary_error
+
+_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](
+    func: Callable[P, R],
+    /,
+    *,
+    log_level: int = ...,
+    re_raise: bool = ...,
+    no_raise_return: Any = ...,
+    measure_performance: bool = ...,
+) -> Callable[P, R]: ...
+
+
+@overload
+def inspector[**P, R](
+    func: None = ...,
+    /,
+    *,
+    log_level: int = ...,
+    re_raise: bool = ...,
+    no_raise_return: Any = ...,
+    measure_performance: bool = ...,
+) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+
+
+def inspector[**P, R](  # noqa: C901
+    func: Callable[P, R] | None = None,
+    /,
+    *,
+    log_level: int = logging.ERROR,
+    re_raise: bool = True,
+    no_raise_return: Any = None,
+    measure_performance: bool = False,
+) -> 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, ...)
+
+    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.
+
+    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: Callable, 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."""
+
+            # Fast-path: avoid logger check and time call unless explicitly enabled
+            start_needed = measure_performance and _LOGGER_PERFORMANCE.isEnabledFor(level=logging.DEBUG)
+            start = monotonic() if start_needed else None
+
+            # Avoid repeated ContextVar.get() calls; only set/reset when needed
+            was_in_service = IN_SERVICE_VAR.get()
+            token = IN_SERVICE_VAR.set(True) if not was_in_service else None
+            context_obj = args[0] if args else None
+            try:
+                return_value: R = func(*args, **kwargs)
+            except BaseHomematicException as bhexc:
+                if token is not None:
+                    IN_SERVICE_VAR.reset(token)
+                return handle_exception(
+                    exc=bhexc,
+                    func=func,
+                    is_sub_service_call=was_in_service,
+                    is_homematic=True,
+                    context_obj=context_obj,
+                )
+            except Exception as exc:
+                if token is not None:
+                    IN_SERVICE_VAR.reset(token)
+                return handle_exception(
+                    exc=exc,
+                    func=func,
+                    is_sub_service_call=was_in_service,
+                    is_homematic=False,
+                    context_obj=context_obj,
+                )
+            else:
+                if token is not None:
+                    IN_SERVICE_VAR.reset(token)
+                return return_value
+            finally:
+                if start is not None:
+                    _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_needed = measure_performance and _LOGGER_PERFORMANCE.isEnabledFor(level=logging.DEBUG)
+            start = monotonic() if start_needed else None
+
+            was_in_service = IN_SERVICE_VAR.get()
+            token = IN_SERVICE_VAR.set(True) if not was_in_service else None
+            context_obj = args[0] if args else None
+            try:
+                return_value = await func(*args, **kwargs)  # type: ignore[misc]
+            except BaseHomematicException as bhexc:
+                if token is not None:
+                    IN_SERVICE_VAR.reset(token)
+                return handle_exception(
+                    exc=bhexc,
+                    func=func,
+                    is_sub_service_call=was_in_service,
+                    is_homematic=True,
+                    context_obj=context_obj,
+                )
+            except Exception as exc:
+                if token is not None:
+                    IN_SERVICE_VAR.reset(token)
+                return handle_exception(
+                    exc=exc,
+                    func=func,
+                    is_sub_service_call=was_in_service,
+                    is_homematic=False,
+                    context_obj=context_obj,
+                )
+            else:
+                if token is not None:
+                    IN_SERVICE_VAR.reset(token)
+                return cast(R, return_value)
+            finally:
+                if start is not None:
+                    _log_performance_message(func, start, *args, **kwargs)
+
+        # Check if the function is a coroutine or not and select the appropriate wrapper
+        if inspect.iscoroutinefunction(func):
+            setattr(wrap_async_function, "ha_service", True)
+            return wrap_async_function  # type: ignore[return-value]
+        setattr(wrap_sync_function, "ha_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 _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) -> dict[str, Callable]:
+    """
+    Get all methods decorated with the service decorator (ha_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 ha_service on the function/wrapper
+            if callable(getattr(obj, name, None)) and hasattr(attr, "ha_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: Callable[..., Any]](func: CallableT) -> CallableT:
+    """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,164 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025
+"""
+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:
+        """Init 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:
+        """Init the ClientException."""
+        super().__init__("ClientException", *args)
+
+
+class UnsupportedException(BaseHomematicException):
+    """aiohomematic unsupported exception."""
+
+    def __init__(self, *args: Any) -> None:
+        """Init the UnsupportedException."""
+        super().__init__("UnsupportedException", *args)
+
+
+class ValidationException(BaseHomematicException):
+    """aiohomematic validation exception."""
+
+    def __init__(self, *args: Any) -> None:
+        """Init the ValidationException."""
+        super().__init__("ValidationException", *args)
+
+
+class NoConnectionException(BaseHomematicException):
+    """aiohomematic NoConnectionException exception."""
+
+    def __init__(self, *args: Any) -> None:
+        """Init the NoConnection."""
+        super().__init__("NoConnectionException", *args)
+
+
+class NoClientsException(BaseHomematicException):
+    """aiohomematic NoClientsException exception."""
+
+    def __init__(self, *args: Any) -> None:
+        """Init the NoClientsException."""
+        super().__init__("NoClientsException", *args)
+
+
+class AuthFailure(BaseHomematicException):
+    """aiohomematic AuthFailure exception."""
+
+    def __init__(self, *args: Any) -> None:
+        """Init the AuthFailure."""
+        super().__init__("AuthFailure", *args)
+
+
+class AioHomematicException(BaseHomematicException):
+    """aiohomematic AioHomematicException exception."""
+
+    def __init__(self, *args: Any) -> None:
+        """Init the AioHomematicException."""
+        super().__init__("AioHomematicException", *args)
+
+
+class AioHomematicConfigException(BaseHomematicException):
+    """aiohomematic AioHomematicConfigException exception."""
+
+    def __init__(self, *args: Any) -> None:
+        """Init the AioHomematicConfigException."""
+        super().__init__("AioHomematicConfigException", *args)
+
+
+class InternalBackendException(BaseHomematicException):
+    """aiohomematic InternalBackendException exception."""
+
+    def __init__(self, *args: Any) -> None:
+        """Init the InternalBackendException."""
+        super().__init__("InternalBackendException", *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:
+    """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__
+    )
+)