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

aiohomematic/model/update.py

@@ -21,8 +21,9 @@ from aiohomematic.decorators import inspector
 from aiohomematic.exceptions import AioHomematicException
 from aiohomematic.model import device as hmd
 from aiohomematic.model.data_point import CallbackDataPoint
-from aiohomematic.model.decorators import config_property, state_property
-from aiohomematic.model.support import DataPointPathData, PayloadMixin, generate_unique_id
+from aiohomematic.model.support import DataPointPathData, generate_unique_id
+from aiohomematic.property_decorators import config_property, state_property
+from aiohomematic.support import PayloadMixin
 
 __all__ = ["DpUpdate"]
 
@@ -130,12 +131,12 @@ class DpUpdate(CallbackDataPoint, PayloadMixin):
             self._custom_id = None
         self._device.unregister_firmware_update_callback(cb)
 
-    @inspector()
+    @inspector
     async def update_firmware(self, refresh_after_update_intervals: tuple[int, ...]) -> bool:
         """Turn the update on."""
         return await self._device.update_firmware(refresh_after_update_intervals=refresh_after_update_intervals)
 
-    @inspector()
+    @inspector
     async def refresh_firmware_data(self) -> None:
         """Refresh device firmware data."""
         await self._device.central.refresh_firmware_data(device_address=self._device.address)

aiohomematic/property_decorators.py

