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

aiohomematic/client/json_rpc.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Asynchronous JSON-RPC client for HomeMatic CCU-compatible backends.
 
@@ -29,6 +31,7 @@ Notes
 
 from __future__ import annotations
 
+import asyncio
 from asyncio import Semaphore
 from collections.abc import Mapping
 from datetime import datetime
@@ -54,6 +57,7 @@ import orjson
 
 from aiohomematic import central as hmcu
 from aiohomematic.async_support import Looper
+from aiohomematic.client._rpc_errors import RpcContext, map_jsonrpc_error
 from aiohomematic.const import (
     ALWAYS_ENABLE_SYSVARS_BY_ID,
     DEFAULT_INCLUDE_INTERNAL_PROGRAMS,
@@ -78,7 +82,6 @@ from aiohomematic.const import (
     SysvarType,
 )
 from aiohomematic.exceptions import (
-    AuthFailure,
     BaseHomematicException,
     ClientException,
     InternalBackendException,
@@ -91,6 +94,7 @@ from aiohomematic.support import (
     element_matches_key,
     extract_exc_args,
     get_tls_context,
+    log_boundary_error,
     parse_sys_var,
 )
 
@@ -402,38 +406,59 @@ class JsonRpcAioHttpClient:
             )
             if method in _PARALLEL_EXECUTION_LIMITED_JSONRPC_METHODS:
                 async with self._sema:
-                    if (response := await post_call()) is None:
+                    if (response := await asyncio.shield(post_call())) is None:
                         raise ClientException("POST method failed with no response")
-            elif (response := await post_call()) is None:
+            elif (response := await asyncio.shield(post_call())) is None:
                 raise ClientException("POST method failed with no response")
 
             if response.status == 200:
-                json_response = await self._get_json_reponse(response=response)
+                json_response = await asyncio.shield(self._get_json_reponse(response=response))
 
                 if error := json_response[_JsonKey.ERROR]:
-                    error_message = error[_JsonKey.MESSAGE]
-                    message = f"POST method '{method}' failed: {error_message}"
-                    if error_message.startswith("access denied"):
-                        _LOGGER.debug(message)
-                        raise AuthFailure(message)
-                    if "internal error" in error_message:
-                        message = f"An internal error happened within your backend (Fix or ignore it): {message}"
-                        _LOGGER.debug(message)
-                        raise InternalBackendException(message)
-                    _LOGGER.debug(message)
-                    raise ClientException(message)
+                    # Map JSON-RPC error to actionable exception with context
+                    ctx = RpcContext(protocol="json-rpc", method=str(method), host=self._url)
+                    exc = map_jsonrpc_error(error=error, ctx=ctx)
+                    # Structured boundary log at warning level (recoverable per-call failure)
+                    log_boundary_error(
+                        logger=_LOGGER,
+                        boundary="json-rpc",
+                        action=str(method),
+                        err=exc,
+                        level=logging.WARNING,
+                        context={"url": self._url},
+                    )
+                    _LOGGER.debug("POST: %s", exc)
+                    raise exc
 
                 return json_response
 
             message = f"Status: {response.status}"
-            json_response = await self._get_json_reponse(response=response)
+            json_response = await asyncio.shield(self._get_json_reponse(response=response))
             if error := json_response[_JsonKey.ERROR]:
-                error_message = error[_JsonKey.MESSAGE]
-                message = f"{message}: {error_message}"
+                ctx = RpcContext(protocol="json-rpc", method=str(method), host=self._url)
+                exc = map_jsonrpc_error(error=error, ctx=ctx)
+                log_boundary_error(
+                    logger=_LOGGER,
+                    boundary="json-rpc",
+                    action=str(method),
+                    err=exc,
+                    level=logging.WARNING,
+                    context={"url": self._url, "status": response.status},
+                )
+                raise exc
             raise ClientException(message)
-        except BaseHomematicException:
+        except BaseHomematicException as bhe:
             if method in (_JsonRpcMethod.SESSION_LOGIN, _JsonRpcMethod.SESSION_LOGOUT, _JsonRpcMethod.SESSION_RENEW):
                 self.clear_session()
+            # Domain error at boundary -> warning
+            log_boundary_error(
+                logger=_LOGGER,
+                boundary="json-rpc",
+                action=str(method),
+                err=bhe,
+                level=logging.WARNING,
+                context={"url": self._url},
+            )
             raise
         except ClientConnectorCertificateError as cccerr:
             self.clear_session()
@@ -443,12 +468,36 @@ class JsonRpcAioHttpClient:
                     f"{message}. Possible reason: 'Automatic forwarding to HTTPS' is enabled in backend, "
                     f"but this integration is not configured to use TLS"
                 )
