aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/store/dynamic/data.py

@@ -0,0 +1,175 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Central data cache for device/channel parameter values.
+
+This module provides CentralDataCache which stores recently fetched device/channel
+parameter values from interfaces for quick lookup and periodic refresh.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import datetime
+import logging
+from typing import Any, Final
+
+from aiohomematic.const import INIT_DATETIME, MAX_CACHE_AGE, NO_CACHE_ENTRY, CallSource, Interface, ParamsetKey
+from aiohomematic.interfaces import (
+    CacheWithStatisticsProtocol,
+    CentralInfoProtocol,
+    ClientProviderProtocol,
+    DataCacheWriterProtocol,
+    DataPointProviderProtocol,
+    DeviceProviderProtocol,
+)
+from aiohomematic.store.types import CacheName, CacheStatistics
+from aiohomematic.support import changed_within_seconds
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class CentralDataCache(DataCacheWriterProtocol, CacheWithStatisticsProtocol):
+    """Central cache for device/channel initial data."""
+
+    __slots__ = (
+        "_central_info",
+        "_client_provider",
+        "_data_point_provider",
+        "_device_provider",
+        "_is_initializing",
+        "_refreshed_at",
+        "_stats",
+        "_value_cache",
+    )
+
+    def __init__(
+        self,
+        *,
+        device_provider: DeviceProviderProtocol,
+        client_provider: ClientProviderProtocol,
+        data_point_provider: DataPointProviderProtocol,
+        central_info: CentralInfoProtocol,
+    ) -> None:
+        """Initialize the central data cache."""
+        self._device_provider: Final = device_provider
+        self._client_provider: Final = client_provider
+        self._data_point_provider: Final = data_point_provider
+        self._central_info: Final = central_info
+        self._stats: Final = CacheStatistics()
+        # { key, value}
+        self._value_cache: Final[dict[Interface, Mapping[str, Any]]] = {}
+        self._refreshed_at: Final[dict[Interface, datetime]] = {}
+        # During initialization, cache expiration is disabled to prevent
+        # getValue calls when device creation takes longer than MAX_CACHE_AGE
+        self._is_initializing: bool = True
+
+    @property
+    def name(self) -> CacheName:
+        """Return the cache name."""
+        return CacheName.DATA
+
+    @property
+    def size(self) -> int:
+        """Return total number of entries in cache."""
+        return sum(len(cache) for cache in self._value_cache.values())
+
+    @property
+    def statistics(self) -> CacheStatistics:
+        """Return the cache statistics."""
+        return self._stats
+
+    def add_data(self, *, interface: Interface, all_device_data: Mapping[str, Any]) -> None:
+        """Add data to cache."""
+        self._value_cache[interface] = all_device_data
+        self._refreshed_at[interface] = datetime.now()
+
+    def clear(self, *, interface: Interface | None = None) -> None:
+        """Clear the cache."""
+        if interface:
+            self._value_cache[interface] = {}
+            self._refreshed_at[interface] = INIT_DATETIME
+        else:
+            for _interface in self._device_provider.interfaces:
+                self.clear(interface=_interface)
+
+    def get_data(
+        self,
+        *,
+        interface: Interface,
+        channel_address: str,
+        parameter: str,
+    ) -> Any:
+        """Get data from cache."""
+        if not self._is_empty(interface=interface) and (iface_cache := self._value_cache.get(interface)) is not None:
+            result = iface_cache.get(f"{interface}.{channel_address}.{parameter}", NO_CACHE_ENTRY)
+            if result != NO_CACHE_ENTRY:
+                self._stats.record_hit()
+            else:
+                self._stats.record_miss()
+            return result
+        self._stats.record_miss()
+        return NO_CACHE_ENTRY
+
+    async def load(self, *, direct_call: bool = False, interface: Interface | None = None) -> None:
+        """Fetch data from the backend."""
+        _LOGGER.debug("load: Loading device data for %s", self._central_info.name)
+        for client in self._client_provider.clients:
+            if interface and interface != client.interface:
+                continue
+            if direct_call is False and changed_within_seconds(
+                last_change=self._get_refreshed_at(interface=client.interface),
+                max_age=int(MAX_CACHE_AGE / 3),
+            ):
+                return
+            await client.fetch_all_device_data()
+
+    async def refresh_data_point_data(
+        self,
+        *,
+        paramset_key: ParamsetKey | None = None,
+        interface: Interface | None = None,
+        direct_call: bool = False,
+    ) -> None:
+        """Refresh data_point data."""
+        for dp in self._data_point_provider.get_readable_generic_data_points(
+            paramset_key=paramset_key, interface=interface
+        ):
+            await dp.load_data_point_value(call_source=CallSource.HM_INIT, direct_call=direct_call)
+
+    def set_initialization_complete(self) -> None:
+        """
+        Mark initialization as complete, enabling cache expiration.
+
+        Call this after device creation is finished to enable normal cache
+        expiration behavior. During initialization, cache entries are kept
+        regardless of age to avoid triggering getValue calls when device
+        creation takes longer than MAX_CACHE_AGE.
+        """
+        self._is_initializing = False
+        _LOGGER.debug(
+            "SET_INITIALIZATION_COMPLETE: Cache expiration enabled for %s",
+            self._central_info.name,
+        )
+
+    def _get_refreshed_at(self, *, interface: Interface) -> datetime:
+        """Return when cache has been refreshed."""
+        return self._refreshed_at.get(interface, INIT_DATETIME)
+
+    def _is_empty(self, *, interface: Interface) -> bool:
+        """Return if cache is empty for the given interface."""
+        # If there is no data stored for the requested interface, treat as empty.
+        if not self._value_cache.get(interface):
+            return True
+        # Skip cache expiration during initialization to prevent getValue calls
+        # when device creation takes longer than MAX_CACHE_AGE (10 seconds).
+        if self._is_initializing:
+            return False
+        # Auto-expire stale cache by interface.
+        if not changed_within_seconds(last_change=self._get_refreshed_at(interface=interface)):
+            # Track eviction before clearing
+            if (evicted_count := len(self._value_cache.get(interface, {}))) > 0:
+                self._stats.record_eviction(count=evicted_count)
+            self.clear(interface=interface)
+            return True
+        return False

