aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/store/persistent/base.py

@@ -0,0 +1,285 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Base class for persistent caches using storage abstraction.
+
+This module provides the foundation for all persistent caches. Instead of
+handling file I/O directly, caches now delegate to StorageProtocol instances.
+
+Key behaviors:
+- Delegates file I/O to StorageProtocol
+- Hash-based change detection for efficient saves
+- Optional caching control via config
+- Supports delayed saves for batching updates
+
+Migration from old BasePersistentFile
+-------------------------------------
+The old implementation mixed cache logic with file operations. The new
+BasePersistentCache separates concerns:
+
+- Cache logic: Handled by BasePersistentCache and subclasses
+- File operations: Delegated to StorageProtocol
+- Factory creation: Via StorageFactoryProtocol
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+import logging
+from typing import TYPE_CHECKING, Any, Final
+
+from slugify import slugify
+
+from aiohomematic.const import FILE_NAME_TS_PATTERN, INIT_DATETIME, DataOperationResult
+from aiohomematic.support import hash_sha256
+
+if TYPE_CHECKING:
+    from aiohomematic.interfaces import ConfigProviderProtocol
+    from aiohomematic.store.storage import StorageProtocol
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class BasePersistentCache(ABC):
+    """
+    Base class for persistent caches.
+
+    This abstract class provides common functionality for caches that need
+    to persist their data. Subclasses define the cache structure and logic,
+    while actual storage operations are delegated to a StorageProtocol.
+
+    Key differences from old BasePersistentFile:
+        - No direct file I/O - uses storage.save/load
+        - No semaphore needed - storage handles synchronization
+        - Hash-based change detection retained for efficiency
+        - Simpler interface - only cache logic, no file path handling
+
+    Subclasses must implement:
+        - _create_empty_content(): Define initial data structure
+        - _process_loaded_content(): Rebuild indexes after load
+
+    Schema Versioning:
+        - SCHEMA_VERSION: Subclasses override to define their schema version
+        - _migrate_schema(): Subclasses override to implement migrations
+    """
+
+    # Subclasses override to define their schema version
+    SCHEMA_VERSION: int = 1
+
+    __slots__ = (
+        "_config_provider",
+        "_content",
+        "_last_hash_saved",
+        "_storage",
+        "last_save_triggered",
+    )
+
+    def __init__(
+        self,
+        *,
+        storage: StorageProtocol,
+        config_provider: ConfigProviderProtocol,
+    ) -> None:
+        """
+        Initialize the cache.
+
+        Args:
+            storage: Storage instance for persistence.
+            config_provider: Provider for configuration access.
+
+        """
+        self._storage: Final = storage
+        self._config_provider: Final = config_provider
+        self._content: dict[str, Any] = self._create_empty_content()
+        self._last_hash_saved: str = ""
+        self.last_save_triggered: datetime = INIT_DATETIME
+
+    @property
+    def _should_save(self) -> bool:
+        """Determine if save operation should proceed."""
+        self.last_save_triggered = datetime.now()
+        use_caches = self._config_provider.config.use_caches
+        has_changes = self.has_unsaved_changes
+        _LOGGER.debug(
+            "CACHE_SHOULD_SAVE: %s - use_caches=%s, has_unsaved_changes=%s, result=%s",
+            self.storage_key,
+            use_caches,
+            has_changes,
+            use_caches and has_changes,
+        )
+        return use_caches and has_changes
+
+    @property
+    def content_hash(self) -> str:
+        """Return hash of current content."""
+        return hash_sha256(value=self._content)
+
+    @property
+    def has_unsaved_changes(self) -> bool:
+        """Return True if content changed since last save."""
+        return self.content_hash != self._last_hash_saved
+
+    @property
+    def storage_key(self) -> str:
+        """Return the storage key."""
+        return self._storage.key
+
+    async def clear(self) -> None:
+        """Remove storage and clear content."""
+        await self._storage.remove()
+        self._content.clear()
+        self._content.update(self._create_empty_content())
+        self._last_hash_saved = ""
+
+    async def flush(self) -> None:
+        """Flush any pending delayed saves immediately."""
+        await self._storage.flush()
+
+    async def load(self) -> DataOperationResult:
+        """
+        Load content from storage.
+
+        After loading, calls _process_loaded_content to rebuild any
+        derived structures or indexes. If the loaded schema version is
+        older than the current SCHEMA_VERSION, _migrate_schema is called.
+
+        Returns:
+            DataOperationResult indicating success/skip/failure.
+
+        """
+        _LOGGER.debug("CACHE_LOAD: Starting load for %s", self.storage_key)
+        try:
+            data = await self._storage.load()
+        except Exception:
+            _LOGGER.exception("CACHE: Failed to load %s", self.storage_key)  # i18n-log: ignore
+            return DataOperationResult.LOAD_FAIL
+
+        if data is None:
+            _LOGGER.debug("CACHE_LOAD: No data found for %s", self.storage_key)
+            return DataOperationResult.NO_LOAD
+
+        _LOGGER.debug("CACHE_LOAD: Loaded data for %s (keys: %s)", self.storage_key, list(data.keys()))
+
+        # Check and migrate schema version
+        if (loaded_version := data.pop("_schema_version", 1)) < self.SCHEMA_VERSION:
+            data = self._migrate_schema(data=data, from_version=loaded_version)
+
+        if (loaded_hash := hash_sha256(value=data)) == self._last_hash_saved:
+            return DataOperationResult.NO_LOAD
+
+        self._content.clear()
+        self._content.update(data)
+        self._process_loaded_content(data=data)
+        self._last_hash_saved = loaded_hash
+        return DataOperationResult.LOAD_SUCCESS
+
+    async def save(self) -> DataOperationResult:
+        """
+        Save content to storage if changed.
+
+        Only saves if caching is enabled and content has changed since last save.
+        Adds _schema_version to saved data for migration support.
+
+        Returns:
+            DataOperationResult indicating success/skip/failure.
+
+        """
+        if not self._should_save:
+            _LOGGER.debug("CACHE_SAVE: Skipping save for %s (no changes or caching disabled)", self.storage_key)
+            return DataOperationResult.NO_SAVE
+
+        # Add schema version before saving
+        save_data = {"_schema_version": self.SCHEMA_VERSION, **self._content}
+
+        try:
+            _LOGGER.debug(
+                "CACHE_SAVE: Saving %s to storage (content keys: %s, sizes: %s)",
+                self.storage_key,
+                list(self._content.keys()),
+                {k: len(v) if isinstance(v, (list, dict)) else "?" for k, v in self._content.items()},
+            )
+            await self._storage.save(data=save_data)
+            self._last_hash_saved = self.content_hash
+            _LOGGER.debug("CACHE_SAVE: Successfully saved %s", self.storage_key)
+        except Exception:
+            _LOGGER.exception("CACHE: Failed to save %s", self.storage_key)  # i18n-log: ignore
+            return DataOperationResult.SAVE_FAIL
+        else:
+            return DataOperationResult.SAVE_SUCCESS
+
+    async def save_delayed(self, *, delay: float = 1.0) -> None:
+        """
+        Schedule a delayed save.
+
+        Multiple calls within the delay period will reset the timer.
+        Useful for batching rapid updates.
+
+        Args:
+            delay: Delay in seconds before saving (default: 1.0).
+
+        """
+        if not self._config_provider.config.use_caches:
+            return
+
+        await self._storage.delay_save(
+            data_func=lambda: self._content,
+            delay=delay,
+        )
+
+    @abstractmethod
+    def _create_empty_content(self) -> dict[str, Any]:
+        """
+        Create empty content structure.
+
+        Subclasses override to define their data structure.
+
+        Returns:
+            Empty dict structure for this cache type.
+
+        """
+
+    def _migrate_schema(self, *, data: dict[str, Any], from_version: int) -> dict[str, Any]:
+        """
+        Migrate data from older schema version.
+
+        Subclasses override to implement version-specific migrations.
+        Default implementation returns data unchanged.
+
+        Args:
+            data: Raw data loaded from storage.
+            from_version: Schema version of loaded data.
+
+        Returns:
+            Migrated data dict.
+
+        """
+        return data
+
+    @abstractmethod
+    def _process_loaded_content(self, *, data: dict[str, Any]) -> None:
+        """
+        Process data after loading from storage.
+
+        Subclasses implement to rebuild internal indexes or derived structures.
+
+        Args:
+            data: Raw data loaded from storage.
+
+        """
+
+
+# Helper functions for path/name generation
+
+
+def get_file_path(*, storage_directory: str, sub_directory: str) -> str:
+    """Return the content path."""
+    return f"{storage_directory}/{sub_directory}"
+
+
+def get_file_name(*, central_name: str, file_name: str, ts: datetime | None = None) -> str:
+    """Return the content file name."""
+    fn = f"{slugify(central_name)}_{file_name}"
+    if ts:
+        fn += f"_{ts.strftime(FILE_NAME_TS_PATTERN)}"
+    return f"{fn}.json"