@@ -0,0 +1,327 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
+"""Decorators for data points used within aiohomematic."""
+
+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 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",
+    "info_property",
+    "state_property",
+]
+
+P = ParamSpec("P")
+T = TypeVar("T")
+R = TypeVar("R")
+
+
+class _GenericProperty[GETTER, SETTER](property):
+    """Generic property implementation."""
+
+    fget: Callable[[Any], GETTER] | None
+    fset: Callable[[Any, SETTER], None] | None
+    fdel: Callable[[Any], None] | None
+
+    def __init__(
+        self,
+        fget: Callable[[Any], GETTER] | None = None,
+        fset: Callable[[Any, SETTER], None] | None = None,
+        fdel: Callable[[Any], None] | None = None,
+        doc: str | None = None,
+        log_context: bool = False,
+    ) -> None:
+        """Init the generic property."""
+        super().__init__(fget, fset, fdel, doc)
+        if doc is None and fget is not None:
+            doc = fget.__doc__
+        self.__doc__ = doc
+        self.log_context = log_context
+
+    def getter(self, fget: Callable[[Any], GETTER], /) -> _GenericProperty:
+        """Return generic getter."""
+        return type(self)(fget, self.fset, self.fdel, self.__doc__)  # 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__)
+
+    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]
+        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 self.fset is None:
+            raise AttributeError("can't set attribute")  # pragma: no cover
+        self.fset(obj, value)
+
+    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)
+
+
+# ----- config_property -----
+
+
+class _ConfigProperty[GETTER, SETTER](_GenericProperty[GETTER, SETTER]):
+    """Decorate to mark own config properties."""
+
+
+@overload
+def config_property[PR](func: Callable[[Any], PR], /) -> _ConfigProperty[PR, Any]: ...
+
+
+@overload
+def config_property(*, log_context: bool = ...) -> Callable[[Callable[[Any], R]], _ConfigProperty[R, Any]]: ...
+
+
+def config_property[PR](
+    func: Callable[[Any], PR] | None = None,
+    *,
+    log_context: bool = False,
+) -> _ConfigProperty[PR, Any] | Callable[[Callable[[Any], PR]], _ConfigProperty[PR, Any]]:
+    """
+    Return an instance of _ConfigProperty wrapping the given function.
+
+    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)
+
+        return wrapper
+    return _ConfigProperty(func, log_context=log_context)
+
+
+# Expose the underlying property class for discovery
+setattr(config_property, "__property_class__", _ConfigProperty)
+
+
+# ----- info_property -----
+
+
+class _InfoProperty[GETTER, SETTER](_GenericProperty[GETTER, SETTER]):
+    """Decorate to mark own info properties."""
+
+
+@overload
+def info_property[PR](func: Callable[[Any], PR], /) -> _InfoProperty[PR, Any]: ...
+
+
+@overload
+def info_property(*, log_context: bool = ...) -> Callable[[Callable[[Any], R]], _InfoProperty[R, Any]]: ...
+
+
+def info_property[PR](
+    func: Callable[[Any], PR] | None = None,
+    *,
+    log_context: bool = False,
+) -> _InfoProperty[PR, Any] | Callable[[Callable[[Any], PR]], _InfoProperty[PR, Any]]:
+    """
+    Return an instance of _InfoProperty wrapping the given function.
+
+    Decorator for info properties supporting both usages:
+    - @info_property
+    - @info_property(log_context=True)
+    """
+    if func is None:
+
+        def wrapper(f: Callable[[Any], PR]) -> _InfoProperty[PR, Any]:
+            return _InfoProperty(f, 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)
+
+
+# ----- 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]: ...
+
+
+@overload
+def state_property(*, log_context: bool = ...) -> Callable[[Callable[[Any], R]], _StateProperty[R, Any]]: ...
+
+
+def state_property[PR](
+    func: Callable[[Any], PR] | None = None,
+    *,
+    log_context: bool = False,
+) -> _StateProperty[PR, Any] | Callable[[Callable[[Any], PR]], _StateProperty[PR, Any]]:
+    """
+    Return an instance of _StateProperty wrapping the given function.
+
+    Decorator for state properties supporting both usages:
+    - @state_property
+    - @state_property(log_context=True)
+    """
+    if func is None:
+
+        def wrapper(f: Callable[[Any], PR]) -> _StateProperty[PR, Any]:
+            return _StateProperty(f, log_context=log_context)
+
+        return wrapper
+    return _StateProperty(func, 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()
+
+
+def _get_attributes_by_decorator(
+    data_object: Any, decorator: Callable, context: bool = False, only_names: 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.
+
+    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
+
+    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
+        try:
+            value = getattr(data_object, name)
+            if isinstance(value, hms.LogContextMixin):
+                result.update({f"{name[:1]}.{k}": v for k, v in value.log_context.items()})
+            else:
+                result[name] = _get_text_value(value)
+        except Exception:
+            # Avoid propagating side effects/errors from getters
+            result[name] = None
+    return result
+
+
+def _get_text_value(value: Any) -> Any:
+    """Convert value to text."""
+    if isinstance(value, list | tuple | set):
+        return tuple(_get_text_value(v) for v in value)
+    if isinstance(value, Enum):
+        return str(value)
+    if isinstance(value, datetime):
+        return datetime.timestamp(value)
+    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 __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__
+
+    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)
+
+        # 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)
+
+        # 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}'")
+
+    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)

aiohomematic/support.py

@@ -49,6 +49,13 @@ from aiohomematic.const import (
     SysvarType,
 )
 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,
+)
 
 _LOGGER: Final = logging.getLogger(__name__)
 
@@ -465,13 +472,13 @@ def hash_sha256(value: Any) -> str:
 
 def _make_value_hashable(value: Any) -> Any:
     """Make a hashable object."""
-    if isinstance(value, (tuple, list)):
+    if isinstance(value, tuple | list):
         return tuple(_make_value_hashable(e) for e in value)
 
     if isinstance(value, dict):
         return tuple(sorted((k, _make_value_hashable(v)) for k, v in value.items()))
 
-    if isinstance(value, (set, frozenset)):
+    if isinstance(value, set | frozenset):
         return tuple(sorted(_make_value_hashable(e) for e in value))
 
     return value
@@ -514,7 +521,7 @@ def cleanup_text_from_html_tags(text: str) -> str:
 _BOUNDARY_MSG = "error_boundary"
 
 
-def _safe_context(context: Mapping[str, Any] | None) -> dict[str, Any]:
+def _safe_log_context(context: Mapping[str, Any] | None) -> dict[str, Any]:
     """Extract safe context from a mapping."""
     ctx: dict[str, Any] = {}
     if not context:
@@ -534,57 +541,6 @@ def _safe_context(context: Mapping[str, Any] | None) -> dict[str, Any]:
     return ctx
 
 
-def build_log_context_from_obj(obj: Any | None) -> dict[str, Any]:
-    """
-    Extract structured context like device_id/channel/parameter from common objects.
-
-    Tries best-effort extraction without raising. Returns a dict suitable for logger.extra.
-    """
-    ctx: dict[str, Any] = {}
-    if obj is None:
-        return ctx
-    try:
-        # DataPoint-like: has channel and parameter
-        if hasattr(obj, "channel"):
-            ch = getattr(obj, "channel")
-            try:
-                # channel address/id
-                channel_address = ch.address if not callable(ch.address) else ch.address()
-                ctx["channel"] = channel_address
-            except Exception:
-                # Fallback to str
-                ctx["channel"] = str(ch)
-            try:
-                if (dev := ch.device if hasattr(ch, "device") else None) is not None:
-                    device_id = dev.id if not callable(dev.id) else dev.id()
-                    ctx["device_id"] = device_id
-            except Exception:
-                pass
-        # Parameter on DataPoint-like
-        if hasattr(obj, "parameter"):
-            with contextlib.suppress(Exception):
-                ctx["parameter"] = getattr(obj, "parameter")
-
-        # Also support objects exposing address directly
-        if "device_id" not in ctx and hasattr(obj, "device"):
-            dev = getattr(obj, "device")
-            try:
-                device_id = dev.id if not callable(dev.id) else dev.id()
-                ctx["device_id"] = device_id
-            except Exception:
-                pass
-        if "channel" not in ctx and hasattr(obj, "address"):
-            try:
-                addr = obj.address if not callable(obj.address) else obj.address()
-                ctx["channel"] = addr
-            except Exception:
-                pass
-    except Exception:
-        # Never allow context building to break the application
-        return {}
-    return ctx
-
-
 def log_boundary_error(
     logger: logging.Logger,
     *,
@@ -592,7 +548,8 @@ def log_boundary_error(
     action: str,
     err: Exception,
     level: int | None = None,
-    context: Mapping[str, Any] | None = None,
+    log_context: Mapping[str, Any] | None = None,
+    message: str | None = None,
 ) -> None:
     """
     Log a boundary error with the provided logger.
