aiohomematic 2025.8.8__py3-none-any.whl → 2025.8.10__py3-none-any.whl

aiohomematic/__init__.py

@@ -1,6 +1,10 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 AioHomematic: a Python 3 library to interact with HomeMatic and HomematicIP backends.
 
+Public API at the top-level package is defined by __all__.
+
 This package provides a high-level API to discover devices and channels, read and write
 parameters (data points), receive events, and manage programs and system variables.
 
@@ -23,7 +27,7 @@ import sys
 import threading
 from typing import Final
 
-from aiohomematic import central as hmcu
+from aiohomematic import central as hmcu, validator as _ahm_validator
 from aiohomematic.const import VERSION
 
 if sys.stdout.isatty():
@@ -43,5 +47,15 @@ def signal_handler(sig, frame):  # type: ignore[no-untyped-def]
         asyncio.run_coroutine_threadsafe(central.stop(), asyncio.get_running_loop())
 
 
+# Perform lightweight startup validation once on import
+try:
+    _ahm_validator.validate_startup()
+except Exception as _exc:  # pragma: no cover
+    # Fail-fast with a clear message if validation fails during import
+    raise RuntimeError(f"AioHomematic startup validation failed: {_exc}") from _exc
+
 if threading.current_thread() is threading.main_thread() and sys.stdout.isatty():
     signal.signal(signal.SIGINT, signal_handler)
+
+# Define public API for the top-level package
+__all__ = ["__version__"]

aiohomematic/async_support.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """Module with support for loop interaction."""
 
 from __future__ import annotations
@@ -26,13 +28,24 @@ class Looper:
         self._tasks: Final[set[asyncio.Future[Any]]] = set()
         self._loop = asyncio.get_event_loop()
 
-    async def block_till_done(self) -> None:
-        """Block until all pending work is done."""
+    async def block_till_done(self, wait_time: float | None = None) -> None:
+        """
+        Block until all pending work is done.
+
+        If wait_time is set, stop waiting after the given number of seconds and log remaining tasks.
+        """
         # To flush out any call_soon_threadsafe
         await asyncio.sleep(0)
         start_time: float | None = None
+        deadline: float | None = (monotonic() + wait_time) if wait_time is not None else None
         current_task = asyncio.current_task()
         while tasks := [task for task in self._tasks if task is not current_task and not cancelling(task)]:
+            # If we have a deadline and have exceeded it, log remaining tasks and break
+            if deadline is not None and monotonic() >= deadline:
+                for task in tasks:
+                    _LOGGER.warning("Shutdown timeout reached; task still pending: %s", task)
+                break
+
             await self._await_and_log_pending(tasks)
 
             if start_time is None:

aiohomematic/caches/__init__.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Cache packages for AioHomematic.
 

aiohomematic/caches/dynamic.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Dynamic caches used at runtime by the central unit and clients.
 

aiohomematic/caches/persistent.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2025 Daniel Perna, SukramJ
 """
 Persistent caches used to persist HomeMatic metadata between runs.
 
@@ -208,9 +210,15 @@ class DeviceDescriptionCache(BasePersistentCache):
 
     def add_device(self, interface_id: str, device_description: DeviceDescription) -> None:
         """Add a device to the cache."""
+        # Fast-path: If the address is not yet known, skip costly removal operations.
+        if (address := device_description["ADDRESS"]) not in self._device_descriptions[interface_id]:
+            self._raw_device_descriptions[interface_id].append(device_description)
+            self._process_device_description(interface_id=interface_id, device_description=device_description)
+            return
+        # Address exists: remove old entries before adding the new description.
         self._remove_device(
             interface_id=interface_id,
-            addresses_to_remove=[device_description["ADDRESS"]],
+            addresses_to_remove=[address],
         )
         self._raw_device_descriptions[interface_id].append(device_description)
         self._process_device_description(interface_id=interface_id, device_description=device_description)
@@ -228,23 +236,22 @@ class DeviceDescriptionCache(BasePersistentCache):
 
     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_to_remove
+            device for device in self._raw_device_descriptions[interface_id] if device["ADDRESS"] not in addresses_set
         ]
-        for address in addresses_to_remove:
-            try:
-                if ADDRESS_SEPARATOR not in address and self._addresses[interface_id].get(address):
-                    del self._addresses[interface_id][address]
-                if self._device_descriptions[interface_id].get(address):
-                    del self._device_descriptions[interface_id][address]
-            except KeyError:
-                _LOGGER.warning("REMOVE_DEVICE failed: Unable to delete: %s", address)
-
-    def get_addresses(self, interface_id: str) -> tuple[str, ...]:
-        """Return the addresses by interface."""
-        return tuple(self._addresses[interface_id].keys())
+        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)
+
+    def get_addresses(self, interface_id: str) -> frozenset[str]:
+        """Return the addresses by interface as a set."""
+        return frozenset(self._addresses[interface_id])
 
     def get_device_descriptions(self, interface_id: str) -> Mapping[str, DeviceDescription]:
         """Return the devices by interface."""
@@ -288,9 +295,10 @@ class DeviceDescriptionCache(BasePersistentCache):
         device_address = get_device_address(address)
         self._device_descriptions[interface_id][address] = device_description
 
-        if device_address not in self._addresses[interface_id][device_address]:
-            self._addresses[interface_id][device_address].add(device_address)
-        self._addresses[interface_id][device_address].add(address)
+        # 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)
 
     async def load(self) -> DataOperationResult:
         """Load device data from disk into _device_description_cache."""
@@ -420,13 +428,12 @@ class ParamsetDescriptionCache(BasePersistentCache):
     def _add_address_parameter(self, channel_address: str, paramsets: list[dict[str, Any]]) -> None:
         """Add address parameter to cache."""
         device_address, channel_no = get_split_channel_address(channel_address)
+        cache = self._address_parameter_cache
         for paramset in paramsets:
             if not paramset:
                 continue
             for parameter in paramset:
-                if (device_address, parameter) not in self._address_parameter_cache:
-                    self._address_parameter_cache[(device_address, parameter)] = set()
-                self._address_parameter_cache[(device_address, parameter)].add(channel_no)
+                cache.setdefault((device_address, parameter), set()).add(channel_no)
 
     async def load(self) -> DataOperationResult:
         """Load paramset descriptions from disk into paramset cache."""