aiohomematic 2025.8.9__py3-none-any.whl → 2025.8.10__py3-none-any.whl

aiohomematic/client/xml_rpc.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 XML-RPC transport proxy with concurrency control and connection awareness.
 
@@ -19,6 +21,7 @@ Notes
 
 from __future__ import annotations
 
+import asyncio
 from collections.abc import Mapping
 from concurrent.futures import ThreadPoolExecutor
 from enum import Enum, IntEnum, StrEnum
@@ -30,6 +33,7 @@ import xmlrpc.client
 
 from aiohomematic import central as hmcu
 from aiohomematic.async_support import Looper
+from aiohomematic.client._rpc_errors import RpcContext, map_xmlrpc_fault
 from aiohomematic.const import ISO_8859_1
 from aiohomematic.exceptions import (
     AuthFailure,
@@ -134,13 +138,15 @@ class XmlRpcProxy(xmlrpc.client.ServerProxy):
             ):
                 args = _cleanup_args(*args)
                 _LOGGER.debug("__ASYNC_REQUEST: %s", args)
-                result = await self._looper.async_add_executor_job(
-                    # pylint: disable=protected-access
-                    parent._ServerProxy__request,  # type: ignore[attr-defined]
-                    self,
-                    *args,
-                    name="xmp_rpc_proxy",
-                    executor=self._proxy_executor,
+                result = await asyncio.shield(
+                    self._looper.async_add_executor_job(
+                        # pylint: disable=protected-access
+                        parent._ServerProxy__request,  # type: ignore[attr-defined]
+                        self,
+                        *args,
+                        name="xmp_rpc_proxy",
+                        executor=self._proxy_executor,
+                    )
                 )
                 self._connection_state.remove_issue(issuer=self, iid=self.interface_id)
                 return result
@@ -165,7 +171,8 @@ class XmlRpcProxy(xmlrpc.client.ServerProxy):
                 _LOGGER.error(message)
             raise NoConnectionException(message) from oserr
         except xmlrpc.client.Fault as flt:
-            raise ClientException(f"XMLRPC Fault from backend: {flt.faultCode} {flt.faultString}") from flt
+            ctx = RpcContext(protocol="xml-rpc", method=str(args[0]), interface=self.interface_id)
+            raise map_xmlrpc_fault(code=flt.faultCode, fault_string=flt.faultString, ctx=ctx) from flt
         except TypeError as terr:
             raise ClientException(terr) from terr
         except xmlrpc.client.ProtocolError as perr:

aiohomematic/const.py

@@ -1,4 +1,10 @@
-"""Constants used by aiohomematic."""
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
+"""
+Constants used by aiohomematic.
+
+Public API of this module is defined by __all__.
+"""
 
 from __future__ import annotations
 
@@ -6,13 +12,14 @@ from collections.abc import Callable, Iterable, Mapping
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum, IntEnum, StrEnum
+import inspect
 import os
 import re
 import sys
 from types import MappingProxyType
 from typing import Any, Final, NamedTuple, Required, TypeAlias, TypedDict
 
-VERSION: Final = "2025.8.9"
+VERSION: Final = "2025.8.10"
 
 # Detect test speedup mode via environment
 _TEST_SPEEDUP: Final = (
@@ -67,7 +74,8 @@ RENAME_SYSVAR_BY_NAME: Final[Mapping[str, str]] = MappingProxyType(
     }
 )
 
-SYSVAR_ENABLE_DEFAULT: Final[frozenset[str]] = frozenset({"40", "41"})
+# Deprecated alias (use ALWAYS_ENABLE_SYSVARS_BY_ID). Kept for backward compatibility.
+SYSVAR_ENABLE_DEFAULT: Final[frozenset[str]] = ALWAYS_ENABLE_SYSVARS_BY_ID
 
 ADDRESS_SEPARATOR: Final = ":"
 BLOCK_LOG_TIMEOUT: Final = 60
@@ -161,6 +169,17 @@ class CallSource(StrEnum):
     MANUAL_OR_SCHEDULED = "manual_or_scheduled"
 
 
+class CentralUnitState(StrEnum):
+    """Enum with central unit states."""
+
+    INITIALIZING = "initializing"
+    NEW = "new"
+    RUNNING = "running"
+    STOPPED = "stopped"
+    STOPPED_BY_ERROR = "stopped_by_error"
+    STOPPING = "stopping"
+
+
 class DataOperationResult(Enum):
     """Enum with data operation results."""
 
@@ -601,6 +620,8 @@ KEY_CHANNEL_OPERATION_MODE_VISIBILITY: Final[Mapping[str, frozenset[str]]] = Map
     }
 )
 
