aiohomematic 2025.10.1__py3-none-any.whl → 2025.10.3__py3-none-any.whl

aiohomematic/model/data_point.py

@@ -44,6 +44,7 @@ from aiohomematic.const import (
     DP_KEY_VALUE,
     INIT_DATETIME,
     KEY_CHANNEL_OPERATION_MODE_VISIBILITY,
+    KWARGS_ARG_CUSTOM_ID,
     KWARGS_ARG_DATA_POINT,
     NO_CACHE_ENTRY,
     WAIT_FOR_CALLBACK,
@@ -142,7 +143,7 @@ class CallbackDataPoint(ABC, LogContextMixin):
         "_custom_id",
         "_data_point_updated_callbacks",
         "_device_removed_callbacks",
-        "_fired_at",
+        "_fired_event_at",
         "_modified_at",
         "_path_data",
         "_refreshed_at",
@@ -154,7 +155,7 @@ class CallbackDataPoint(ABC, LogContextMixin):
 
     _category = DataPointCategory.UNDEFINED
 
-    def __init__(self, central: hmcu.CentralUnit, unique_id: str) -> None:
+    def __init__(self, *, central: hmcu.CentralUnit, unique_id: str) -> None:
         """Init the callback data_point."""
         self._central: Final = central
         self._unique_id: Final = unique_id
@@ -162,7 +163,7 @@ class CallbackDataPoint(ABC, LogContextMixin):
         self._device_removed_callbacks: list[Callable] = []
         self._custom_id: str | None = None
         self._path_data = self._get_path_data()
-        self._fired_at: datetime = INIT_DATETIME
+        self._fired_event_at: datetime = INIT_DATETIME
         self._modified_at: datetime = INIT_DATETIME
         self._refreshed_at: datetime = INIT_DATETIME
         self._signature: Final = self._get_signature()
@@ -190,16 +191,16 @@ class CallbackDataPoint(ABC, LogContextMixin):
         return self._custom_id
 
     @property
-    def fired_at(self) -> datetime:
-        """Return the data point updated fired at."""
-        return self._fired_at
+    def fired_event_at(self) -> datetime:
+        """Return the data point updated fired an event at."""
+        return self._fired_event_at
 
     @state_property
-    def fired_recently(self) -> bool:
-        """Return the data point fired within 500 milliseconds."""
-        if self._fired_at == INIT_DATETIME:
+    def fired_event_recently(self) -> bool:
+        """Return the data point fired an event within 500 milliseconds."""
+        if self._fired_event_at == INIT_DATETIME:
             return False
-        return (datetime.now() - self._fired_at).total_seconds() < 0.5
+        return (datetime.now() - self._fired_event_at).total_seconds() < 0.5
 
     @classmethod
     def default_category(cls) -> DataPointCategory:
@@ -305,11 +306,11 @@ class CallbackDataPoint(ABC, LogContextMixin):
         """Return all service methods."""
         return tuple(self.service_methods.keys())
 
-    def register_internal_data_point_updated_callback(self, cb: Callable) -> CALLBACK_TYPE:
+    def register_internal_data_point_updated_callback(self, *, cb: Callable) -> CALLBACK_TYPE:
         """Register internal data_point updated callback."""
         return self.register_data_point_updated_callback(cb=cb, custom_id=DEFAULT_CUSTOM_ID)
 
-    def register_data_point_updated_callback(self, cb: Callable, custom_id: str) -> CALLBACK_TYPE:
+    def register_data_point_updated_callback(self, *, cb: Callable, custom_id: str) -> CALLBACK_TYPE:
         """Register data_point updated callback."""
         if custom_id != DEFAULT_CUSTOM_ID:
             if self._custom_id is not None and self._custom_id != custom_id:
@@ -336,45 +337,46 @@ class CallbackDataPoint(ABC, LogContextMixin):
     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:
+    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:
             del self._data_point_updated_callbacks[cb]
         if self.custom_id == custom_id:
             self._custom_id = None
 
-    def register_device_removed_callback(self, cb: Callable) -> CALLBACK_TYPE:
+    def register_device_removed_callback(self, *, cb: Callable) -> CALLBACK_TYPE:
         """Register the device removed callback."""
         if callable(cb) and cb not in self._device_removed_callbacks:
             self._device_removed_callbacks.append(cb)
             return partial(self._unregister_device_removed_callback, cb=cb)
         return None
 
-    def _unregister_device_removed_callback(self, cb: Callable) -> None:
+    def _unregister_device_removed_callback(self, *, cb: Callable) -> None:
         """Unregister the device removed callback."""
         if cb in self._device_removed_callbacks:
             self._device_removed_callbacks.remove(cb)
 
     @loop_check
-    def fire_data_point_updated_callback(self, *args: Any, **kwargs: Any) -> None:
+    def fire_data_point_updated_callback(self, **kwargs: Any) -> None:
         """Do what is needed when the value of the data_point has been updated/refreshed."""
         if not self._should_fire_data_point_updated_callback:
             return
-        self._fired_at = datetime.now()
-        # Add the data_point reference once to kwargs to avoid per-callback writes.
-        kwargs[KWARGS_ARG_DATA_POINT] = self
-        for callback_handler in self._data_point_updated_callbacks:
+        self._fired_event_at = datetime.now()
+        for callback_handler, custom_id in self._data_point_updated_callbacks.items():
             try:
-                callback_handler(*args, **kwargs)
+                # Add the data_point reference once to kwargs to avoid per-callback writes.
+                kwargs[KWARGS_ARG_DATA_POINT] = self
+                kwargs[KWARGS_ARG_CUSTOM_ID] = custom_id
+                callback_handler(**kwargs)
             except Exception as exc:
                 _LOGGER.warning("FIRE_DATA_POINT_UPDATED_EVENT failed: %s", extract_exc_args(exc=exc))
 
     @loop_check
-    def fire_device_removed_callback(self, *args: Any) -> None:
+    def fire_device_removed_callback(self) -> None:
         """Do what is needed when the data_point has been removed."""
         for callback_handler in self._device_removed_callbacks:
             try:
-                callback_handler(*args)
+                callback_handler()
             except Exception as exc:
                 _LOGGER.warning("FIRE_DEVICE_REMOVED_EVENT failed: %s", extract_exc_args(exc=exc))
 
@@ -383,21 +385,21 @@ class CallbackDataPoint(ABC, LogContextMixin):
         """Check if a data point has been updated or refreshed."""
         return True
 
-    def _set_modified_at(self, modified_at: datetime) -> None:
+    def _set_modified_at(self, *, modified_at: datetime) -> None:
         """Set modified_at to current datetime."""
         self._modified_at = modified_at
         self._set_refreshed_at(refreshed_at=modified_at)
 
-    def _set_refreshed_at(self, refreshed_at: datetime) -> None:
+    def _set_refreshed_at(self, *, refreshed_at: datetime) -> None:
         """Set refreshed_at to current datetime."""
         self._refreshed_at = refreshed_at
 
-    def _set_temporary_modified_at(self, modified_at: datetime) -> None:
+    def _set_temporary_modified_at(self, *, modified_at: datetime) -> None:
         """Set temporary_modified_at to current datetime."""
         self._temporary_modified_at = modified_at
         self._set_temporary_refreshed_at(refreshed_at=modified_at)
 
-    def _set_temporary_refreshed_at(self, refreshed_at: datetime) -> None:
+    def _set_temporary_refreshed_at(self, *, refreshed_at: datetime) -> None:
         """Set temporary_refreshed_at to current datetime."""
         self._temporary_refreshed_at = refreshed_at
 
@@ -426,6 +428,7 @@ class BaseDataPoint(CallbackDataPoint, PayloadMixin):
 
     def __init__(
         self,
+        *,
         channel: hmd.Channel,
         unique_id: str,
         is_in_multiple_channels: bool,
@@ -507,7 +510,7 @@ class BaseDataPoint(CallbackDataPoint, PayloadMixin):
         """Return the data_point usage."""
         return self._get_data_point_usage()
 
-    def force_usage(self, forced_usage: DataPointUsage) -> None:
+    def force_usage(self, *, forced_usage: DataPointUsage) -> None:
         """Set the data_point usage."""
         self._forced_usage = forced_usage
 
@@ -525,7 +528,7 @@ class BaseDataPoint(CallbackDataPoint, PayloadMixin):
         return on_time
 
     @abstractmethod
-    async def load_data_point_value(self, call_source: CallSource, direct_call: bool = False) -> None:
+    async def load_data_point_value(self, *, call_source: CallSource, direct_call: bool = False) -> None:
         """Init the data_point data."""
 
     @abstractmethod
@@ -536,7 +539,7 @@ class BaseDataPoint(CallbackDataPoint, PayloadMixin):
     def _get_data_point_usage(self) -> DataPointUsage:
         """Generate the usage for the data_point."""
 
-    def set_timer_on_time(self, on_time: float) -> None:
+    def set_timer_on_time(self, *, on_time: float) -> None:
         """Set the on_time."""
         self._timer_on_time = on_time
         self._timer_on_time_end = INIT_DATETIME
@@ -580,6 +583,7 @@ class BaseParameterDataPoint[
 
     def __init__(
         self,
+        *,
         channel: hmd.Channel,
         paramset_key: ParamsetKey,
         parameter: str,
@@ -618,13 +622,13 @@ class BaseParameterDataPoint[
         self._is_forced_sensor: bool = False
         self._assign_parameter_data(parameter_data=parameter_data)
 
-    def _assign_parameter_data(self, parameter_data: ParameterData) -> None:
+    def _assign_parameter_data(self, *, parameter_data: ParameterData) -> None:
         """Assign parameter data to instance variables."""
         self._type: ParameterType = ParameterType(parameter_data["TYPE"])
         self._values = tuple(parameter_data["VALUE_LIST"]) if parameter_data.get("VALUE_LIST") else None
-        self._max: ParameterT = self._convert_value(parameter_data["MAX"])
-        self._min: ParameterT = self._convert_value(parameter_data["MIN"])
-        self._default: ParameterT = self._convert_value(parameter_data.get("DEFAULT")) or self._min
+        self._max: ParameterT = self._convert_value(value=parameter_data["MAX"])
+        self._min: ParameterT = self._convert_value(value=parameter_data["MIN"])
+        self._default: ParameterT = self._convert_value(value=parameter_data.get("DEFAULT")) or self._min
         flags: int = parameter_data["FLAGS"]
         self._visible: bool = flags & Flag.VISIBLE == Flag.VISIBLE
         self._service: bool = flags & Flag.SERVICE == Flag.SERVICE
@@ -832,7 +836,7 @@ class BaseParameterDataPoint[
         )
         self._is_forced_sensor = True
 
-    def _cleanup_unit(self, raw_unit: str | None) -> str | None:
+    def _cleanup_unit(self, *, raw_unit: str | None) -> str | None:
         """Replace given unit."""
         if new_unit := _FIX_UNIT_BY_PARAM.get(self._parameter):
             return new_unit
@@ -843,7 +847,7 @@ class BaseParameterDataPoint[
                 return fix
         return raw_unit
 
-    def _get_multiplier(self, raw_unit: str | None) -> float:
+    def _get_multiplier(self, *, raw_unit: str | None) -> float:
         """Replace given unit."""
         if not raw_unit:
             return DEFAULT_MULTIPLIER
@@ -856,10 +860,10 @@ class BaseParameterDataPoint[
         return f"{self._category}/{self._channel.device.model}/{self._parameter}"
 
     @abstractmethod
-    async def event(self, value: Any, received_at: datetime) -> None:
+    async def event(self, *, value: Any, received_at: datetime) -> None:
         """Handle event for which this handler has subscribed."""
 
-    async def load_data_point_value(self, call_source: CallSource, direct_call: bool = False) -> None:
+    async def load_data_point_value(self, *, call_source: CallSource, direct_call: bool = False) -> None:
         """Init the data_point data."""
         if (self._ignore_on_initial_load or self._channel.device.ignore_on_initial_load) and call_source in (
             CallSource.HM_INIT,
@@ -883,7 +887,7 @@ class BaseParameterDataPoint[
             write_at=datetime.now(),
         )
 
-    def write_value(self, value: Any, write_at: datetime) -> tuple[ParameterT, ParameterT]:
+    def write_value(self, *, value: Any, write_at: datetime) -> tuple[ParameterT, ParameterT]:
         """Update value of the data_point."""
         self._reset_temporary_value()
 
@@ -894,7 +898,7 @@ class BaseParameterDataPoint[
                 self.fire_data_point_updated_callback()
             return (old_value, None)  # type: ignore[return-value]
 
-        new_value = self._convert_value(value)
+        new_value = self._convert_value(value=value)
         if old_value == new_value:
             self._set_refreshed_at(refreshed_at=write_at)
         else:
@@ -905,11 +909,11 @@ class BaseParameterDataPoint[
         self.fire_data_point_updated_callback()
         return (old_value, new_value)
 
-    def write_temporary_value(self, value: Any, write_at: datetime) -> None:
+    def write_temporary_value(self, *, value: Any, write_at: datetime) -> None:
         """Update the temporary value of the data_point."""
         self._reset_temporary_value()
 
-        temp_value = self._convert_value(value)
+        temp_value = self._convert_value(value=value)
         if self._value == temp_value:
             self._set_temporary_refreshed_at(refreshed_at=write_at)
         else:
@@ -928,7 +932,7 @@ class BaseParameterDataPoint[
         ):
             self._assign_parameter_data(parameter_data=parameter_data)
 
-    def _convert_value(self, value: Any) -> ParameterT:
+    def _convert_value(self, *, value: Any) -> ParameterT:
         """Convert to value to ParameterT."""
         if value is None:
             return None  # type: ignore[return-value]
@@ -963,7 +967,7 @@ class BaseParameterDataPoint[
         self._temporary_value = None  # type: ignore[assignment]
         self._reset_temporary_timestamps()
 
-    def get_event_data(self, value: Any = None) -> dict[EventKey, Any]:
+    def get_event_data(self, *, value: Any = None) -> dict[EventKey, Any]:
         """Get the event_data."""
         event_data = {
             EventKey.ADDRESS: self._device.address,
@@ -986,7 +990,7 @@ class CallParameterCollector:
         "_paramsets",
     )
 
-    def __init__(self, client: hmcl.Client) -> None:
+    def __init__(self, *, client: hmcl.Client) -> None:
         """Init the generator."""
         self._client: Final = client
         self._central: Final = client.central
@@ -995,6 +999,7 @@ class CallParameterCollector:
 
     def add_data_point(
         self,
+        *,
         data_point: BaseParameterDataPoint,
         value: Any,
         collector_order: int,
@@ -1010,7 +1015,7 @@ class CallParameterCollector:
             value
         )
 
-    async def send_data(self, wait_for_callback: int | None) -> set[DP_KEY_VALUE]:
+    async def send_data(self, *, wait_for_callback: int | None) -> set[DP_KEY_VALUE]:
         """Send data to the backend."""
         dpk_values: set[DP_KEY_VALUE] = set()
         for paramset_key, paramsets in self._paramsets.items():
@@ -1040,6 +1045,7 @@ class CallParameterCollector:
 
 
 def bind_collector(
+    *,
     wait_for_callback: int | None = WAIT_FOR_CALLBACK,
     enabled: bool = True,
     log_level: int = logging.ERROR,
@@ -1052,7 +1058,12 @@ def bind_collector(
 
     def bind_decorator[CallableT: Callable[..., Any]](func: CallableT) -> CallableT:
         """Decorate function to automatically add collector if not set."""
-        argument_index = getfullargspec(func).args.index(_COLLECTOR_ARGUMENT_NAME)
+        spec = getfullargspec(func)
+        # Support both positional and keyword-only 'collector' parameters
+        if _COLLECTOR_ARGUMENT_NAME in spec.args:
+            argument_index: int | None = spec.args.index(_COLLECTOR_ARGUMENT_NAME)
+        else:
+            argument_index = None
 
         @wraps(func)
         async def bind_wrapper(*args: Any, **kwargs: Any) -> Any:
@@ -1067,8 +1078,10 @@ def bind_collector(
                         IN_SERVICE_VAR.reset(token)
                     return return_value
                 try:
-                    collector_exists = args[argument_index] is not None
-                except IndexError:
+                    collector_exists = (
+                        argument_index is not None and len(args) > argument_index and args[argument_index] is not None
+                    ) or kwargs.get(_COLLECTOR_ARGUMENT_NAME) is not None
+                except Exception:
                     collector_exists = kwargs.get(_COLLECTOR_ARGUMENT_NAME) is not None
 
                 if collector_exists:
@@ -1127,6 +1140,7 @@ class NoneTypeDataPoint:
 
     async def send_value(
         self,
+        *,
         value: Any,
         collector: CallParameterCollector | None = None,
         do_validate: bool = True,