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

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
@@ -280,6 +282,10 @@ class CalculatedDataPoint[ParameterT: GenericParameterType](BaseDataPoint):
         """Generate the usage for the data point."""
         return DataPointUsage.DATA_POINT
 
+    def _get_signature(self) -> str:
+        """Return the signature of the data_point."""
+        return f"{self._category}/{self._channel.device.model}/{self._calculated_parameter}"
+
     async def load_data_point_value(self, call_source: CallSource, direct_call: bool = False) -> None:
         """Init the data point values."""
         for dp in self._readable_data_points:
@@ -300,7 +306,7 @@ class CalculatedDataPoint[ParameterT: GenericParameterType](BaseDataPoint):
     @property
     def _should_fire_data_point_updated_callback(self) -> bool:
         """Check if a data point has been updated or refreshed."""
-        if self.fired_recently:  # pylint: disable=using-constant-test
+        if self.fired_recently:
             return False
 
         if (relevant_values_data_point := self._relevant_values_data_points) is not None and len(

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
@@ -177,6 +179,10 @@ class CustomDataPoint(BaseDataPoint):
             return DataPointUsage.CDP_PRIMARY
         return DataPointUsage.CDP_SECONDARY
 
+    def _get_signature(self) -> str:
+        """Return the signature of the data_point."""
+        return f"{self._category}/{self._channel.device.model}/{self.data_point_name_postfix}"
+
     async def load_data_point_value(self, call_source: CallSource, direct_call: bool = False) -> None:
         """Init the data point values."""
         for dp in self._readable_data_points:

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

aiohomematic/model/custom/light.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """Module for data points implemented using the light category."""
 
 from __future__ import annotations
@@ -471,29 +473,29 @@ class CustomDpIpRGBWLight(CustomDpDimmer):
     @property
     def _relevant_data_points(self) -> tuple[GenericDataPoint, ...]:
         """Returns the list of relevant data points. To be overridden by subclasses."""
-        if self._dp_device_operation_mode.value == _DeviceOperationMode.RGBW:
+        if self._device_operation_mode == _DeviceOperationMode.RGBW:
             return (
                 self._dp_hue,
                 self._dp_level,
                 self._dp_saturation,
                 self._dp_color_temperature_kelvin,
             )
-        if self._dp_device_operation_mode.value == _DeviceOperationMode.RGB:
+        if self._device_operation_mode == _DeviceOperationMode.RGB:
             return self._dp_hue, self._dp_level, self._dp_saturation
-        if self._dp_device_operation_mode.value == _DeviceOperationMode.TUNABLE_WHITE:
+        if self._device_operation_mode == _DeviceOperationMode.TUNABLE_WHITE:
             return self._dp_level, self._dp_color_temperature_kelvin
         return (self._dp_level,)
 
     @property
     def supports_color_temperature(self) -> bool:
         """Flag if light supports color temperature."""
-        return self._dp_device_operation_mode.value == _DeviceOperationMode.TUNABLE_WHITE
+        return self._device_operation_mode == _DeviceOperationMode.TUNABLE_WHITE
 
     @property
     def supports_effects(self) -> bool:
         """Flag if light supports effects."""
         return (
-            self._dp_device_operation_mode.value != _DeviceOperationMode.PWM
+            self._device_operation_mode != _DeviceOperationMode.PWM
             and self.effects is not None
             and len(self.effects) > 0
         )
@@ -501,7 +503,7 @@ class CustomDpIpRGBWLight(CustomDpDimmer):
     @property
     def supports_hs_color(self) -> bool:
         """Flag if light supports color."""
-        return self._dp_device_operation_mode.value in (
+        return self._device_operation_mode in (
             _DeviceOperationMode.RGBW,
             _DeviceOperationMode.RGB,
         )
@@ -514,11 +516,9 @@ class CustomDpIpRGBWLight(CustomDpDimmer):
         Avoid creating data points that are not usable in selected device operation mode.
         """
         if (
-            self._dp_device_operation_mode.value in (_DeviceOperationMode.RGB, _DeviceOperationMode.RGBW)
+            self._device_operation_mode in (_DeviceOperationMode.RGB, _DeviceOperationMode.RGBW)
             and self._channel.no in (2, 3, 4)
-        ) or (
-            self._dp_device_operation_mode.value == _DeviceOperationMode.TUNABLE_WHITE and self._channel.no in (3, 4)
-        ):
+        ) or (self._device_operation_mode == _DeviceOperationMode.TUNABLE_WHITE and self._channel.no in (3, 4)):
             return DataPointUsage.NO_CREATE
         return self._get_data_point_usage()
 
@@ -555,6 +555,13 @@ class CustomDpIpRGBWLight(CustomDpDimmer):
             await self._set_on_time_value(on_time=_NOT_USED, collector=collector)
         await super().turn_off(collector=collector, **kwargs)
 
+    @property
+    def _device_operation_mode(self) -> _DeviceOperationMode:
+        """Return the device operation mode."""
+        if (mode := self._dp_device_operation_mode.value) is None:
+            return _DeviceOperationMode.RGBW
+        return _DeviceOperationMode(mode)
+
     @bind_collector()
     async def _set_on_time_value(self, on_time: float, collector: CallParameterCollector | None = None) -> None:
         """Set the on time value in seconds."""
@@ -1068,6 +1075,7 @@ DEVICES: Mapping[str, CustomConfig | tuple[CustomConfig, ...]] = {
     "HmIP-FDT": CustomConfig(make_ce_func=make_ip_dimmer, channels=(2,)),
     "HmIP-PDT": CustomConfig(make_ce_func=make_ip_dimmer, channels=(3,)),
     "HmIP-RGBW": CustomConfig(make_ce_func=make_ip_rgbw_light),
+    "HmIP-LSC": CustomConfig(make_ce_func=make_ip_rgbw_light),
     "HmIP-SCTH230": CustomConfig(
         make_ce_func=make_ip_dimmer,
         channels=(12,),

aiohomematic/model/custom/lock.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """Module for data points implemented using the lock category."""
 
 from __future__ import annotations

aiohomematic/model/custom/siren.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """Module for data points implemented using the siren category."""
 
 from __future__ import annotations
@@ -8,6 +10,7 @@ from enum import StrEnum
 from typing import Final, TypedDict, Unpack
 
 from aiohomematic.const import DataPointCategory
+from aiohomematic.exceptions import ValidationException
 from aiohomematic.model import device as hmd
 from aiohomematic.model.custom import definition as hmed
 from aiohomematic.model.custom.const import DeviceProfile, Field
@@ -147,14 +150,14 @@ class CustomDpIpSiren(BaseCustomDpSiren):
 
         acoustic_alarm = kwargs.get("acoustic_alarm", self._dp_acoustic_alarm_selection.default)
         if self.available_tones and acoustic_alarm and acoustic_alarm not in self.available_tones:
-            raise ValueError(
+            raise ValidationException(
                 f"Invalid tone specified for data_point {self.full_name}: {acoustic_alarm}, "
                 "check the available_tones attribute for valid tones to pass in"
             )
 
         optical_alarm = kwargs.get("optical_alarm", self._dp_optical_alarm_selection.default)
         if self.available_lights and optical_alarm and optical_alarm not in self.available_lights:
-            raise ValueError(
+            raise ValidationException(
                 f"Invalid light specified for data_point {self.full_name}: {optical_alarm}, "
                 "check the available_lights attribute for valid tones to pass in"
             )

aiohomematic/model/custom/support.py

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

aiohomematic/model/custom/switch.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """Module for data points implemented using the switch category."""
 
 from __future__ import annotations

aiohomematic/model/custom/valve.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """Module for data points implemented using the valve category."""
 
 from __future__ import annotations

aiohomematic/model/data_point.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Core data point model for AioHomematic.
 
@@ -80,7 +82,6 @@ __all__ = [
     "BaseParameterDataPoint",
     "CallParameterCollector",
     "CallbackDataPoint",
-    "EVENT_DATA_SCHEMA",
     "bind_collector",
 ]
 
@@ -146,6 +147,7 @@ class CallbackDataPoint(ABC):
         "_modified_at",
         "_path_data",
         "_refreshed_at",
+        "_signature",
         "_temporary_modified_at",
         "_temporary_refreshed_at",
         "_unique_id",
@@ -164,6 +166,7 @@ class CallbackDataPoint(ABC):
         self._fired_at: datetime = INIT_DATETIME
         self._modified_at: datetime = INIT_DATETIME
         self._refreshed_at: datetime = INIT_DATETIME
+        self._signature: Final = self._get_signature()
         self._temporary_modified_at: datetime = INIT_DATETIME
         self._temporary_refreshed_at: datetime = INIT_DATETIME
 
@@ -252,6 +255,11 @@ class CallbackDataPoint(ABC):
     def name(self) -> str:
         """Return the name of the data_point."""
 
+    @property
+    def signature(self) -> str:
+        """Return the data_point signature."""
+        return self._signature
+
     @config_property
     def unique_id(self) -> str:
         """Return the unique_id."""
@@ -325,6 +333,10 @@ class CallbackDataPoint(ABC):
     def _get_path_data(self) -> PathData:
         """Return the path data."""
 
+    @abstractmethod
+    def _get_signature(self) -> str:
+        """Return the signature of the data_point."""
+
     def _unregister_data_point_updated_callback(self, cb: Callable, custom_id: str) -> None:
         """Unregister data_point updated callback."""
         if cb in self._data_point_updated_callbacks:
@@ -840,6 +852,10 @@ class BaseParameterDataPoint[
             return multiplier
         return DEFAULT_MULTIPLIER
 
+    def _get_signature(self) -> str:
+        """Return the signature of the data_point."""
+        return f"{self._category}/{self._channel.device.model}/{self._parameter}"
+
     @abstractmethod
     async def event(self, value: Any, received_at: datetime | None = None) -> None:
         """Handle event for which this handler has subscribed."""
@@ -1070,12 +1086,23 @@ def bind_collector(
                     IN_SERVICE_VAR.reset(token)
                 in_service = IN_SERVICE_VAR.get()
                 if not in_service and log_level > logging.NOTSET:
-                    logging.getLogger(args[0].__module__).log(level=log_level, msg=extract_exc_args(exc=bhexc))
+                    logger = logging.getLogger(args[0].__module__)
+                    extra = {
+                        "err_type": bhexc.__class__.__name__,
+                        "err": extract_exc_args(exc=bhexc),
+                        "function": func.__name__,
+                        **hms.build_log_context_from_obj(obj=args[0]),
+                    }
+                    if log_level >= logging.ERROR:
+                        logger.exception("service_error", extra=extra)
+                    else:
+                        logger.log(level=log_level, msg="service_error", extra=extra)
+                # Re-raise domain-specific exceptions so callers and tests can handle them
+                raise
             else:
                 if token:
                     IN_SERVICE_VAR.reset(token)
                 return return_value
-            return None
 
         setattr(bind_wrapper, "ha_service", True)
         return bind_wrapper  # type: ignore[return-value]