+BLOCKED_CATEGORIES: Final[tuple[DataPointCategory, ...]] = (DataPointCategory.ACTION,)
+
 HUB_CATEGORIES: Final[tuple[DataPointCategory, ...]] = (
     DataPointCategory.HUB_BINARY_SENSOR,
     DataPointCategory.HUB_BUTTON,
@@ -820,3 +841,23 @@ class DeviceDescription(TypedDict, total=False):
     INTERFACE: str | None
     # ROAMING: int | None
     RX_MODE: int
+
+
+# Define public API for this module
+__all__ = tuple(
+    sorted(
+        name
+        for name, obj in globals().items()
+        if not name.startswith("_")
+        and (
+            name.isupper()  # constants like VERSION, patterns, defaults
+            or inspect.isclass(obj)  # Enums, dataclasses, TypedDicts, NamedTuple classes
+            or inspect.isfunction(obj)  # module functions
+        )
+        and (
+            getattr(obj, "__module__", __name__) == __name__
+            if not isinstance(obj, (int, float, str, bytes, tuple, frozenset, dict))
+            else True
+        )
+    )
+)

aiohomematic/context.py

@@ -1,4 +1,10 @@
-"""Collection of context variables."""
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
+"""
+Collection of context variables.
+
+Public API of this module is defined by __all__.
+"""
 
 from __future__ import annotations
 
@@ -6,3 +12,7 @@ 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

@@ -1,8 +1,16 @@
-"""Converters used by aiohomematic."""
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
+"""
+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
 
@@ -12,6 +20,7 @@ from aiohomematic.support import extract_exc_args
 _LOGGER = logging.getLogger(__name__)
 
 
+@lru_cache(maxsize=1024)
 def _convert_cpv_to_hm_level(cpv: Any) -> Any:
     """Convert combined parameter value for hm level."""
     if isinstance(cpv, str) and cpv.startswith("0x"):
@@ -19,11 +28,13 @@ def _convert_cpv_to_hm_level(cpv: Any) -> Any:
     return cpv
 
 
+@lru_cache(maxsize=1024)
 def _convert_cpv_to_hmip_level(cpv: Any) -> Any:
     """Convert combined parameter value for hmip level."""
     return int(cpv) / 100
 
 
+@lru_cache(maxsize=1024)
 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")
@@ -40,6 +51,7 @@ _COMBINED_PARAMETER_TO_HM_CONVERTER: Final = {
 _COMBINED_PARAMETER_NAMES: Final = {"L": Parameter.LEVEL, "L2": Parameter.LEVEL_2}
 
 
+@lru_cache(maxsize=1024)
 def _convert_combined_parameter_to_paramset(cpv: str) -> dict[str, Any]:
     """Convert combined parameter to paramset."""
     paramset: dict[str, Any] = {}
@@ -53,6 +65,7 @@ def _convert_combined_parameter_to_paramset(cpv: str) -> dict[str, Any]:
     return paramset
 
 
+@lru_cache(maxsize=1024)
 def _convert_level_combined_to_paramset(lcv: str) -> dict[str, Any]:
     """Convert combined parameter to paramset."""
     if "," in lcv:
@@ -71,6 +84,7 @@ _COMBINED_PARAMETER_TO_PARAMSET_CONVERTER: Final = {
 }
 
 
+@lru_cache(maxsize=1024)
 def convert_combined_parameter_to_paramset(parameter: str, cpv: str) -> dict[str, Any]:
     """Convert combined parameter to paramset."""
     try:
@@ -80,3 +94,15 @@ def convert_combined_parameter_to_paramset(parameter: str, cpv: str) -> dict[str
     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

@@ -1,4 +1,10 @@
-"""Common Decorators used within aiohomematic."""
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
+"""
+Common Decorators used within aiohomematic.
+
+Public API of this module is defined by __all__.
+"""
 
 from __future__ import annotations
 
@@ -8,16 +14,21 @@ import inspect
 import logging
 from time import monotonic
 from typing import Any, Final, ParamSpec, TypeVar, cast
+from weakref import WeakKeyDictionary
 
 from aiohomematic.context import IN_SERVICE_VAR
 from aiohomematic.exceptions import BaseHomematicException
-from aiohomematic.support import extract_exc_args
+from aiohomematic.support import build_log_context_from_obj, extract_exc_args
 
 P = ParamSpec("P")
 R = TypeVar("R")
 
 _LOGGER: Final = logging.getLogger(__name__)
 
+# 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()
+
 
 def inspector(  # noqa: C901
     log_level: int = logging.ERROR,
@@ -54,11 +65,22 @@ def inspector(  # noqa: C901
 
         """
 
-        def handle_exception(exc: Exception, func: Callable, is_sub_service_call: bool, is_homematic: bool) -> R:
-            """Handle exceptions for decorated functions."""
+        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:
-                message = f"{func.__name__.upper()} failed: {extract_exc_args(exc=exc)}"
-                logging.getLogger(func.__module__).log(level=log_level, msg=message)
+                logger = logging.getLogger(func.__module__)
+                extra = {
+                    "err_type": exc.__class__.__name__,
+                    "err": extract_exc_args(exc=exc),
+                    "function": func.__name__,
+                    **build_log_context_from_obj(obj=context_obj),
+                }
+                if log_level >= logging.ERROR:
+                    logger.exception("service_error", extra=extra)
+                else:
+                    logger.log(level=log_level, msg="service_error", extra=extra)
             if re_raise or not is_homematic:
                 raise exc
             return cast(R, no_raise_return)
@@ -75,13 +97,21 @@ def inspector(  # noqa: C901
                 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
+                    exc=bhexc,
+                    func=func,
+                    is_sub_service_call=IN_SERVICE_VAR.get(),
+                    is_homematic=True,
+                    context_obj=(args[0] if args else None),
                 )
             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
+                    exc=exc,
+                    func=func,
+                    is_sub_service_call=IN_SERVICE_VAR.get(),
+                    is_homematic=False,
+                    context_obj=(args[0] if args else None),
                 )
             else:
                 if token:
@@ -103,13 +133,21 @@ def inspector(  # noqa: C901
                 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
+                    exc=bhexc,
+                    func=func,
+                    is_sub_service_call=IN_SERVICE_VAR.get(),
+                    is_homematic=True,
+                    context_obj=(args[0] if args else None),
                 )
             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
+                    exc=exc,
+                    func=func,
+                    is_sub_service_call=IN_SERVICE_VAR.get(),
+                    is_homematic=False,
+                    context_obj=(args[0] if args else None),
                 )
             else:
                 if token:
@@ -147,15 +185,34 @@ def _log_performance_message(func: Callable, start: float, *args: P.args, **kwar
 
 
 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")
-    }
+    """
+    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:
@@ -186,3 +243,15 @@ def measure_execution_time[CallableT: Callable[..., Any]](func: CallableT) -> Ca
     if inspect.iscoroutinefunction(func):
         return async_measure_wrapper  # type: ignore[return-value]
     return measure_wrapper  # type: ignore[return-value]
+
+
+# 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

@@ -1,4 +1,10 @@
-"""Module for AioHomematicExceptions."""
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
+"""
+Module for AioHomematicExceptions.
+
+Public API of this module is defined by __all__.
+"""
 
 from __future__ import annotations
 
@@ -143,3 +149,15 @@ def log_exception[**P, R](
         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__
+    )
+)

aiohomematic/hmcli.py

@@ -1,5 +1,14 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 #!/usr/bin/python3
-"""Commandline tool to query HomeMatic hubs via XML-RPC."""
+"""
+Commandline tool to query HomeMatic hubs via XML-RPC.
+
+Public API of this module is defined by __all__.
+
+This module provides a command-line interface; as a library surface it only
+exposes the 'main' entrypoint for invocation. All other names are internal.
+"""
 
 from __future__ import annotations
 
@@ -12,6 +21,9 @@ from aiohomematic import __version__
 from aiohomematic.const import ParamsetKey
 from aiohomematic.support import build_xml_rpc_headers, build_xml_rpc_uri, get_tls_context
 
+# Define public API for this module (CLI only)
+__all__ = ["main"]
+
 
 def main() -> None:
     """Start the cli."""

aiohomematic/model/__init__.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Data point and event model for AioHomematic.
 

aiohomematic/model/calculated/__init__.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Calculated (derived) data points for AioHomematic.
 

aiohomematic/model/calculated/climate.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """Module for calculating the apparent temperature in the sensor category."""
 
 from __future__ import annotations

aiohomematic/model/calculated/data_point.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """Module with base class for calculated data points."""
 
 from __future__ import annotations

aiohomematic/model/calculated/operating_voltage_level.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """Module for calculating the operating voltage level in the sensor category."""
 
 from __future__ import annotations

aiohomematic/model/calculated/support.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 A number of functions used to calculate values based on existing data.
 

aiohomematic/model/custom/__init__.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Custom data points for AioHomematic.
 

aiohomematic/model/custom/climate.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """Module for data points implemented using the climate category."""
 
 from __future__ import annotations
@@ -335,7 +337,7 @@ class BaseCustomDpClimate(CustomDataPoint):
             do_validate = False
 
         if do_validate and not (self.min_temp <= temperature <= self.max_temp):
-            raise ValueError(
+            raise ValidationException(
                 f"SET_TEMPERATURE failed: Invalid temperature: {temperature} (min: {self.min_temp}, max: {self.max_temp})"
             )
 

aiohomematic/model/custom/const.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """Constants used by aiohomematic custom data points."""
 
 from __future__ import annotations

aiohomematic/model/custom/cover.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """Module for data points implemented using the cover category."""
 
 from __future__ import annotations
@@ -21,6 +23,11 @@ from aiohomematic.model.generic import DpAction, DpFloat, DpSelect, DpSensor
 
 _LOGGER: Final = logging.getLogger(__name__)
 
+# Timeout for acquiring the per-instance command processing lock to avoid
+# potential deadlocks or indefinite serialization if an awaited call inside
+# the critical section stalls.
+_COMMAND_LOCK_TIMEOUT: Final[float] = 5.0
+
 _CLOSED_LEVEL: Final = 0.0
 _COVER_VENT_MAX_POSITION: Final = 50
 _LEVEL_TO_POSITION_MULTIPLIER: Final = 100.0
@@ -336,7 +343,15 @@ class CustomDpBlind(CustomDpCover):
         """
         currently_moving = False
 