aiohomematic/store/dynamic/details.py

@@ -0,0 +1,187 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Device details cache for runtime device metadata.
+
+This module provides DeviceDetailsCache which enriches devices with human-readable
+names, interface mapping, rooms, functions, and address IDs fetched via the backend.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Mapping
+from datetime import datetime
+import logging
+from typing import Final, cast
+
+from aiohomematic.const import INIT_DATETIME, MAX_CACHE_AGE, Interface
+from aiohomematic.interfaces import (
+    CentralInfoProtocol,
+    DeviceDetailsProviderProtocol,
+    DeviceDetailsWriterProtocol,
+    PrimaryClientProviderProtocol,
+)
+from aiohomematic.interfaces.model import DeviceRemovalInfoProtocol
+from aiohomematic.property_decorators import DelegatedProperty
+from aiohomematic.support import changed_within_seconds, get_device_address
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class DeviceDetailsCache(DeviceDetailsProviderProtocol, DeviceDetailsWriterProtocol):
+    """Cache for device/channel details."""
+
+    __slots__ = (
+        "_central_info",
+        "_channel_rooms",
+        "_device_channel_rega_ids",
+        "_device_rooms",
+        "_functions",
+        "_interface_cache",
+        "_names_cache",
+        "_primary_client_provider",
+        "_refreshed_at",
+    )
+
+    def __init__(
+        self,
+        *,
+        central_info: CentralInfoProtocol,
+        primary_client_provider: PrimaryClientProviderProtocol,
+    ) -> None:
+        """Initialize the device details cache."""
+        self._central_info: Final = central_info
+        self._primary_client_provider: Final = primary_client_provider
+        self._channel_rooms: Final[dict[str, set[str]]] = defaultdict(set)
+        self._device_channel_rega_ids: Final[dict[str, int]] = {}
+        self._device_rooms: Final[dict[str, set[str]]] = defaultdict(set)
+        self._functions: Final[dict[str, set[str]]] = {}
+        self._interface_cache: Final[dict[str, Interface]] = {}
+        self._names_cache: Final[dict[str, str]] = {}
+        self._refreshed_at = INIT_DATETIME
+
+    device_channel_rega_ids: Final = DelegatedProperty[Mapping[str, int]](path="_device_channel_rega_ids")
+
+    def add_address_rega_id(self, *, address: str, rega_id: int) -> None:
+        """Add channel id for a channel."""
+        self._device_channel_rega_ids[address] = rega_id
+
+    def add_interface(self, *, address: str, interface: Interface) -> None:
+        """Add interface to cache."""
+        self._interface_cache[address] = interface
+
+    def add_name(self, *, address: str, name: str) -> None:
+        """Add name to cache."""
+        self._names_cache[address] = name
+
+    def clear(self) -> None:
+        """Clear the cache."""
+        self._names_cache.clear()
+        self._channel_rooms.clear()
+        self._device_rooms.clear()
+        self._functions.clear()
+        self._refreshed_at = INIT_DATETIME
+
+    def get_address_id(self, *, address: str) -> int:
+        """Get id for address."""
+        return self._device_channel_rega_ids.get(address) or 0
+
+    def get_channel_rooms(self, *, channel_address: str) -> set[str]:
+        """Return rooms by channel_address."""
+        return self._channel_rooms[channel_address]
+
+    def get_device_rooms(self, *, device_address: str) -> set[str]:
+        """Return all rooms by device_address."""
+        return set(self._device_rooms.get(device_address, ()))
+
+    def get_function_text(self, *, address: str) -> str | None:
+        """Return function by address."""
+        if functions := self._functions.get(address):
+            return ",".join(functions)
+        return None
+
+    def get_interface(self, *, address: str) -> Interface:
+        """Get interface from cache."""
+        return self._interface_cache.get(address) or Interface.BIDCOS_RF
+
+    def get_name(self, *, address: str) -> str | None:
+        """Get name from cache."""
+        return self._names_cache.get(address)
+
+    async def load(self, *, direct_call: bool = False) -> None:
+        """Fetch names from the backend."""
+        if direct_call is False and changed_within_seconds(
+            last_change=self._refreshed_at, max_age=int(MAX_CACHE_AGE / 3)
+        ):
+            return
+        self.clear()
+        _LOGGER.debug("LOAD: Loading names for %s", self._central_info.name)
+        if client := self._primary_client_provider.primary_client:
+            await client.fetch_device_details()
+        _LOGGER.debug("LOAD: Loading rooms for %s", self._central_info.name)
+        self._channel_rooms.clear()
+        self._channel_rooms.update(await self._get_all_rooms())
+        self._device_rooms.clear()
+        self._device_rooms.update(self._prepare_device_rooms())
+        _LOGGER.debug("LOAD: Loading functions for %s", self._central_info.name)
+        self._functions.clear()
+        self._functions.update(await self._get_all_functions())
+        self._refreshed_at = datetime.now()
+
+    def remove_device(self, *, device: DeviceRemovalInfoProtocol) -> None:
+        """Remove device data from all caches."""
+        # Clean device-level entries
+        self._names_cache.pop(device.address, None)
+        self._interface_cache.pop(device.address, None)
+        self._device_channel_rega_ids.pop(device.address, None)
+        self._device_rooms.pop(device.address, None)
+        self._functions.pop(device.address, None)
+
+        # Clean channel-level entries
+        for channel_address in device.channels:
+            self._names_cache.pop(channel_address, None)
+            self._interface_cache.pop(channel_address, None)
+            self._device_channel_rega_ids.pop(channel_address, None)
+            self._channel_rooms.pop(channel_address, None)
+            self._functions.pop(channel_address, None)
+
+    async def _get_all_functions(self) -> Mapping[str, set[str]]:
+        """Get all functions, if available."""
+        if client := self._primary_client_provider.primary_client:
+            return cast(
+                Mapping[str, set[str]],
+                await client.get_all_functions(),
+            )
+        return {}
+
+    async def _get_all_rooms(self) -> Mapping[str, set[str]]:
+        """Get all rooms, if available."""
+        if client := self._primary_client_provider.primary_client:
+            return cast(
+                Mapping[str, set[str]],
+                await client.get_all_rooms(),
+            )
+        return {}
+
+    def _prepare_device_rooms(self) -> dict[str, set[str]]:
+        """
+        Return rooms by device_address.
+
+        Aggregation algorithm:
+            The CCU stores room assignments at the channel level (e.g., "ABC123:1" is in "Living Room").
+            Devices themselves don't have direct room assignments - they inherit from their channels.
+            This method aggregates channel rooms to the device level by:
+            1. Iterating all channel_address -> rooms mappings
+            2. Extracting the device_address from each channel_address
+            3. Merging all channel rooms into a set per device
+
+        Result: A device is considered "in" all rooms that any of its channels are in.
+        """
+        _device_rooms: Final[dict[str, set[str]]] = defaultdict(set)
+        for channel_address, rooms in self._channel_rooms.items():
+            if rooms:
+                # Extract device address (e.g., "ABC123:1" -> "ABC123")
+                # and merge this channel's rooms into the device's room set
+                _device_rooms[get_device_address(address=channel_address)].update(rooms)
+        return _device_rooms