aiohomematic/store/persistent/device.py

@@ -0,0 +1,233 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Device description registry for persisting device/channel metadata.
+
+This module provides DeviceDescriptionRegistry which persists device descriptions
+per interface, including the mapping of device/channels and model metadata.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Mapping
+import logging
+from typing import TYPE_CHECKING, Any, Final
+
+from aiohomematic import i18n
+from aiohomematic.const import ADDRESS_SEPARATOR, DeviceDescription
+from aiohomematic.exceptions import DescriptionNotFoundException
+from aiohomematic.interfaces import DeviceDescriptionProviderProtocol, DeviceDescriptionsAccessProtocol
+from aiohomematic.interfaces.model import DeviceRemovalInfoProtocol
+from aiohomematic.schemas import normalize_device_description
+from aiohomematic.store.persistent.base import BasePersistentCache
+from aiohomematic.support import get_device_address
+
+if TYPE_CHECKING:
+    from aiohomematic.interfaces import ConfigProviderProtocol
+    from aiohomematic.store.storage import StorageProtocol
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class DeviceDescriptionRegistry(
+    BasePersistentCache, DeviceDescriptionProviderProtocol, DeviceDescriptionsAccessProtocol
+):
+    """Registry for device/channel descriptions."""
+
+    # Bump version when normalization logic changes
+    SCHEMA_VERSION: int = 2
+
+    __slots__ = (
+        "_addresses",
+        "_device_descriptions",
+    )
+
+    def __init__(
+        self,
+        *,
+        storage: StorageProtocol,
+        config_provider: ConfigProviderProtocol,
+    ) -> None:
+        """
+        Initialize the device description cache.
+
+        Args:
+            storage: Storage instance for persistence.
+            config_provider: Provider for configuration access.
+
+        """
+        # {interface_id, {device_address, [channel_address]}}
+        self._addresses: Final[dict[str, dict[str, set[str]]]] = defaultdict(lambda: defaultdict(set))
+        # {interface_id, {address, device_descriptions}}
+        self._device_descriptions: Final[dict[str, dict[str, DeviceDescription]]] = defaultdict(dict)
+        super().__init__(
+            storage=storage,
+            config_provider=config_provider,
+        )
+
+    @property
+    def _raw_device_descriptions(self) -> dict[str, list[DeviceDescription]]:
+        """Return the raw device descriptions (alias to _content)."""
+        return self._content
+
+    @property
+    def size(self) -> int:
+        """Return total number of device descriptions in cache."""
+        return sum(len(descriptions) for descriptions in self._raw_device_descriptions.values())
+
+    def add_device(self, *, interface_id: str, device_description: DeviceDescription) -> None:
+        """Add a device to the cache (normalized)."""
+        # Normalize at ingestion
+        normalized = normalize_device_description(device_description=device_description)
+        # Fast-path: If the address is not yet known, skip costly removal operations.
+        if (address := normalized["ADDRESS"]) not in self._device_descriptions[interface_id]:
+            self._raw_device_descriptions[interface_id].append(normalized)
+            _LOGGER.debug(
+                "DEVICE_REGISTRY_ADD: Added device %s to %s (total: %s)",
+                address,
+                interface_id,
+                len(self._raw_device_descriptions[interface_id]),
+            )
+            self._process_device_description(interface_id=interface_id, device_description=normalized)
+            return
+        # Address exists: remove old entries before adding the new description.
+        self._remove_device(
+            interface_id=interface_id,
+            addresses_to_remove=[address],
+        )
+        self._raw_device_descriptions[interface_id].append(normalized)
+        _LOGGER.debug(
+            "DEVICE_REGISTRY_UPDATE: Updated device %s in %s (total: %s)",
+            address,
+            interface_id,
+            len(self._raw_device_descriptions[interface_id]),
+        )
+        self._process_device_description(interface_id=interface_id, device_description=normalized)
+
+    def find_device_description(self, *, interface_id: str, device_address: str) -> DeviceDescription | None:
+        """Return the device description by interface and device_address."""
+        return self._device_descriptions[interface_id].get(device_address)
+
+    def get_addresses(self, *, interface_id: str | None = None) -> frozenset[str]:
+        """Return the addresses by interface as a set."""
+        if interface_id:
+            return frozenset(self._addresses[interface_id])
+        return frozenset(addr for interface_id in self.get_interface_ids() for addr in self._addresses[interface_id])
+
+    def get_device_description(self, *, interface_id: str, address: str) -> DeviceDescription:
+        """Return the device description by interface and device_address."""
+        try:
+            return self._device_descriptions[interface_id][address]
+        except KeyError as exc:
+            raise DescriptionNotFoundException(
+                i18n.tr(
+                    key="exception.store.device_description.not_found",
+                    address=address,
+                    interface_id=interface_id,
+                )
+            ) from exc
+
+    def get_device_descriptions(self, *, interface_id: str) -> Mapping[str, DeviceDescription]:
+        """Return the devices by interface."""
+        return self._device_descriptions[interface_id]
+
+    def get_device_with_channels(self, *, interface_id: str, device_address: str) -> Mapping[str, DeviceDescription]:
+        """Return the device dict by interface and device_address."""
+        device_descriptions: dict[str, DeviceDescription] = {
+            device_address: self.get_device_description(interface_id=interface_id, address=device_address)
+        }
+        children = device_descriptions[device_address].get("CHILDREN", [])
+        for channel_address in children:
+            device_descriptions[channel_address] = self.get_device_description(
+                interface_id=interface_id, address=channel_address
+            )
+        return device_descriptions
+
+    def get_interface_ids(self) -> tuple[str, ...]:
+        """Return the interface ids."""
+        return tuple(self._raw_device_descriptions.keys())
+
+    def get_model(self, *, device_address: str) -> str | None:
+        """Return the device type."""
+        for data in self._device_descriptions.values():
+            if items := data.get(device_address):
+                return items["TYPE"]
+        return None
+
+    def get_raw_device_descriptions(self, *, interface_id: str) -> list[DeviceDescription]:
+        """Retrieve raw device descriptions from the cache."""
+        return self._raw_device_descriptions[interface_id]
+
+    def has_device_descriptions(self, *, interface_id: str) -> bool:
+        """Return the devices by interface."""
+        return interface_id in self._device_descriptions
+
+    def remove_device(self, *, device: DeviceRemovalInfoProtocol) -> None:
+        """Remove device from cache."""
+        self._remove_device(
+            interface_id=device.interface_id,
+            addresses_to_remove=[device.address, *device.channels.keys()],
+        )
+
+    def _convert_device_descriptions(self, *, interface_id: str, device_descriptions: list[DeviceDescription]) -> None:
+        """Convert provided list of device descriptions (normalized)."""
+        for device_description in device_descriptions:
+            # Normalize each description when loading
+            normalized = normalize_device_description(device_description=device_description)
+            self._process_device_description(interface_id=interface_id, device_description=normalized)
+
+    def _create_empty_content(self) -> dict[str, Any]:
+        """Create empty content structure."""
+        return defaultdict(list)
+
+    def _migrate_schema(self, *, data: dict[str, Any], from_version: int) -> dict[str, Any]:
+        """Migrate device descriptions from older schema."""
+        if from_version < 2:
+            # Migration from v1: normalize all CHILDREN fields
+            for interface_id, descriptions in data.items():
+                if interface_id.startswith("_"):
+                    continue
+                for desc in descriptions:
+                    children = desc.get("CHILDREN")
+                    if children is None or isinstance(children, str):
+                        desc["CHILDREN"] = []
+        return data
+
+    def _process_device_description(self, *, interface_id: str, device_description: DeviceDescription) -> None:
+        """Convert provided dict of device descriptions."""
+        address = device_description["ADDRESS"]
+        device_address = get_device_address(address=address)
+        self._device_descriptions[interface_id][address] = device_description
+
+        # Avoid redundant membership checks; set.add is idempotent and cheaper than check+add
+        addr_set = self._addresses[interface_id][device_address]
+        addr_set.add(device_address)
+        addr_set.add(address)
+
+    def _process_loaded_content(self, *, data: dict[str, Any]) -> None:
+        """Rebuild indexes from loaded data."""
+        self._addresses.clear()
+        self._device_descriptions.clear()
+        for interface_id, device_descriptions in data.items():
+            if interface_id.startswith("_"):  # Skip metadata keys
+                continue
+            self._convert_device_descriptions(
+                interface_id=interface_id,
+                device_descriptions=device_descriptions,
+            )
+
+    def _remove_device(self, *, interface_id: str, addresses_to_remove: list[str]) -> None:
+        """Remove a device from the cache."""
+        # Use a set for faster membership checks
+        addresses_set = set(addresses_to_remove)
+        self._raw_device_descriptions[interface_id] = [
+            device for device in self._raw_device_descriptions[interface_id] if device["ADDRESS"] not in addresses_set
+        ]
+        addr_map = self._addresses[interface_id]
+        desc_map = self._device_descriptions[interface_id]
+        for address in addresses_set:
+            # Pop with default to avoid KeyError and try/except overhead
+            if ADDRESS_SEPARATOR not in address:
+                addr_map.pop(address, None)
+            desc_map.pop(address, None)