-        async with self._command_processing_lock:
+        try:
+            acquired: bool = await asyncio.wait_for(
+                self._command_processing_lock.acquire(), timeout=_COMMAND_LOCK_TIMEOUT
+            )
+        except TimeoutError:
+            acquired = False
+            _LOGGER.warning("%s: command lock acquisition timed out; proceeding without lock", self)
+
+        try:
             if level is not None:
                 _level = level
             elif self._target_level is not None:
@@ -360,6 +375,9 @@ class CustomDpBlind(CustomDpCover):
                 await self._stop()
 
             await self._send_level(level=_level, tilt_level=_tilt_level, collector=collector)
+        finally:
+            if acquired:
+                self._command_processing_lock.release()
 
     @bind_collector()
     async def _send_level(
@@ -404,8 +422,18 @@ class CustomDpBlind(CustomDpCover):
     @bind_collector(enabled=False)
     async def stop(self, collector: CallParameterCollector | None = None) -> None:
         """Stop the device if in motion."""
-        async with self._command_processing_lock:
+        try:
+            acquired: bool = await asyncio.wait_for(
+                self._command_processing_lock.acquire(), timeout=_COMMAND_LOCK_TIMEOUT
+            )
+        except TimeoutError:
+            acquired = False
+            _LOGGER.warning("%s: command lock acquisition timed out; proceeding without lock", self)
+        try:
             await self._stop(collector=collector)
+        finally:
+            if acquired:
+                self._command_processing_lock.release()
 
     @bind_collector(enabled=False)
     async def _stop(self, collector: CallParameterCollector | None = None) -> None:

aiohomematic/model/custom/data_point.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """Module with base class for custom data points."""
 
 from __future__ import annotations

aiohomematic/model/custom/definition.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """The module contains device descriptions for custom data points."""
 
 from __future__ import annotations