+            log_boundary_error(
+                logger=_LOGGER,
+                boundary="json-rpc",
+                action=str(method),
+                err=cccerr,
+                level=logging.ERROR,
+                context={"url": self._url},
+            )
             raise ClientException(message) from cccerr
         except (ClientError, OSError) as err:
             self.clear_session()
+            log_boundary_error(
+                logger=_LOGGER,
+                boundary="json-rpc",
+                action=str(method),
+                err=err,
+                level=logging.ERROR,
+                context={"url": self._url},
+            )
             raise NoConnectionException(err) from err
         except (TypeError, Exception) as exc:
             self.clear_session()
+            log_boundary_error(
+                logger=_LOGGER,
+                boundary="json-rpc",
+                action=str(method),
+                err=exc,
+                level=logging.ERROR,
+                context={"url": self._url},
+            )
             raise ClientException(exc) from exc
 
     async def _get_json_reponse(self, response: ClientResponse) -> dict[str, Any] | Any:

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,12 +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 typing import Any, Final, NamedTuple, Required, TypedDict
+from types import MappingProxyType
+from typing import Any, Final, NamedTuple, Required, TypeAlias, TypedDict
 
-VERSION: Final = "2025.8.8"
+VERSION: Final = "2025.8.10"
 
 # Detect test speedup mode via environment
 _TEST_SPEEDUP: Final = (
@@ -24,7 +32,7 @@ DEFAULT_ENABLE_DEVICE_FIRMWARE_CHECK: Final = False
 DEFAULT_ENABLE_PROGRAM_SCAN: Final = True
 DEFAULT_ENABLE_SYSVAR_SCAN: Final = True
 DEFAULT_HM_MASTER_POLL_AFTER_SEND_INTERVALS: Final = (5,)
-DEFAULT_IGNORE_CUSTOM_DEVICE_DEFINITION_MODELS: Final[tuple[str, ...]] = ()
+DEFAULT_IGNORE_CUSTOM_DEVICE_DEFINITION_MODELS: Final[frozenset[str]] = frozenset()
 DEFAULT_INCLUDE_INTERNAL_PROGRAMS: Final = False
 DEFAULT_INCLUDE_INTERNAL_SYSVARS: Final = True
 DEFAULT_MAX_READ_WORKERS: Final = 1
@@ -35,7 +43,7 @@ DEFAULT_PROGRAM_MARKERS: Final[tuple[DescriptionMarker | str, ...]] = ()
 DEFAULT_SYSVAR_MARKERS: Final[tuple[DescriptionMarker | str, ...]] = ()
 DEFAULT_SYS_SCAN_INTERVAL: Final = 30
 DEFAULT_TLS: Final = False
-DEFAULT_UN_IGNORES: Final[tuple[str, ...]] = ()
+DEFAULT_UN_IGNORES: Final[frozenset[str]] = frozenset()
 DEFAULT_VERIFY_TLS: Final = False
 
 # Default encoding for json service calls, persistent cache
@@ -52,22 +60,25 @@ CHANNEL_ADDRESS_PATTERN: Final = re.compile(r"^[0-9a-zA-Z-]{5,20}:[0-9]{1,3}$")
 DEVICE_ADDRESS_PATTERN: Final = re.compile(r"^[0-9a-zA-Z-]{5,20}$")
 ALLOWED_HOSTNAME_PATTERN: Final = re.compile(r"(?!-)[a-z0-9-]{1,63}(?<!-)$", re.IGNORECASE)
 HTMLTAG_PATTERN: Final = re.compile(r"<.*?>|&([a-z0-9]+|#[0-9]{1,6}|#x[0-9a-f]{1,6});")
-SCHEDULER_PROFILE_PATTERN = re.compile(
+SCHEDULER_PROFILE_PATTERN: Final = re.compile(
     r"^P[1-6]_(ENDTIME|TEMPERATURE)_(MONDAY|TUESDAY|WEDNESDAY|THURSDAY|FRIDAY|SATURDAY|SUNDAY)_([1-9]|1[0-3])$"
 )
-SCHEDULER_TIME_PATTERN = re.compile(r"^(([0-1]{0,1}[0-9])|(2[0-4])):[0-5][0-9]")
-
-ALWAYS_ENABLE_SYSVARS_BY_ID: Final = "40", "41"
-RENAME_SYSVAR_BY_NAME: Final = {
-    "${sysVarAlarmMessages}": "ALARM_MESSAGES",
-    "${sysVarPresence}": "PRESENCE",
-    "${sysVarServiceMessages}": "SERVICE_MESSAGES",
-}
+SCHEDULER_TIME_PATTERN: Final = re.compile(r"^(([0-1]{0,1}[0-9])|(2[0-4])):[0-5][0-9]")
+
+ALWAYS_ENABLE_SYSVARS_BY_ID: Final[frozenset[str]] = frozenset({"40", "41"})
+RENAME_SYSVAR_BY_NAME: Final[Mapping[str, str]] = MappingProxyType(
+    {
+        "${sysVarAlarmMessages}": "ALARM_MESSAGES",
+        "${sysVarPresence}": "PRESENCE",
+        "${sysVarServiceMessages}": "SERVICE_MESSAGES",
+    }
+)
 
-SYSVAR_ENABLE_DEFAULT: Final = "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 = 60
+BLOCK_LOG_TIMEOUT: Final = 60
 CACHE_PATH: Final = "cache"
 CONF_PASSWORD: Final = "password"
 CONF_USERNAME: Final = "username"
@@ -79,7 +90,7 @@ DEVICE_DESCRIPTIONS_DIR: Final = "export_device_descriptions"
 DEVICE_FIRMWARE_CHECK_INTERVAL: Final = 21600  # 6h
 DEVICE_FIRMWARE_DELIVERING_CHECK_INTERVAL: Final = 3600  # 1h
 DEVICE_FIRMWARE_UPDATING_CHECK_INTERVAL: Final = 300  # 5m
-DUMMY_SERIAL = "SN0815"
+DUMMY_SERIAL: Final = "SN0815"
 FILE_DEVICES: Final = "homematic_devices.json"
 FILE_PARAMSETS: Final = "homematic_paramsets.json"
 HUB_PATH: Final = "hub"
@@ -87,7 +98,7 @@ IDENTIFIER_SEPARATOR: Final = "@"
 INIT_DATETIME: Final = datetime.strptime("01.01.1970 00:00:00", DATETIME_FORMAT)
 IP_ANY_V4: Final = "0.0.0.0"
 JSON_SESSION_AGE: Final = 90
-KWARGS_ARG_DATA_POINT = "data_point"
+KWARGS_ARG_DATA_POINT: Final = "data_point"
 LAST_COMMAND_SEND_STORE_TIMEOUT: Final = 60
 LOCAL_HOST: Final = "127.0.0.1"
 MAX_CACHE_AGE: Final = 10
@@ -113,7 +124,7 @@ WAIT_FOR_CALLBACK: Final[int | None] = None
 SCHEDULER_NOT_STARTED_SLEEP: Final = 0.05 if _TEST_SPEEDUP else 10
 SCHEDULER_LOOP_SLEEP: Final = 0.05 if _TEST_SPEEDUP else 5
 
-CALLBACK_WARN_INTERVAL = CONNECTION_CHECKER_INTERVAL * 40
+CALLBACK_WARN_INTERVAL: Final = CONNECTION_CHECKER_INTERVAL * 40
 
 # Path
 PROGRAM_SET_PATH_ROOT: Final = "program/set"
@@ -125,7 +136,7 @@ SYSVAR_STATE_PATH_ROOT: Final = "sysvar/status"
 VIRTDEV_SET_PATH_ROOT: Final = "virtdev/set"
 VIRTDEV_STATE_PATH_ROOT: Final = "virtdev/status"
 
-CALLBACK_TYPE = Callable[[], None] | None
+CALLBACK_TYPE: TypeAlias = Callable[[], None] | None
 
 
 class Backend(StrEnum):
@@ -158,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."""
 
@@ -536,22 +558,26 @@ class ParameterType(StrEnum):
     EMPTY = ""
 
 
-CLICK_EVENTS: Final[tuple[Parameter, ...]] = (
-    Parameter.PRESS,
-    Parameter.PRESS_CONT,
-    Parameter.PRESS_LOCK,
-    Parameter.PRESS_LONG,
-    Parameter.PRESS_LONG_RELEASE,
-    Parameter.PRESS_LONG_START,
-    Parameter.PRESS_SHORT,
-    Parameter.PRESS_UNLOCK,
+CLICK_EVENTS: Final[frozenset[Parameter]] = frozenset(
+    {
+        Parameter.PRESS,
+        Parameter.PRESS_CONT,
+        Parameter.PRESS_LOCK,
+        Parameter.PRESS_LONG,
+        Parameter.PRESS_LONG_RELEASE,
+        Parameter.PRESS_LONG_START,
+        Parameter.PRESS_SHORT,
+        Parameter.PRESS_UNLOCK,
+    }
 )
 
 DEVICE_ERROR_EVENTS: Final[tuple[Parameter, ...]] = (Parameter.ERROR, Parameter.SENSOR_ERROR)
 
-DATA_POINT_EVENTS: Final[tuple[EventType, ...]] = (
-    EventType.IMPULSE,
-    EventType.KEYPRESS,
+DATA_POINT_EVENTS: Final[frozenset[EventType]] = frozenset(
+    {
+        EventType.IMPULSE,
+        EventType.KEYPRESS,
+    }
 )
 
 
@@ -567,26 +593,34 @@ class DataPointKey(NamedTuple):
 type DP_KEY_VALUE = tuple[DataPointKey, Any]
 type SYSVAR_TYPE = bool | float | int | str | None
 
-HMIP_FIRMWARE_UPDATE_IN_PROGRESS_STATES: Final[tuple[DeviceFirmwareState, ...]] = (
-    DeviceFirmwareState.DO_UPDATE_PENDING,
-    DeviceFirmwareState.PERFORMING_UPDATE,
+HMIP_FIRMWARE_UPDATE_IN_PROGRESS_STATES: Final[frozenset[DeviceFirmwareState]] = frozenset(
+    {
+        DeviceFirmwareState.DO_UPDATE_PENDING,
+        DeviceFirmwareState.PERFORMING_UPDATE,
+    }
 )
 
-HMIP_FIRMWARE_UPDATE_READY_STATES: Final[tuple[DeviceFirmwareState, ...]] = (
-    DeviceFirmwareState.READY_FOR_UPDATE,
-    DeviceFirmwareState.DO_UPDATE_PENDING,
-    DeviceFirmwareState.PERFORMING_UPDATE,
+HMIP_FIRMWARE_UPDATE_READY_STATES: Final[frozenset[DeviceFirmwareState]] = frozenset(
+    {
+        DeviceFirmwareState.READY_FOR_UPDATE,
+        DeviceFirmwareState.DO_UPDATE_PENDING,
+        DeviceFirmwareState.PERFORMING_UPDATE,
+    }
 )
 
-IMPULSE_EVENTS: Final[tuple[Parameter, ...]] = (Parameter.SEQUENCE_OK,)
+IMPULSE_EVENTS: Final[frozenset[Parameter]] = frozenset({Parameter.SEQUENCE_OK})
 
-KEY_CHANNEL_OPERATION_MODE_VISIBILITY: Final[Mapping[str, tuple[str, ...]]] = {
-    Parameter.STATE: ("BINARY_BEHAVIOR",),
-    Parameter.PRESS_LONG: ("KEY_BEHAVIOR", "SWITCH_BEHAVIOR"),
-    Parameter.PRESS_LONG_RELEASE: ("KEY_BEHAVIOR", "SWITCH_BEHAVIOR"),
-    Parameter.PRESS_LONG_START: ("KEY_BEHAVIOR", "SWITCH_BEHAVIOR"),
-    Parameter.PRESS_SHORT: ("KEY_BEHAVIOR", "SWITCH_BEHAVIOR"),
-}
+KEY_CHANNEL_OPERATION_MODE_VISIBILITY: Final[Mapping[str, frozenset[str]]] = MappingProxyType(
+    {
+        Parameter.STATE: frozenset({"BINARY_BEHAVIOR"}),
+        Parameter.PRESS_LONG: frozenset({"KEY_BEHAVIOR", "SWITCH_BEHAVIOR"}),
+        Parameter.PRESS_LONG_RELEASE: frozenset({"KEY_BEHAVIOR", "SWITCH_BEHAVIOR"}),
+        Parameter.PRESS_LONG_START: frozenset({"KEY_BEHAVIOR", "SWITCH_BEHAVIOR"}),
+        Parameter.PRESS_SHORT: frozenset({"KEY_BEHAVIOR", "SWITCH_BEHAVIOR"}),
+    }
+)
+
+BLOCKED_CATEGORIES: Final[tuple[DataPointCategory, ...]] = (DataPointCategory.ACTION,)
 
 HUB_CATEGORIES: Final[tuple[DataPointCategory, ...]] = (
     DataPointCategory.HUB_BINARY_SENSOR,
@@ -616,42 +650,54 @@ CATEGORIES: Final[tuple[DataPointCategory, ...]] = (
     DataPointCategory.VALVE,
 )
 
-PRIMARY_CLIENT_CANDIDATE_INTERFACES: Final = (
-    Interface.HMIP_RF,
-    Interface.BIDCOS_RF,
-    Interface.BIDCOS_WIRED,
+PRIMARY_CLIENT_CANDIDATE_INTERFACES: Final[frozenset[Interface]] = frozenset(
+    {
+        Interface.HMIP_RF,
+        Interface.BIDCOS_RF,
+        Interface.BIDCOS_WIRED,
+    }
 )
 
-RELEVANT_INIT_PARAMETERS: Final[tuple[Parameter, ...]] = (
-    Parameter.CONFIG_PENDING,
-    Parameter.STICKY_UN_REACH,
-    Parameter.UN_REACH,
+RELEVANT_INIT_PARAMETERS: Final[frozenset[Parameter]] = frozenset(
+    {
+        Parameter.CONFIG_PENDING,
+        Parameter.STICKY_UN_REACH,
+        Parameter.UN_REACH,
+    }
 )
 
-INTERFACES_SUPPORTING_FIRMWARE_UPDATES: Final[tuple[Interface, ...]] = (
-    Interface.BIDCOS_RF,
-    Interface.BIDCOS_WIRED,
-    Interface.HMIP_RF,
+INTERFACES_SUPPORTING_FIRMWARE_UPDATES: Final[frozenset[Interface]] = frozenset(
+    {
+        Interface.BIDCOS_RF,
+        Interface.BIDCOS_WIRED,
+        Interface.HMIP_RF,
+    }
 )
 
-INTERFACES_SUPPORTING_XML_RPC: Final[tuple[Interface, ...]] = (
-    Interface.BIDCOS_RF,
-    Interface.BIDCOS_WIRED,
-    Interface.HMIP_RF,
-    Interface.VIRTUAL_DEVICES,
+INTERFACES_SUPPORTING_XML_RPC: Final[frozenset[Interface]] = frozenset(
+    {
+        Interface.BIDCOS_RF,
+        Interface.BIDCOS_WIRED,
+        Interface.HMIP_RF,
+        Interface.VIRTUAL_DEVICES,
+    }
 )
 
-INTERFACES_REQUIRING_PERIODIC_REFRESH: Final[tuple[Interface, ...]] = (
-    Interface.CCU_JACK,
-    Interface.CUXD,
+INTERFACES_REQUIRING_PERIODIC_REFRESH: Final[frozenset[Interface]] = frozenset(
+    {
+        Interface.CCU_JACK,
+        Interface.CUXD,
+    }
 )
 
 DEFAULT_USE_PERIODIC_SCAN_FOR_INTERFACES: Final = True
 
-IGNORE_FOR_UN_IGNORE_PARAMETERS: Final[tuple[Parameter, ...]] = (
-    Parameter.CONFIG_PENDING,
-    Parameter.STICKY_UN_REACH,
-    Parameter.UN_REACH,
+IGNORE_FOR_UN_IGNORE_PARAMETERS: Final[frozenset[Parameter]] = frozenset(
+    {
+        Parameter.CONFIG_PENDING,
+        Parameter.STICKY_UN_REACH,
+        Parameter.UN_REACH,
+    }
 )
 
 
@@ -659,12 +705,14 @@ IGNORE_FOR_UN_IGNORE_PARAMETERS: Final[tuple[Parameter, ...]] = (
 _IGNORE_ON_INITIAL_LOAD_PARAMETERS_END_RE: Final = re.compile(r".*(_ERROR)$")
 # Ignore Parameter on initial load that start with
 _IGNORE_ON_INITIAL_LOAD_PARAMETERS_START_RE: Final = re.compile(r"^(ERROR_|RSSI_)")
-_IGNORE_ON_INITIAL_LOAD_PARAMETERS: Final = (
-    Parameter.DUTY_CYCLE,
-    Parameter.DUTYCYCLE,
-    Parameter.LOW_BAT,
-    Parameter.LOWBAT,
-    Parameter.OPERATING_VOLTAGE,
+_IGNORE_ON_INITIAL_LOAD_PARAMETERS: Final[frozenset[Parameter]] = frozenset(
+    {
+        Parameter.DUTY_CYCLE,
+        Parameter.DUTYCYCLE,
+        Parameter.LOW_BAT,
+        Parameter.LOWBAT,
+        Parameter.OPERATING_VOLTAGE,
+    }
 )
 
 
@@ -793,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__
+    )
+)