aiohomematic 2025.8.6__py3-none-any.whl

aiohomematic/context.py

@@ -0,0 +1,8 @@
+"""Collection of context variables."""
+
+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)

aiohomematic/converter.py

@@ -0,0 +1,82 @@
+"""Converters used by aiohomematic."""
+
+from __future__ import annotations
+
+import ast
+import logging
+from typing import Any, Final, cast
+
+from aiohomematic.const import Parameter
+from aiohomematic.support import extract_exc_args
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def _convert_cpv_to_hm_level(cpv: Any) -> Any:
+    """Convert combined parameter value for hm level."""
+    if isinstance(cpv, str) and cpv.startswith("0x"):
+        return ast.literal_eval(cpv) / 100 / 2
+    return cpv
+
+
+def _convert_cpv_to_hmip_level(cpv: Any) -> Any:
+    """Convert combined parameter value for hmip level."""
+    return int(cpv) / 100
+
+
+def convert_hm_level_to_cpv(hm_level: Any) -> Any:
+    """Convert hm level to combined parameter value."""
+    return format(int(hm_level * 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}
+
+
+def _convert_combined_parameter_to_paramset(cpv: str) -> dict[str, Any]:
+    """Convert combined parameter to paramset."""
+    paramset: dict[str, Any] = {}
+    for cp_param_value in cpv.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)
+            else:
+                paramset[parameter] = value
+    return paramset
+
+
+def _convert_level_combined_to_paramset(lcv: str) -> dict[str, Any]:
+    """Convert combined parameter to paramset."""
+    if "," in lcv:
+        l1_value, l2_value = lcv.split(",")
+        if converter := _COMBINED_PARAMETER_TO_HM_CONVERTER.get(Parameter.LEVEL_COMBINED):
+            return {
+                Parameter.LEVEL: converter(l1_value),
+                Parameter.LEVEL_SLATS: converter(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,
+}
+
+
+def convert_combined_parameter_to_paramset(parameter: str, cpv: 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(cpv))
+        _LOGGER.debug("CONVERT_COMBINED_PARAMETER_TO_PARAMSET: No converter found for %s: %s", parameter, cpv)
+    except Exception as exc:
+        _LOGGER.debug("CONVERT_COMBINED_PARAMETER_TO_PARAMSET: Convert failed %s", extract_exc_args(exc=exc))
+    return {}

aiohomematic/decorators.py

@@ -0,0 +1,188 @@
+"""Common Decorators used within aiohomematic."""
+
+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, ParamSpec, TypeVar, cast
+
+from aiohomematic.context import IN_SERVICE_VAR
+from aiohomematic.exceptions import BaseHomematicException
+from aiohomematic.support import extract_exc_args
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+def inspector(  # noqa: C901
+    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]]:
+    """
+    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.
+
+    Args:
+        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:
+        A decorator that wraps sync or async functions.
+
+    """
+
+    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) -> R:
+            """Handle exceptions for decorated functions."""
+            if not is_sub_service_call and log_level > logging.NOTSET:
+                message = f"{func.__name__.upper()} failed: {extract_exc_args(exc=exc)}"
+                logging.getLogger(func.__module__).log(level=log_level, msg=message)
+            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."""
+
+            start = monotonic() if measure_performance and _LOGGER.isEnabledFor(level=logging.DEBUG) else None
+            token = IN_SERVICE_VAR.set(True) if not IN_SERVICE_VAR.get() else None
+            try:
+                return_value: R = func(*args, **kwargs)
+            except BaseHomematicException as bhexc:
+                if token:
+                    IN_SERVICE_VAR.reset(token)
+                return handle_exception(
+                    exc=bhexc, func=func, is_sub_service_call=IN_SERVICE_VAR.get(), is_homematic=True
+                )
+            except Exception as exc:
+                if token:
+                    IN_SERVICE_VAR.reset(token)
+                return handle_exception(
+                    exc=exc, func=func, is_sub_service_call=IN_SERVICE_VAR.get(), is_homematic=False
+                )
+            else:
+                if token:
+                    IN_SERVICE_VAR.reset(token)
+                return return_value
+            finally:
+                if start:
+                    _log_performance_message(func, start, *args, **kwargs)
+
+        @wraps(func)
+        async def wrap_async_function(*args: P.args, **kwargs: P.kwargs) -> R:
+            """Wrap async functions."""
+
+            start = monotonic() if measure_performance and _LOGGER.isEnabledFor(level=logging.DEBUG) else None
+            token = IN_SERVICE_VAR.set(True) if not IN_SERVICE_VAR.get() else None
+            try:
+                return_value = await func(*args, **kwargs)  # type: ignore[misc]  # Await the async call
+            except BaseHomematicException as bhexc:
+                if token:
+                    IN_SERVICE_VAR.reset(token)
+                return handle_exception(
+                    exc=bhexc, func=func, is_sub_service_call=IN_SERVICE_VAR.get(), is_homematic=True
+                )
+            except Exception as exc:
+                if token:
+                    IN_SERVICE_VAR.reset(token)
+                return handle_exception(
+                    exc=exc, func=func, is_sub_service_call=IN_SERVICE_VAR.get(), is_homematic=False
+                )
+            else:
+                if token:
+                    IN_SERVICE_VAR.reset(token)
+                return cast(R, return_value)
+            finally:
+                if start:
+                    _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
+
+    return create_wrapped_decorator
+
+
+def _log_performance_message(func: Callable, start: float, *args: P.args, **kwargs: P.kwargs) -> None:  # type: ignore[valid-type]
+    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.info(message)
+
+
+def get_service_calls(obj: object) -> dict[str, Callable]:
+    """Get all methods decorated with the "bind_collector" or "service_call"  decorator."""
+    return {
+        name: getattr(obj, name)
+        for name in dir(obj)
+        if not name.startswith("_")
+        and name not in ("service_methods", "service_method_names")
+        and callable(getattr(obj, name))
+        and hasattr(getattr(obj, name), "ha_service")
+    }
+
+
+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.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.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 async_measure_wrapper  # type: ignore[return-value]
+    return measure_wrapper  # type: ignore[return-value]

aiohomematic/exceptions.py

@@ -0,0 +1,145 @@
+"""Module for AioHomematicExceptions."""
+
+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

aiohomematic/hmcli.py

@@ -0,0 +1,159 @@
+#!/usr/bin/python3
+"""Commandline tool to query HomeMatic hubs via XML-RPC."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+from xmlrpc.client import ServerProxy
+
+from aiohomematic import __version__
+from aiohomematic.const import ParamsetKey
+from aiohomematic.support import build_xml_rpc_headers, build_xml_rpc_uri, get_tls_context
+
+
+def main() -> None:
+    """Start the cli."""
+    parser = argparse.ArgumentParser(
+        description="Commandline tool to query HomeMatic hubs via XML-RPC",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument(
+        "--host",
+        "-H",
+        required=True,
+        type=str,
+        help="Hostname / IP address to connect to",
+    )
+    parser.add_argument(
+        "--port",
+        "-p",
+        required=True,
+        type=int,
+        help="Port to connect to",
+    )
+    parser.add_argument(
+        "--path",
+        type=str,
+        help="Path, used for heating groups",
+    )
+    parser.add_argument(
+        "--username",
+        "-U",
+        nargs="?",
+        help="Username required for access",
+    )
+    parser.add_argument(
+        "--password",
+        "-P",
+        nargs="?",
+        help="Password required for access",
+    )
+    parser.add_argument(
+        "--tls",
+        "-t",
+        action="store_true",
+        help="Enable TLS encryption",
+    )
+    parser.add_argument(
+        "--verify",
+        "-v",
+        action="store_true",
+        help="Verify TLS encryption",
+    )
+    parser.add_argument(
+        "--json",
+        "-j",
+        action="store_true",
+        help="Output as JSON",
+    )
+    parser.add_argument(
+        "--address",
+        "-a",
+        required=True,
+        type=str,
+        help="Address of HomeMatic device, including channel",
+    )
+    parser.add_argument(
+        "--paramset_key",
+        default=ParamsetKey.VALUES,
+        choices=[ParamsetKey.VALUES, ParamsetKey.MASTER],
+        help="Paramset of HomeMatic device. Default: VALUES",
+    )
+    parser.add_argument(
+        "--parameter",
+        required=True,
+        help="Parameter of HomeMatic device",
+    )
+    parser.add_argument(
+        "--value",
+        type=str,
+        help="Value to set for parameter. Use 0/1 for boolean",
+    )
+    parser.add_argument(
+        "--type",
+        choices=["int", "float", "bool"],
+        help="Type of value when setting a value. Using str if not provided",
+    )
+    args = parser.parse_args()
+
+    url = build_xml_rpc_uri(
+        host=args.host,
+        port=args.port,
+        path=args.path,
+        tls=args.tls,
+    )
+    headers = build_xml_rpc_headers(username=args.username, password=args.password)
+    context = None
+    if args.tls:
+        context = get_tls_context(verify_tls=args.verify)
+    proxy = ServerProxy(url, context=context, headers=headers)
+
+    try:
+        if args.paramset_key == ParamsetKey.VALUES and args.value is None:
+            proxy.getValue(args.address, args.parameter)
+            if args.json:
+                pass
+            else:
+                pass
+            sys.exit(0)
+        elif args.paramset_key == ParamsetKey.VALUES and args.value:
+            value: Any
+            if args.type == "int":
+                value = int(args.value)
+            elif args.type == "float":
+                value = float(args.value)
+            elif args.type == "bool":
+                value = bool(int(args.value))
+            else:
+                value = args.value
+            proxy.setValue(args.address, args.parameter, value)
+            sys.exit(0)
+        elif args.paramset_key == ParamsetKey.MASTER and args.value is None:
+            paramset: dict[str, Any] | None
+            if (paramset := proxy.getParamset(args.address, args.paramset_key)) and paramset.get(  # type: ignore[assignment]
+                args.parameter
+            ):
+                if args.json:
+                    pass
+                else:
+                    pass
+            sys.exit(0)
+        elif args.paramset_key == ParamsetKey.MASTER and args.value:
+            if args.type == "int":
+                value = int(args.value)
+            elif args.type == "float":
+                value = float(args.value)
+            elif args.type == "bool":
+                value = bool(int(args.value))
+            else:
+                value = args.value
+            proxy.putParamset(args.address, args.paramset_key, {args.parameter: value})
+            sys.exit(0)
+    except Exception:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()