aiohomematic 2025.9.2__py3-none-any.whl → 2025.9.3__py3-none-any.whl

aiohomematic/client/__init__.py

@@ -93,7 +93,7 @@ from aiohomematic.decorators import inspector, measure_execution_time
 from aiohomematic.exceptions import BaseHomematicException, ClientException, NoConnectionException
 from aiohomematic.model.device import Device
 from aiohomematic.model.support import convert_value
-from aiohomematic.property_decorators import info_property
+from aiohomematic.property_decorators import hm_property
 from aiohomematic.support import (
     LogContextMixin,
     build_xml_rpc_headers,
@@ -171,7 +171,7 @@ class Client(ABC, LogContextMixin):
         """Return the interface of the client."""
         return self._config.interface
 
-    @info_property(log_context=True)
+    @hm_property(log_context=True)
     def interface_id(self) -> str:
         """Return the interface id of the client."""
         return self._config.interface_id

aiohomematic/client/json_rpc.py

@@ -91,7 +91,7 @@ from aiohomematic.exceptions import (
     UnsupportedException,
 )
 from aiohomematic.model.support import convert_value
-from aiohomematic.property_decorators import info_property
+from aiohomematic.property_decorators import hm_property
 from aiohomematic.support import (
     LogContextMixin,
     cleanup_text_from_html_tags,
@@ -217,12 +217,12 @@ class JsonRpcAioHttpClient(LogContextMixin):
         """If session exists, then it is activated."""
         return self._session_id is not None
 
-    @info_property(log_context=True)
+    @hm_property(log_context=True)
     def url(self) -> str | None:
         """Return url."""
         return self._url
 
-    @info_property(log_context=True)
+    @hm_property(log_context=True)
     def tls(self) -> bool:
         """Return tls."""
         return self._tls

aiohomematic/client/xml_rpc.py

@@ -42,7 +42,7 @@ from aiohomematic.exceptions import (
     NoConnectionException,
     UnsupportedException,
 )
-from aiohomematic.property_decorators import info_property
+from aiohomematic.property_decorators import hm_property
 from aiohomematic.support import LogContextMixin, extract_exc_args, get_tls_context, log_boundary_error
 
 _LOGGER: Final = logging.getLogger(__name__)
@@ -121,7 +121,7 @@ class XmlRpcProxy(xmlrpc.client.ServerProxy, LogContextMixin):
             supported_methods.append(_XmlRpcMethod.PING)
             self._supported_methods = tuple(supported_methods)
 
-    @info_property(log_context=True)
+    @hm_property(log_context=True)
     def interface_id(self) -> str:
         """Return the interface_id."""
         return self._interface_id
@@ -131,7 +131,7 @@ class XmlRpcProxy(xmlrpc.client.ServerProxy, LogContextMixin):
         """Return the supported methods."""
         return self._supported_methods
 
-    @info_property(log_context=True)
+    @hm_property(log_context=True)
     def tls(self) -> bool:
         """Return tls."""
         return self._tls

aiohomematic/const.py

@@ -19,7 +19,7 @@ import sys
 from types import MappingProxyType
 from typing import Any, Final, NamedTuple, Required, TypeAlias, TypedDict
 
-VERSION: Final = "2025.9.2"
+VERSION: Final = "2025.9.3"
 
 # Detect test speedup mode via environment
 _TEST_SPEEDUP: Final = (

aiohomematic/model/calculated/data_point.py

@@ -32,7 +32,7 @@ from aiohomematic.model.support import (
     generate_unique_id,
     get_data_point_name_data,
 )
-from aiohomematic.property_decorators import cached_slot_property, config_property, state_property
+from aiohomematic.property_decorators import cached_property, config_property, state_property
 
 _LOGGER: Final = logging.getLogger(__name__)
 
@@ -147,7 +147,7 @@ class CalculatedDataPoint[ParameterT: GenericParameterType](BaseDataPoint):
         """Return default value."""
         return self._default
 
-    @cached_slot_property
+    @cached_property
     def dpk(self) -> DataPointKey:
         """Return data_point key value."""
         return DataPointKey(

aiohomematic/model/data_point.py

@@ -73,7 +73,7 @@ from aiohomematic.model.support import (
     convert_value,
     generate_unique_id,
 )
-from aiohomematic.property_decorators import cached_slot_property, config_property, info_property, state_property
+from aiohomematic.property_decorators import cached_property, config_property, hm_property, state_property
 from aiohomematic.support import LogContextMixin, PayloadMixin, extract_exc_args, log_boundary_error
 
 __all__ = [
@@ -269,7 +269,7 @@ class CallbackDataPoint(ABC, LogContextMixin):
         """Return the data_point usage."""
         return DataPointUsage.DATA_POINT
 
-    @cached_slot_property
+    @cached_property
     def enabled_default(self) -> bool:
         """Return, if data_point should be enabled based on usage attribute."""
         return self.usage in (
@@ -295,12 +295,12 @@ class CallbackDataPoint(ABC, LogContextMixin):
         return self._path_data.state_path
 
     # @property
-    @cached_slot_property
+    @cached_property
     def service_methods(self) -> Mapping[str, Callable]:
         """Return all service methods."""
         return get_service_calls(obj=self)
 
-    @cached_slot_property
+    @cached_property
     def service_method_names(self) -> tuple[str, ...]:
         """Return all service methods."""
         return tuple(self.service_methods.keys())
@@ -447,7 +447,7 @@ class BaseDataPoint(CallbackDataPoint, PayloadMixin):
         """Return the availability of the device."""
         return self._device.available
 
-    @info_property(log_context=True)
+    @hm_property(log_context=True)
     def channel(self) -> hmd.Channel:
         """Return the channel the data_point."""
         return self._channel
@@ -659,7 +659,7 @@ class BaseParameterDataPoint[
         """Return if the parameter is un ignored."""
         return self._is_un_ignored
 
-    @cached_slot_property
+    @cached_property
     def dpk(self) -> DataPointKey:
         """Return data_point key value."""
         return DataPointKey(
@@ -684,7 +684,7 @@ class BaseParameterDataPoint[
         """Return multiplier value."""
         return self._multiplier
 
-    @info_property(log_context=True)
+    @hm_property(log_context=True)
     def parameter(self) -> str:
         """Return parameter name."""
         return self._parameter
@@ -699,7 +699,7 @@ class BaseParameterDataPoint[
         """Return raw unit value."""
         return self._raw_unit
 
-    @cached_slot_property
+    @cached_property
     def requires_polling(self) -> bool:
         """Return whether the data_point requires polling."""
         return not self._channel.device.client.supports_push_updates or (
@@ -785,7 +785,7 @@ class BaseParameterDataPoint[
         """Return the if data_point is visible in ccu."""
         return self._visible
 
-    @cached_slot_property
+    @cached_property
     def _enabled_by_channel_operation_mode(self) -> bool | None:
         """Return, if the data_point/event must be enabled."""
         if self._channel.type_name not in _CONFIGURABLE_CHANNEL:

aiohomematic/model/device.py

@@ -80,7 +80,7 @@ from aiohomematic.model.support import (
     get_device_name,
 )
 from aiohomematic.model.update import DpUpdate
-from aiohomematic.property_decorators import cached_slot_property, info_property, state_property
+from aiohomematic.property_decorators import cached_property, hm_property, info_property, state_property
 from aiohomematic.support import (
     CacheEntry,
     LogContextMixin,
@@ -327,7 +327,7 @@ class Device(LogContextMixin, PayloadMixin):
         """Return the interface of the device."""
         return self._interface
 
-    @info_property(log_context=True)
+    @hm_property(log_context=True)
     def interface_id(self) -> str:
         """Return the interface_id of the device."""
         return self._interface_id
@@ -441,7 +441,7 @@ class Device(LogContextMixin, PayloadMixin):
             for channel in self._channels.values():
                 await channel.remove_central_link()
 
-    @cached_slot_property
+    @cached_property
     def relevant_for_central_link_management(self) -> bool:
         """Return if channel is relevant for central link management."""
         return (
@@ -762,7 +762,7 @@ class Channel(LogContextMixin, PayloadMixin):
         """Return the device description for the channel."""
         return self._description
 
-    @info_property(log_context=True)
+    @hm_property(log_context=True)
     def device(self) -> Device:
         """Return the device of the channel."""
         return self._device
@@ -832,7 +832,7 @@ class Channel(LogContextMixin, PayloadMixin):
         """Return the name data of the channel."""
         return self._name_data
 
-    @info_property(log_context=True)
+    @hm_property(log_context=True)
     def no(self) -> int | None:
         """Return the channel_no of the channel."""
         return self._no

aiohomematic/model/generic/data_point.py

@@ -21,7 +21,7 @@ from aiohomematic.decorators import inspector
 from aiohomematic.exceptions import ValidationException
 from aiohomematic.model import data_point as hme, device as hmd
 from aiohomematic.model.support import DataPointNameData, GenericParameterType, get_data_point_name_data
-from aiohomematic.property_decorators import cached_slot_property
+from aiohomematic.property_decorators import cached_property
 
 _LOGGER: Final = logging.getLogger(__name__)
 
@@ -51,7 +51,7 @@ class GenericDataPoint[ParameterT: GenericParameterType, InputParameterT: Generi
             parameter_data=parameter_data,
         )
 
-    @cached_slot_property
+    @cached_property
     def usage(self) -> DataPointUsage:
         """Return the data_point usage."""
         if self._is_forced_sensor or self._is_un_ignored:

aiohomematic/property_decorators.py

@@ -1,22 +1,39 @@
 # SPDX-License-Identifier: MIT
 # Copyright (c) 2021-2025 Daniel Perna, SukramJ
-"""Decorators for data points used within aiohomematic."""
+"""
+Decorators and helpers for declaring public attributes on data point classes.
+
+This module provides four decorator factories that behave like the built-in
+@property, but additionally annotate properties with a semantic category so they
+can be automatically collected to build payloads and log contexts:
+- cached_property: computed once per instance and cached until the value is
+  invalidated by a setter/deleter on the same descriptor.
+- config_property: configuration-related properties.
+- info_property: informational/metadata properties.
+- state_property: dynamic state properties.
+
+All decorators accept an optional keyword-only argument log_context. If set to
+True, the property will be included in the LogContextMixin.log_context mapping.
+
+Notes on caching
+- cached_property always caches on first access and invalidates on set/delete.
+- The other decorators can be created with cached=True to enable the same
+  behavior when desired.
+"""
 
 from __future__ import annotations
 
 from collections.abc import Callable, Mapping
 from datetime import datetime
-from enum import Enum
-from typing import Any, ParamSpec, TypeVar, cast, overload
+from enum import Enum, StrEnum
+from typing import Any, Final, ParamSpec, TypeVar, cast, overload
 from weakref import WeakKeyDictionary
 
 from aiohomematic import support as hms
 
 __all__ = [
     "config_property",
-    "get_attributes_for_config_property",
-    "get_attributes_for_info_property",
-    "get_attributes_for_state_property",
+    "get_hm_property_by_kind",
     "info_property",
     "state_property",
 ]
@@ -26,8 +43,30 @@ T = TypeVar("T")
 R = TypeVar("R")
 
 
+class Kind(StrEnum):
+    """Enum for property feature flags."""
+
+    CONFIG = "config"
+    INFO = "info"
+    SIMPLE = "simple"
+    STATE = "state"
+
+
 class _GenericProperty[GETTER, SETTER](property):
-    """Generic property implementation."""
+    """
+    Base descriptor used by all property decorators in this module.
+
+    Extends the built-in property to optionally cache the computed value on the
+    instance and to carry a log_context flag.
+
+    Args:
+    - fget/fset/fdel: Standard property callables.
+    - doc: Optional docstring of the property.
+    - cached: If True, the computed value is cached per instance and
+      invalidated when the descriptor receives a set/delete.
+    - log_context: If True, the property is included in get_attributes_for_log_context().
+
+    """
 
     fget: Callable[[Any], GETTER] | None
     fset: Callable[[Any, SETTER], None] | None
@@ -39,210 +78,377 @@ class _GenericProperty[GETTER, SETTER](property):
         fset: Callable[[Any, SETTER], None] | None = None,
         fdel: Callable[[Any], None] | None = None,
         doc: str | None = None,
+        kind: Kind = Kind.SIMPLE,
+        cached: bool = False,
         log_context: bool = False,
     ) -> None:
-        """Init the generic property."""
+        """
+        Initialize the descriptor.
+
+        Mirrors the standard property signature and adds two options:
+        - kind: specify the kind of property (e.g. simple, cached, config, info, state).
+        - cached: enable per-instance caching of the computed value.
+        - log_context: mark this property as relevant for structured logging.
+        """
         super().__init__(fget, fset, fdel, doc)
         if doc is None and fget is not None:
             doc = fget.__doc__
         self.__doc__ = doc
+        self.kind: Final = kind
+        self._cached: Final = cached
         self.log_context = log_context
+        if cached:
+            if fget is not None:
+                func_name = fget.__name__
+            elif fset is not None:
+                func_name = fset.__name__
+            elif fdel is not None:
+                func_name = fdel.__name__
+            else:
+                func_name = "prop"
+            self._cache_attr = f"_cached_{func_name}"  # Default name of the cache attribute
 
     def getter(self, fget: Callable[[Any], GETTER], /) -> _GenericProperty:
         """Return generic getter."""
-        return type(self)(fget, self.fset, self.fdel, self.__doc__)  # pragma: no cover
+        return type(self)(
+            fget=fget,
+            fset=self.fset,
+            fdel=self.fdel,
+            doc=self.__doc__,
+            kind=self.kind,
+            cached=self._cached,
+            log_context=self.log_context,
+        )  # pragma: no cover
 
     def setter(self, fset: Callable[[Any, SETTER], None], /) -> _GenericProperty:
         """Return generic setter."""
-        return type(self)(self.fget, fset, self.fdel, self.__doc__)
+        return type(self)(
+            fget=self.fget,
+            fset=fset,
+            fdel=self.fdel,
+            doc=self.__doc__,
+            kind=self.kind,
+            cached=self._cached,
+            log_context=self.log_context,
+        )
 
     def deleter(self, fdel: Callable[[Any], None], /) -> _GenericProperty:
         """Return generic deleter."""
-        return type(self)(self.fget, self.fset, fdel, self.__doc__)
-
-    def __get__(self, obj: Any, gtype: type | None = None, /) -> GETTER:  # type: ignore[override]
-        """Return the attribute."""
-        if obj is None:
-            return self  # type: ignore[return-value]
+        return type(self)(
+            fget=self.fget,
+            fset=self.fset,
+            fdel=fdel,
+            doc=self.__doc__,
+            kind=self.kind,
+            cached=self._cached,
+            log_context=self.log_context,
+        )
+
+    def __get__(self, instance: Any, gtype: type | None = None, /) -> GETTER:  # type: ignore[override]
+        """
+        Return the attribute value.
+
+        If caching is enabled, compute on first access and return the per-instance
+        cached value on subsequent accesses.
+        """
+        if instance is None:
+            # Accessed from class, return the descriptor itself
+            return cast(GETTER, self)
         if self.fget is None:
             raise AttributeError("unreadable attribute")  # pragma: no cover
-        return self.fget(obj)
 
-    def __set__(self, obj: Any, value: Any, /) -> None:
-        """Set the attribute."""
+        if not self._cached:
+            return self.fget(instance)
+
+        # If the cached value is not set yet, compute and store it
+        if not hasattr(instance, self._cache_attr):
+            value = self.fget(instance)
+            setattr(instance, self._cache_attr, value)
+
+        # Return the cached value
+        return cast(GETTER, getattr(instance, self._cache_attr))
+
+    def __set__(self, instance: Any, value: Any, /) -> None:
+        """Set the attribute value and invalidate cache if enabled."""
+        # Delete the cached value so it can be recomputed on next access.
+        if self._cached and hasattr(instance, self._cache_attr):
+            delattr(instance, self._cache_attr)
+
         if self.fset is None:
             raise AttributeError("can't set attribute")  # pragma: no cover
-        self.fset(obj, value)
+        self.fset(instance, value)
+
+    def __delete__(self, instance: Any, /) -> None:
+        """Delete the attribute and invalidate cache if enabled."""
+
+        # Delete the cached value so it can be recomputed on next access.
+        if self._cached and hasattr(instance, self._cache_attr):
+            delattr(instance, self._cache_attr)
 
-    def __delete__(self, obj: Any, /) -> None:
-        """Delete the attribute."""
         if self.fdel is None:
             raise AttributeError("can't delete attribute")  # pragma: no cover
-        self.fdel(obj)
+        self.fdel(instance)
 
 
-# ----- config_property -----
+# ----- hm_property -----
 
 
-class _ConfigProperty[GETTER, SETTER](_GenericProperty[GETTER, SETTER]):
-    """Decorate to mark own config properties."""
+@overload
+def hm_property[PR](func: Callable[[Any], PR], /) -> _GenericProperty[PR, Any]: ...
 
 
 @overload
-def config_property[PR](func: Callable[[Any], PR], /) -> _ConfigProperty[PR, Any]: ...
+def hm_property(
+    *, kind: Kind = ..., cached: bool = ..., log_context: bool = ...
+) -> Callable[[Callable[[Any], R]], _GenericProperty[R, Any]]: ...
+
+
+def hm_property[PR](
+    func: Callable[[Any], PR] | None = None,
+    *,
+    kind: Kind = Kind.SIMPLE,
+    cached: bool = False,
+    log_context: bool = False,
+) -> _GenericProperty[PR, Any] | Callable[[Callable[[Any], PR]], _GenericProperty[PR, Any]]:
+    """
+    Decorate a method as a computed attribute.
+
+    Supports both usages:
+    - @hm_property
+    - @hm_property(kind=..., cached=True, log_context=True)
+
+    Args:
+        func: The function being decorated when used as @hm_property without
+            parentheses. When used as a factory (i.e., @hm_property(...)), this
+            is None and the returned callable expects the function to decorate.
+        kind: Specify the kind of property (e.g. simple, config, info, state).
+        cached: Optionally enable per-instance caching for this property.
+        log_context: Include this property in structured log context if True.
+
+    """
+    if func is None:
+
+        def wrapper(f: Callable[[Any], PR]) -> _GenericProperty[PR, Any]:
+            return _GenericProperty(f, kind=kind, cached=cached, log_context=log_context)
+
+        return wrapper
+    return _GenericProperty(func, kind=kind, cached=cached, log_context=log_context)
+
+
+# ----- cached_property -----
 
 
 @overload
-def config_property(*, log_context: bool = ...) -> Callable[[Callable[[Any], R]], _ConfigProperty[R, Any]]: ...
+def cached_property[PR](func: Callable[[Any], PR], /) -> _GenericProperty[PR, Any]: ...
 
 
-def config_property[PR](
+@overload
+def cached_property(*, log_context: bool = ...) -> Callable[[Callable[[Any], R]], _GenericProperty[R, Any]]: ...
+
+
+def cached_property[PR](
     func: Callable[[Any], PR] | None = None,
     *,
     log_context: bool = False,
-) -> _ConfigProperty[PR, Any] | Callable[[Callable[[Any], PR]], _ConfigProperty[PR, Any]]:
+) -> _GenericProperty[PR, Any] | Callable[[Callable[[Any], PR]], _GenericProperty[PR, Any]]:
     """
-    Return an instance of _ConfigProperty wrapping the given function.
+    Decorate a method as a computed attribute with per-instance caching.
+
+    Supports both usages:
+    - @cached_property
+    - @cached_property(log_context=True)
+
+    Args:
+        func: The function being decorated when used as @cached_property without
+            parentheses. When used as a factory (i.e., @cached_property(...)), this
+            is None and the returned callable expects the function to decorate.
+        log_context: Include this property in structured log context if True.
 
-    Decorator for config properties supporting both usages:
-    - @config_property
-    - @config_property(log_context=True)
     """
     if func is None:
 
-        def wrapper(f: Callable[[Any], PR]) -> _ConfigProperty[PR, Any]:
-            return _ConfigProperty(f, log_context=log_context)
+        def wrapper(f: Callable[[Any], PR]) -> _GenericProperty[PR, Any]:
+            return _GenericProperty(f, kind=Kind.SIMPLE, cached=True, log_context=log_context)
 
         return wrapper
-    return _ConfigProperty(func, log_context=log_context)
+    return _GenericProperty(func, kind=Kind.SIMPLE, cached=True, log_context=log_context)
 
 
-# Expose the underlying property class for discovery
-setattr(config_property, "__property_class__", _ConfigProperty)
+# ----- config_property -----
 
 
-# ----- info_property -----
+@overload
+def config_property[PR](func: Callable[[Any], PR], /) -> _GenericProperty[PR, Any]: ...
+
+
+@overload
+def config_property(
+    *, cached: bool = ..., log_context: bool = ...
+) -> Callable[[Callable[[Any], R]], _GenericProperty[R, Any]]: ...
 
 
-class _InfoProperty[GETTER, SETTER](_GenericProperty[GETTER, SETTER]):
-    """Decorate to mark own info properties."""
+def config_property[PR](
+    func: Callable[[Any], PR] | None = None,
+    *,
+    cached: bool = False,
+    log_context: bool = False,
+) -> _GenericProperty[PR, Any] | Callable[[Callable[[Any], PR]], _GenericProperty[PR, Any]]:
+    """
+    Decorate a method as a configuration property.
+
+    Supports both usages:
+    - @config_property
+    - @config_property(cached=True, log_context=True)
+
+    Args:
+        func: The function being decorated when used as @config_property without
+            parentheses. When used as a factory (i.e., @config_property(...)), this is
+            None and the returned callable expects the function to decorate.
+        cached: Enable per-instance caching for this property when True.
+        log_context: Include this property in structured log context if True.
+
+    """
+    if func is None:
+
+        def wrapper(f: Callable[[Any], PR]) -> _GenericProperty[PR, Any]:
+            return _GenericProperty(f, kind=Kind.CONFIG, cached=cached, log_context=log_context)
+
+        return wrapper
+    return _GenericProperty(func, kind=Kind.CONFIG, cached=cached, log_context=log_context)
+
+
+# ----- info_property -----
 
 
 @overload
-def info_property[PR](func: Callable[[Any], PR], /) -> _InfoProperty[PR, Any]: ...
+def info_property[PR](func: Callable[[Any], PR], /) -> _GenericProperty[PR, Any]: ...
 
 
 @overload
-def info_property(*, log_context: bool = ...) -> Callable[[Callable[[Any], R]], _InfoProperty[R, Any]]: ...
+def info_property(
+    *, cached: bool = ..., log_context: bool = ...
+) -> Callable[[Callable[[Any], R]], _GenericProperty[R, Any]]: ...
 
 
 def info_property[PR](
     func: Callable[[Any], PR] | None = None,
     *,
+    cached: bool = False,
     log_context: bool = False,
-) -> _InfoProperty[PR, Any] | Callable[[Callable[[Any], PR]], _InfoProperty[PR, Any]]:
+) -> _GenericProperty[PR, Any] | Callable[[Callable[[Any], PR]], _GenericProperty[PR, Any]]:
     """
-    Return an instance of _InfoProperty wrapping the given function.
+    Decorate a method as an informational/metadata property.
 
-    Decorator for info properties supporting both usages:
+    Supports both usages:
     - @info_property
-    - @info_property(log_context=True)
+    - @info_property(cached=True, log_context=True)
+
+    Args:
+        func: The function being decorated when used as @info_property without
+            parentheses. When used as a factory (i.e., @info_property(...)), this is
+            None and the returned callable expects the function to decorate.
+        cached: Enable per-instance caching for this property when True.
+        log_context: Include this property in structured log context if True.
+
     """
     if func is None:
 
-        def wrapper(f: Callable[[Any], PR]) -> _InfoProperty[PR, Any]:
-            return _InfoProperty(f, log_context=log_context)
+        def wrapper(f: Callable[[Any], PR]) -> _GenericProperty[PR, Any]:
+            return _GenericProperty(f, kind=Kind.INFO, cached=cached, log_context=log_context)
 
         return wrapper
-    return _InfoProperty(func, log_context=log_context)
-
-
-# Expose the underlying property class for discovery
-setattr(info_property, "__property_class__", _InfoProperty)
+    return _GenericProperty(func, kind=Kind.INFO, cached=cached, log_context=log_context)
 
 
 # ----- state_property -----
 
 
-class _StateProperty[GETTER, SETTER](_GenericProperty[GETTER, SETTER]):
-    """Decorate to mark own config properties."""
-
-
 @overload
-def state_property[PR](func: Callable[[Any], PR], /) -> _StateProperty[PR, Any]: ...
+def state_property[PR](func: Callable[[Any], PR], /) -> _GenericProperty[PR, Any]: ...
 
 
 @overload
-def state_property(*, log_context: bool = ...) -> Callable[[Callable[[Any], R]], _StateProperty[R, Any]]: ...
+def state_property(
+    *, cached: bool = ..., log_context: bool = ...
+) -> Callable[[Callable[[Any], R]], _GenericProperty[R, Any]]: ...
 
 
 def state_property[PR](
     func: Callable[[Any], PR] | None = None,
     *,
+    cached: bool = False,
     log_context: bool = False,
-) -> _StateProperty[PR, Any] | Callable[[Callable[[Any], PR]], _StateProperty[PR, Any]]:
+) -> _GenericProperty[PR, Any] | Callable[[Callable[[Any], PR]], _GenericProperty[PR, Any]]:
     """
-    Return an instance of _StateProperty wrapping the given function.
+    Decorate a method as a dynamic state property.
 
-    Decorator for state properties supporting both usages:
+    Supports both usages:
     - @state_property
-    - @state_property(log_context=True)
+    - @state_property(cached=True, log_context=True)
+
+    Args:
+        func: The function being decorated when used as @state_property without
+            parentheses. When used as a factory (i.e., @state_property(...)), this is
+            None and the returned callable expects the function to decorate.
+        cached: Enable per-instance caching for this property when True.
+        log_context: Include this property in structured log context if True.
+
     """
     if func is None:
 
-        def wrapper(f: Callable[[Any], PR]) -> _StateProperty[PR, Any]:
-            return _StateProperty(f, log_context=log_context)
+        def wrapper(f: Callable[[Any], PR]) -> _GenericProperty[PR, Any]:
+            return _GenericProperty(f, kind=Kind.STATE, cached=cached, log_context=log_context)
 
         return wrapper
-    return _StateProperty(func, log_context=log_context)
+    return _GenericProperty(func, kind=Kind.STATE, cached=cached, log_context=log_context)
 
 
-# Expose the underlying property class for discovery
-setattr(state_property, "__property_class__", _StateProperty)
-
 # ----------
 
+
 # Cache for per-class attribute names by decorator to avoid repeated dir() scans
 # Use WeakKeyDictionary to allow classes to be garbage-collected without leaking cache entries.
 # Structure: {cls: {decorator_class: (attr_name1, attr_name2, ...)}}
-_PUBLIC_ATTR_CACHE: WeakKeyDictionary[type, dict[type, tuple[str, ...]]] = WeakKeyDictionary()
+_PUBLIC_ATTR_CACHE: WeakKeyDictionary[type, dict[Kind, tuple[str, ...]]] = WeakKeyDictionary()
 
 
-def _get_attributes_by_decorator(
-    data_object: Any, decorator: Callable, context: bool = False, only_names: bool = False
-) -> Mapping[str, Any]:
+def get_hm_property_by_kind(data_object: Any, kind: Kind, context: bool = False) -> Mapping[str, Any]:
     """
-    Return the object attributes by decorator.
-
-    This caches the attribute names per (class, decorator) to reduce overhead
-    from repeated dir()/getattr() scans. Values are not cached as they are
-    instance-dependent and may change over time.
+    Collect properties from an object that are defined using a specific decorator.
+
+    Args:
+        data_object: The instance to inspect.
+        kind: The decorator class to use for filtering.
+        context: If True, only include properties where the descriptor has
+            log_context=True. When such a property's value is a LogContextMixin, its
+            items are flattened into the result using a short prefix of the property
+            name (e.g. "p.key").
+
+    Returns:
+        Mapping[str, Any]: A mapping of attribute name to normalized value. Values are converted via
+        _get_text_value() to provide stable JSON/log-friendly types.
+
+    Notes:
+        Attribute NAMES are cached per (class, decorator) to avoid repeated dir()
+        scans. Values are never cached here since they are instance-dependent.
+        Getter exceptions are swallowed and represented as None so payload building
+        remains robust and side-effect free.
 
-    To minimize side effects, exceptions raised by property getters are caught
-    and the corresponding value is set to None. This ensures that payload
-    construction and attribute introspection do not fail due to individual
-    properties with transient errors or expensive side effects.
     """
     cls = data_object.__class__
 
-    # Resolve function-based decorators to their underlying property class, if provided
-    resolved_decorator: Any = decorator
-    if not isinstance(decorator, type):
-        resolved_decorator = getattr(decorator, "__property_class__", decorator)
-
     # Get or create the per-class cache dict
     if (decorator_cache := _PUBLIC_ATTR_CACHE.get(cls)) is None:
         decorator_cache = {}
         _PUBLIC_ATTR_CACHE[cls] = decorator_cache
 
-    # Get or compute the attribute names for this decorator
-    if (names := decorator_cache.get(resolved_decorator)) is None:
-        names = tuple(y for y in dir(cls) if isinstance(getattr(cls, y), resolved_decorator))
-        decorator_cache[resolved_decorator] = names
+    if (names := decorator_cache.get(kind)) is None:
+        names = tuple(
+            y for y in dir(cls) if (gp := getattr(cls, y)) and isinstance(gp, _GenericProperty) and gp.kind == kind
+        )
+        decorator_cache[kind] = names
 
     result: dict[str, Any] = {}
-    if only_names:
-        return dict.fromkeys(names)
     for name in names:
         if context and getattr(cls, name).log_context is False:
             continue
@@ -259,7 +465,21 @@ def _get_attributes_by_decorator(
 
 
 def _get_text_value(value: Any) -> Any:
-    """Convert value to text."""
+    """
+    Normalize values for payload/logging purposes.
+
+    - list/tuple/set are converted to tuples and their items normalized recursively
+    - Enum values are converted to their string representation
+    - datetime objects are converted to unix timestamps (float)
+    - all other types are returned unchanged
+
+    Args:
+        value: The input value to normalize into a log-/JSON-friendly representation.
+
+    Returns:
+        Any: The normalized value, potentially converted as described above.
+
+    """
     if isinstance(value, list | tuple | set):
         return tuple(_get_text_value(v) for v in value)
     if isinstance(value, Enum):
@@ -269,59 +489,23 @@ def _get_text_value(value: Any) -> Any:
     return value
 
 
-def get_attributes_for_config_property(data_object: Any) -> Mapping[str, Any]:
-    """Return the object attributes by decorator config_property."""
-    return _get_attributes_by_decorator(data_object=data_object, decorator=config_property)
-
-
-def get_attributes_for_info_property(data_object: Any) -> Mapping[str, Any]:
-    """Return the object attributes by decorator info_property."""
-    return _get_attributes_by_decorator(data_object=data_object, decorator=info_property)
-
-
-def get_attributes_for_log_context(data_object: Any) -> Mapping[str, Any]:
-    """Return the object attributes by decorator info_property."""
-    return (
-        dict(_get_attributes_by_decorator(data_object=data_object, decorator=config_property, context=True))
-        | dict(_get_attributes_by_decorator(data_object=data_object, decorator=info_property, context=True))
-        | dict(_get_attributes_by_decorator(data_object=data_object, decorator=state_property, context=True))
-    )
-
-
-def get_attributes_for_state_property(data_object: Any) -> Mapping[str, Any]:
-    """Return the object attributes by decorator state_property."""
-    return _get_attributes_by_decorator(data_object=data_object, decorator=state_property)
-
-
-# pylint: disable=invalid-name
-class cached_slot_property[T, R]:
-    """A property-like descriptor that caches the computed value in a slot attribute. Designed to work with classes that use __slots__ and do not define __dict__."""
+def get_hm_property_by_log_context(data_object: Any) -> Mapping[str, Any]:
+    """
+    Return combined log context attributes across all property categories.
 
-    def __init__(self, func: Callable[[T], R]) -> None:
-        """Init the cached property."""
-        self._func = func  # The function to compute the value
-        self._cache_attr = f"_cached_{func.__name__}"  # Default name of the cache attribute
-        self._name = func.__name__
+    Includes only properties declared with log_context=True and flattens
+    values that implement LogContextMixin by prefixing with a short key.
 
-    def __get__(self, instance: T | None, owner: type | None = None) -> R:
-        """Return the cached value if it exists. Otherwise, compute it using the function and cache it."""
-        if instance is None:
-            # Accessed from class, return the descriptor itself
-            return cast(R, self)
+    Args:
+        data_object: The instance from which to collect attributes marked for
+            log context across all property categories.
 
-        # If the cached value is not set yet, compute and store it
-        if not hasattr(instance, self._cache_attr):
-            value = self._func(instance)
-            setattr(instance, self._cache_attr, value)
+    Returns:
+        Mapping[str, Any]: A mapping of attribute name to normalized value for logging.
 
-        # Return the cached value
-        return cast(R, getattr(instance, self._cache_attr))
-
-    def __set__(self, instance: T, value: Any) -> None:
-        """Raise an error to prevent manual assignment to the property."""
-        raise AttributeError(f"Can't set read-only cached property '{self._name}'")
+    """
+    result: dict[str, Any] = {}
+    for kind in Kind:
+        result.update(get_hm_property_by_kind(data_object=data_object, kind=kind, context=True))
 
-    def __delete__(self, instance: T) -> None:
-        """Delete the cached value so it can be recomputed on next access."""
-        if hasattr(instance, self._cache_attr):
-            delattr(instance, self._cache_attr)
+    return result

aiohomematic/support.py

@@ -50,11 +50,10 @@ from aiohomematic.const import (
 )
 from aiohomematic.exceptions import AioHomematicException, BaseHomematicException
 from aiohomematic.property_decorators import (
-    cached_slot_property,
-    get_attributes_for_config_property,
-    get_attributes_for_info_property,
-    get_attributes_for_log_context,
-    get_attributes_for_state_property,
+    Kind,
+    cached_property,
+    get_hm_property_by_kind,
+    get_hm_property_by_log_context,
 )
 
 _LOGGER: Final = logging.getLogger(__name__)
@@ -586,11 +585,11 @@ class LogContextMixin:
 
     __slots__ = ("_cached_log_context",)
 
-    @cached_slot_property
+    @cached_property
     def log_context(self) -> Mapping[str, Any]:
         """Return the log context for this object."""
         return {
-            key: value for key, value in get_attributes_for_log_context(data_object=self).items() if value is not None
+            key: value for key, value in get_hm_property_by_log_context(data_object=self).items() if value is not None
         }
 
 
@@ -604,7 +603,7 @@ class PayloadMixin:
         """Return the config payload."""
         return {
             key: value
-            for key, value in get_attributes_for_config_property(data_object=self).items()
+            for key, value in get_hm_property_by_kind(data_object=self, kind=Kind.CONFIG).items()
             if value is not None
         }
 
@@ -612,7 +611,9 @@ class PayloadMixin:
     def info_payload(self) -> Mapping[str, Any]:
         """Return the info payload."""
         return {
-            key: value for key, value in get_attributes_for_info_property(data_object=self).items() if value is not None
+            key: value
+            for key, value in get_hm_property_by_kind(data_object=self, kind=Kind.INFO).items()
+            if value is not None
         }
 
     @property
@@ -620,7 +621,7 @@ class PayloadMixin:
         """Return the state payload."""
         return {
             key: value
-            for key, value in get_attributes_for_state_property(data_object=self).items()
+            for key, value in get_hm_property_by_kind(data_object=self, kind=Kind.STATE).items()
             if value is not None
         }
 

{aiohomematic-2025.9.2.dist-info → aiohomematic-2025.9.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiohomematic
-Version: 2025.9.2
+Version: 2025.9.3
 Summary: Homematic interface for Home Assistant running on Python 3.
 Home-page: https://github.com/sukramj/aiohomematic
 Author-email: SukramJ <sukramj@icloud.com>, Daniel Perna <danielperna84@gmail.com>

{aiohomematic-2025.9.2.dist-info → aiohomematic-2025.9.3.dist-info}/RECORD

@@ -1,14 +1,14 @@
 aiohomematic/__init__.py,sha256=VPESkjzeVserFI2DDVAxD782cgYRlLK0sXJzLrr3e_k,2283
 aiohomematic/async_support.py,sha256=Xc55KkIV0h8rf936QKyU4OHSZsPEZ8TwuV8gVveeRh8,6106
-aiohomematic/const.py,sha256=EpW2w2XzvTzzzxByobHD7suUpA--ZkbzCmMTk79GK7I,25411
+aiohomematic/const.py,sha256=U6GjonNWYX6PLDyzMZqVeYsrVPgG7QqoBhVjRec0Xwk,25411
 aiohomematic/context.py,sha256=M7gkA7KFT0dp35gzGz2dzKVXu1PP0sAnepgLlmjyRS4,451
 aiohomematic/converter.py,sha256=QTOL8_B6SoCoqLuRSkjtOlfa7BVFSvOfnSBrDngiinA,3558
 aiohomematic/decorators.py,sha256=oHEFSJoJVd-h9RYb6NLTJ60erkpRHPYv7EEipKn1a9Q,10636
 aiohomematic/exceptions.py,sha256=o_H3Z0A2TQ0irNxUM9u8bmivq0L_mwPCB7nhxEawDxE,5018
 aiohomematic/hmcli.py,sha256=wHOLq4IJRSY9RJux_ZfDH1gQ1ZqD0k68ua5agyBkkE8,4933
-aiohomematic/property_decorators.py,sha256=LnWgLCkopkSqdz4dcwxoH2UuoWJmykA9YUFM7Zefw70,11710
+aiohomematic/property_decorators.py,sha256=fDuh3sydnlc-8R1gJAh-9ZxW4jApkk-LohA2Rqk-qPI,17609
 aiohomematic/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-aiohomematic/support.py,sha256=9CsB27Xz0Q5tgqROceG2MaQuJGN1rI47YIUZM3N_2Ik,20374
+aiohomematic/support.py,sha256=THiA1zqOSVkR6rnPTdNpRZkdEhGgEiP-jtgTU68tEwE,20331
 aiohomematic/validator.py,sha256=vChkYQ9dGKCQEigiBMnoeyPkCJDJlIm6DSgR1gmeHH0,3545
 aiohomematic/caches/__init__.py,sha256=_gI30tbsWgPRaHvP6cRxOQr6n9bYZzU-jp1WbHhWg-A,470
 aiohomematic/caches/dynamic.py,sha256=Kp0bL5JZaPGGfsezuBX3VtADhEcUvu93AEB5j2rgzzY,21326
@@ -17,19 +17,19 @@ aiohomematic/caches/visibility.py,sha256=uZ1sSCfmEQURllPvSbJ3EzFVFE7TU8XcxMDSHRp
 aiohomematic/central/__init__.py,sha256=y8JErLEY4zh8qsGyS1qMQPaPlQn3GEx6q5_L4OvqxlQ,86148
 aiohomematic/central/decorators.py,sha256=Sl-cMDhreiAOKkIHiei-QbIOcvbWGVX-QwB5bLeohak,6904
 aiohomematic/central/xml_rpc_server.py,sha256=DZcE3t_KWgJyQJM5Z9_yPO4s075DRJmnIdkIx0OTL9M,10549
-aiohomematic/client/__init__.py,sha256=CX3b5LiWO6kJc1Nr6xQoksenk4mMLIyZFhp-LGOUQ1Q,69968
+aiohomematic/client/__init__.py,sha256=6ik0d9VPcwBguL31zdKw_2Zslkra4rnTmwH_sY7oWXo,69964
 aiohomematic/client/_rpc_errors.py,sha256=vu76ZWMwJJEgB0cnXc10JzK8PaiRU7jYOvj1aC21CqE,2971
-aiohomematic/client/json_rpc.py,sha256=07Vfc9laLHIXKG87jlJE1yiLuu4FD3bg25INsV1twkU,49313
-aiohomematic/client/xml_rpc.py,sha256=Z964fzQtq9LaIYZXG02C82CvMU11shxA7yx7UouI_mI,9646
+aiohomematic/client/json_rpc.py,sha256=MR7lpxd3UddNuUojWh8-CZkxVY8_jUPhLXkDQeIXbfA,49307
+aiohomematic/client/xml_rpc.py,sha256=pTnLjY81bJd8goD_zAkSEE7Q_UTKwBmiiyLOwJ1DOMs,9640
 aiohomematic/model/__init__.py,sha256=LBKHws0W-zgFywTsWfklVVCxrO0w6QUY9ptT6LKxJls,5457
-aiohomematic/model/data_point.py,sha256=QvHLLaq1NByB75mP4yIV0VCq4PPNcKdgVbbx07DEER8,40878
-aiohomematic/model/device.py,sha256=OKecVb9hMb-LnbvojMHFKNH1A0-5yIikG9acYCuu3dU,52139
+aiohomematic/model/data_point.py,sha256=Mls6b20e_fzYhB3EPYab0tocRqbl-v5ityV6uKTBOnU,40837
+aiohomematic/model/device.py,sha256=JNRY7mEIZjwdvDnt-kV95QOjWVLrny-PnamitQqjZ-w,52136
 aiohomematic/model/event.py,sha256=EMoKjbOZRXD3jumRrSlSoUr3nZ2QM3GDKKFfhlf-D50,6837
 aiohomematic/model/support.py,sha256=4VQsOlkJuPhq0hLHKt5LB43YgbITjnyJMwucUYGghzM,19616
 aiohomematic/model/update.py,sha256=QVYFhaEqtHZhZ8yGPXEx2hPMne8WAc_SkVaQ0J20oQw,5138
 aiohomematic/model/calculated/__init__.py,sha256=pk56FYa0MNyN0MTsejSy6RdQjOUCKAqzwWSzN6_ENmk,2808
 aiohomematic/model/calculated/climate.py,sha256=0BhrsiVS74_6jo24I8Cg9WzVAD5od3IqgiwTM0ao2n0,8518
-aiohomematic/model/calculated/data_point.py,sha256=DZyd9vBIxxjEU2BBevyMVwCUptu1cy0uCIOxbySw2HI,11535
+aiohomematic/model/calculated/data_point.py,sha256=Bnv2R9ViFf48C7-BjmJh6999EcWZdJxYZfLpBg57oQg,11525
 aiohomematic/model/calculated/operating_voltage_level.py,sha256=urlCkHjisCJ-DO6tUE0evfp45tPwsYcb81_2uoHYxS0,13521
 aiohomematic/model/calculated/support.py,sha256=K-oUSSH6k6_J7zZ9cwxt6qIfArWd-SBWo93LuZUs1_s,6674
 aiohomematic/model/custom/__init__.py,sha256=1sWRrAjHnHSakdrrlNW4_SZ2rg5g2WjGdI4X2PUg_h0,6064
@@ -48,7 +48,7 @@ aiohomematic/model/generic/__init__.py,sha256=goR2uBBGizm-A5Vvd7ii9Ai3OihBl3hIzt
 aiohomematic/model/generic/action.py,sha256=5SPWVliRqXlPgtb2bI6le0-V6JR5krzw8z_0FaOXu5U,994
 aiohomematic/model/generic/binary_sensor.py,sha256=U5GvfRYbhwe0jRmaedD4LVZ_24SyyPbVr74HEfZXoxE,887
 aiohomematic/model/generic/button.py,sha256=6jZ49woI9gYJEx__PjguDNbc5vdE1P-YcLMZZFkYRCg,740
-aiohomematic/model/generic/data_point.py,sha256=VuRj9C7hm8MHqWt2eO99osiKWCXx1MO7JNT9dNM08DI,5933
+aiohomematic/model/generic/data_point.py,sha256=wlPQQjm3YDQRbSONpSyzLVWeivVHdkoo1lLxRE7AAWE,5923
 aiohomematic/model/generic/number.py,sha256=wHNIIVr41IOoROPOnBXuMRsANG6doguIEWXYnQHJbBk,2669
 aiohomematic/model/generic/select.py,sha256=kxN5BR85Yli7kQF2DYkGiLnTgcY9LBJWI7MMwWpH1mo,1535
 aiohomematic/model/generic/sensor.py,sha256=dWff7yBJfJSjoD4rcYdmH5HhaRCUEKfPFfOu4T1LrPo,2253
@@ -69,10 +69,10 @@ aiohomematic/rega_scripts/get_serial.fn,sha256=t1oeo-sB_EuVeiY24PLcxFSkdQVgEWGXz
 aiohomematic/rega_scripts/get_system_variable_descriptions.fn,sha256=UKXvC0_5lSApdQ2atJc0E5Stj5Zt3lqh0EcliokYu2c,849
 aiohomematic/rega_scripts/set_program_state.fn,sha256=0bnv7lUj8FMjDZBz325tDVP61m04cHjVj4kIOnUUgpY,279
 aiohomematic/rega_scripts/set_system_variable.fn,sha256=sTmr7vkPTPnPkor5cnLKlDvfsYRbGO1iq2z_2pMXq5E,383
-aiohomematic-2025.9.2.dist-info/licenses/LICENSE,sha256=q-B0xpREuZuvKsmk3_iyVZqvZ-vJcWmzMZpeAd0RqtQ,1083
+aiohomematic-2025.9.3.dist-info/licenses/LICENSE,sha256=q-B0xpREuZuvKsmk3_iyVZqvZ-vJcWmzMZpeAd0RqtQ,1083
 aiohomematic_support/__init__.py,sha256=_0YtF4lTdC_k6-zrM2IefI0u0LMr_WA61gXAyeGLgbY,66
 aiohomematic_support/client_local.py,sha256=4p0-PagFeNgu-r0EjhpHWfImgHMrdSgt8VUMBBC66J0,12514
-aiohomematic-2025.9.2.dist-info/METADATA,sha256=VefZTtVGMgUabgxX2pfrEWWN7rnqJdM5ydd_Le-aQtg,7075
-aiohomematic-2025.9.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-aiohomematic-2025.9.2.dist-info/top_level.txt,sha256=5TDRlUWQPThIUwQjOj--aUo4UA-ow4m0sNhnoCBi5n8,34
-aiohomematic-2025.9.2.dist-info/RECORD,,
+aiohomematic-2025.9.3.dist-info/METADATA,sha256=vI27ZQjSHKOzV8Qs8e-W7Gk1iHhAG-qLk-W234XkXZo,7075
+aiohomematic-2025.9.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+aiohomematic-2025.9.3.dist-info/top_level.txt,sha256=5TDRlUWQPThIUwQjOj--aUo4UA-ow4m0sNhnoCBi5n8,34
+aiohomematic-2025.9.3.dist-info/RECORD,,