@@ -602,42 +559,70 @@ def log_boundary_error(
     logging level if not explicitly provided. Additionally, it enriches the log
     record with extra context about the error and action boundaries.
 
-    :param logger: The logger instance used to log the error.
-    :type logger: logging.Logger
-    :param boundary: The name of the boundary at which the error occurred.
-    :type boundary: str
-    :param action: The action being performed when the error occurred.
-    :type action: str
-    :param err: The exception instance representing the error to log.
-    :type err: Exception
-    :param level: The optional logging level. Defaults to WARNING for recoverable
-        domain errors and ERROR for non-recoverable errors if not provided.
-    :type level: int | None
-    :param context: Optional mapping of additional information or context to
-        include in the log record.
-    :type context: Mapping[str, Any] | None
-    :return: None. This function logs the provided information but does not
-        return a value.
-    :rtype: None
     """
-    extra = {
-        "boundary": boundary,
-        "action": action,
-        "err_type": err.__class__.__name__,
-        "err": extract_exc_args(exc=err),
-        **_safe_context(context),
-    }
+    err_name = err.__class__.__name__
+    log_message = f"[boundary={boundary} action={action} err={err_name}"
+
+    if (err_args := extract_exc_args(exc=err)) and err_args != err_name:
+        log_message += f": {err_args}"
+    log_message += "]"
+
+    if message:
+        log_message += f" {message}"
+
+    if log_context:
+        log_message += f" ctx={orjson.dumps(_safe_log_context(log_context), option=orjson.OPT_SORT_KEYS).decode()}"
 
     # Choose level if not provided:
-    chosen_level = level
-    if chosen_level is None:
+    if (chosen_level := level) is None:
         # Use WARNING for expected/recoverable domain errors, ERROR otherwise.
         chosen_level = logging.WARNING if isinstance(err, BaseHomematicException) else logging.ERROR
 
-    if chosen_level >= logging.ERROR:
-        logger.exception(_BOUNDARY_MSG, extra=extra)
-    else:
-        logger.log(chosen_level, _BOUNDARY_MSG, extra=extra)
+    logger.log(chosen_level, log_message)
+
+
+class LogContextMixin:
+    """Mixin to add log context methods to class."""
+
+    __slots__ = ("_cached_log_context",)
+
+    @cached_slot_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
+        }
+
+
+class PayloadMixin:
+    """Mixin to add payload methods to class."""
+
+    __slots__ = ()
+
+    @property
+    def config_payload(self) -> Mapping[str, Any]:
+        """Return the config payload."""
+        return {
+            key: value
+            for key, value in get_attributes_for_config_property(data_object=self).items()
+            if value is not None
+        }
+
+    @property
+    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
+        }
+
+    @property
+    def state_payload(self) -> Mapping[str, Any]:
+        """Return the state payload."""
+        return {
+            key: value
+            for key, value in get_attributes_for_state_property(data_object=self).items()
+            if value is not None
+        }
 
 
 # Define public API for this module

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiohomematic
-Version: 2025.9.1
+Version: 2025.9.2
 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>
@@ -52,7 +52,7 @@ Unlike pyhomematic, which required manual device mappings, aiohomematic automati
 Use the Home Assistant custom integration "Homematic(IP) Local", which is powered by aiohomematic.
 
 1. Prerequisites
-   - Home Assistant 2024.6 or newer recommended.
+   - Use latest version of Home Assistant.
    - A CCU3, RaspberryMatic, or Homegear instance reachable from Home Assistant.
    - For HomematicIP devices, ensure CCU firmware meets the minimum versions listed below.
 2. Install the integration
@@ -60,11 +60,11 @@ Use the Home Assistant custom integration "Homematic(IP) Local", which is powere
    - Follow the installation guide: https://github.com/sukramj/homematicip_local/wiki/Installation
 3. Configure via Home Assistant UI
    - In Home Assistant: Settings → Devices & Services → Add Integration → search for "Homematic(IP) Local".
-   - Enter the CCU/Homegear host (IP or hostname). If you use HTTPS on the CCU, enable SSL and accept the certificate if self‑signed.
-   - Provide credentials if your CCU requires them.
+   - Enter the CCU/Homegear host (IP or hostname). If you use HTTPS on the CCU, enable TLS and don't use verify if self‑signed.
+   - Always enter credentials.
    - Choose which interfaces to enable (HM, HmIP, Virtual). Default ports are typically 2001 (HM), 2010 (HmIP), 9292 (Virtual).
 4. Network callbacks
-   - The integration needs to receive XML‑RPC callbacks from the CCU. Make sure Home Assistant is reachable from the CCU (no NAT/firewall blocking). The default callback port is 43439; you can adjust it in advanced options.
+   - The integration needs to receive XML‑RPC callbacks from the CCU. Make sure Home Assistant is reachable from the CCU (no NAT/firewall blocking). Callbacks ar only required for special network setups.
 5. Verify
    - After setup, devices should appear under Devices & Services → Homematic(IP) Local. Discovery may take a few seconds after the first connection while paramsets are fetched and cached for faster restarts.
 
@@ -84,10 +84,12 @@ See details here: https://github.com/jens-maus/RaspberryMatic/issues/843. Other
 - The public API of aiohomematic is explicitly defined via **all** in each module and subpackage.
 - Backwards‑compatible imports should target these modules:
   - aiohomematic.central: CentralUnit, CentralConfig and related schemas
+  - aiohomematic.central.event: display received events from the backend
   - aiohomematic.client: Client, InterfaceConfig, create_client, get_client
   - aiohomematic.model: device/data point abstractions (see subpackages for details)
   - aiohomematic.exceptions: library exception types intended for consumers
   - aiohomematic.const: constants and enums (stable subset; see module **all**)
+  - aiohomematic.performance: display some performance metrics (enabled when DEBUG is enabled)
 - The top‑level package only exposes **version** to avoid import cycles and keep startup lean. Prefer importing from the specific submodules listed above.
 
 Example: