aiohomematic 2025.8.6__tar.gz

aiohomematic-2025.8.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Daniel Perna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aiohomematic-2025.8.6/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: aiohomematic
+Version: 2025.8.6
+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>
+License: MIT License
+Project-URL: Source Code, https://github.com/sukramj/aiohomematic
+Project-URL: Bug Reports, https://github.com/sukramj/aiohomematic/issues
+Project-URL: Docs: Dev, https://github.com/sukramj/aiohomematic
+Project-URL: Forum, https://github.com/sukramj/aiohomematic/discussions
+Keywords: home,automation,homematic
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.13.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.10.0
+Requires-Dist: orjson>=3.10.0
+Requires-Dist: python-slugify>=8.0.0
+Requires-Dist: voluptuous>=0.14.0
+Dynamic: license-file
+
+# AIO Homematic (hahomematic)
+
+A lightweight Python 3 library that powers Home Assistant integrations for controlling and monitoring [HomeMatic](https://www.eq-3.com/products/homematic.html) and [HomematicIP](https://www.homematic-ip.com/en/start.html) devices. Some third‑party devices/gateways (e.g., Bosch, Intertechno) may be supported as well.
+
+This project is the modern successor to [pyhomematic](https://github.com/danielperna84/pyhomematic), focusing on automatic entity creation, fewer manual device definitions, and faster startups.
+
+## How it works
+
+Unlike pyhomematic, which required manual device mappings, aiohomematic automatically creates entities for each relevant parameter on every device channel (unless blacklisted). To achieve this it:
+
+- Fetches and caches device paramsets (VALUES) for fast successive startups.
+- Provides hooks for custom entity classes where complex behavior is needed (e.g., thermostats, lights, covers, climate, locks, sirens).
+- Includes helpers for robust operation, such as automatic reconnection after CCU restarts.
+
+## Key features
+
+- Automatic entity discovery from device/channel parameters.
+- Extensible via custom entity classes for complex devices.
+- Caching of paramsets to speed up restarts.
+- Designed to integrate with Home Assistant.
+
+## Installation (with Home Assistant)
+
+Install via the custom component: [custom_homematic](https://github.com/sukramj/custom_homematic).
+
+Follow the installation guide: https://github.com/sukramj/custom_homematic/wiki/Installation
+
+## Requirements
+
+Due to a bug in earlier CCU2/CCU3 firmware, aiohomematic requires at least the following versions when used with HomematicIP devices:
+
+- CCU2: 2.53.27
+- CCU3: 3.53.26
+
+See details here: https://github.com/jens-maus/RaspberryMatic/issues/843. Other CCU‑like platforms using the buggy HmIPServer version are not supported.
+
+## Useful links
+
+- Examples: see example.py in this repository.
+- Changelog: see changelog.md.
+- Source code and documentation: this repository (docs/ directory may contain additional information).

aiohomematic-2025.8.6/README.md

@@ -0,0 +1,41 @@
+# AIO Homematic (hahomematic)
+
+A lightweight Python 3 library that powers Home Assistant integrations for controlling and monitoring [HomeMatic](https://www.eq-3.com/products/homematic.html) and [HomematicIP](https://www.homematic-ip.com/en/start.html) devices. Some third‑party devices/gateways (e.g., Bosch, Intertechno) may be supported as well.
+
+This project is the modern successor to [pyhomematic](https://github.com/danielperna84/pyhomematic), focusing on automatic entity creation, fewer manual device definitions, and faster startups.
+
+## How it works
+
+Unlike pyhomematic, which required manual device mappings, aiohomematic automatically creates entities for each relevant parameter on every device channel (unless blacklisted). To achieve this it:
+
+- Fetches and caches device paramsets (VALUES) for fast successive startups.
+- Provides hooks for custom entity classes where complex behavior is needed (e.g., thermostats, lights, covers, climate, locks, sirens).
+- Includes helpers for robust operation, such as automatic reconnection after CCU restarts.
+
+## Key features
+
+- Automatic entity discovery from device/channel parameters.
+- Extensible via custom entity classes for complex devices.
+- Caching of paramsets to speed up restarts.
+- Designed to integrate with Home Assistant.
+
+## Installation (with Home Assistant)
+
+Install via the custom component: [custom_homematic](https://github.com/sukramj/custom_homematic).
+
+Follow the installation guide: https://github.com/sukramj/custom_homematic/wiki/Installation
+
+## Requirements
+
+Due to a bug in earlier CCU2/CCU3 firmware, aiohomematic requires at least the following versions when used with HomematicIP devices:
+
+- CCU2: 2.53.27
+- CCU3: 3.53.26
+
+See details here: https://github.com/jens-maus/RaspberryMatic/issues/843. Other CCU‑like platforms using the buggy HmIPServer version are not supported.
+
+## Useful links
+
+- Examples: see example.py in this repository.
+- Changelog: see changelog.md.
+- Source code and documentation: this repository (docs/ directory may contain additional information).

aiohomematic-2025.8.6/aiohomematic/__init__.py

@@ -0,0 +1,47 @@
+"""
+AioHomematic: a Python 3 library to interact with HomeMatic and HomematicIP backends.
+
+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.
+
+Key layers and responsibilities:
+- aiohomematic.central: Orchestrates clients, caches, device creation and events.
+- aiohomematic.client: Interface-specific clients (JSON-RPC/XML-RPC, Homegear) handling IO.
+- aiohomematic.model: Data point abstraction for generic, hub, and calculated entities.
+- aiohomematic.caches: Persistent and runtime caches for descriptions, values, and metadata.
+
+Typical usage is to construct a CentralConfig, create a CentralUnit and start it, then
+consume data points and events or issue write commands via the exposed API.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import signal
+import sys
+import threading
+from typing import Final
+
+from aiohomematic import central as hmcu
+from aiohomematic.const import VERSION
+
+if sys.stdout.isatty():
+    logging.basicConfig(level=logging.INFO)
+
+__version__: Final = VERSION
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+# pylint: disable=unused-argument
+# noinspection PyUnusedLocal
+def signal_handler(sig, frame):  # type: ignore[no-untyped-def]
+    """Handle signal to shut down central."""
+    _LOGGER.info("Got signal: %s. Shutting down central", str(sig))
+    signal.signal(signal.SIGINT, signal.SIG_DFL)
+    for central in hmcu.CENTRAL_INSTANCES.values():
+        asyncio.run_coroutine_threadsafe(central.stop(), asyncio.get_running_loop())
+
+
+if threading.current_thread() is threading.main_thread() and sys.stdout.isatty():
+    signal.signal(signal.SIGINT, signal_handler)

aiohomematic-2025.8.6/aiohomematic/async_support.py

@@ -0,0 +1,146 @@
+"""Module with support for loop interaction."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Collection, Coroutine
+from concurrent.futures import ThreadPoolExecutor
+from concurrent.futures._base import CancelledError
+from functools import wraps
+import logging
+from time import monotonic
+from typing import Any, Final, cast
+
+from aiohomematic.const import BLOCK_LOG_TIMEOUT
+from aiohomematic.exceptions import AioHomematicException
+from aiohomematic.support import debug_enabled, extract_exc_args
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class Looper:
+    """Helper class for event loop support."""
+
+    def __init__(self) -> None:
+        """Init the loop helper."""
+        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."""
+        # To flush out any call_soon_threadsafe
+        await asyncio.sleep(0)
+        start_time: float | None = None
+        current_task = asyncio.current_task()
+        while tasks := [task for task in self._tasks if task is not current_task and not cancelling(task)]:
+            await self._await_and_log_pending(tasks)
+
+            if start_time is None:
+                # Avoid calling monotonic() until we know
+                # we may need to start logging blocked tasks.
+                start_time = 0
+            elif start_time == 0:
+                # If we have waited twice then we set the start
+                # time
+                start_time = monotonic()
+            elif monotonic() - start_time > BLOCK_LOG_TIMEOUT:
+                # We have waited at least three loops and new tasks
+                # continue to block. At this point we start
+                # logging all waiting tasks.
+                for task in tasks:
+                    _LOGGER.debug("Waiting for task: %s", task)
+
+    async def _await_and_log_pending(self, pending: Collection[asyncio.Future[Any]]) -> None:
+        """Await and log tasks that take a long time."""
+        wait_time = 0
+        while pending:
+            _, pending = await asyncio.wait(pending, timeout=BLOCK_LOG_TIMEOUT)
+            if not pending:
+                return
+            wait_time += BLOCK_LOG_TIMEOUT
+            for task in pending:
+                _LOGGER.debug("Waited %s seconds for task: %s", wait_time, task)
+
+    def create_task(self, target: Coroutine[Any, Any, Any], name: str) -> None:
+        """Add task to the executor pool."""
+        try:
+            self._loop.call_soon_threadsafe(self._async_create_task, target, name)
+        except CancelledError:
+            _LOGGER.debug(
+                "create_task: task cancelled for %s",
+                name,
+            )
+            return
+
+    def _async_create_task[R](self, target: Coroutine[Any, Any, R], name: str) -> asyncio.Task[R]:
+        """Create a task from within the event_loop. This method must be run in the event_loop."""
+        task = self._loop.create_task(target, name=name)
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.remove)
+        return task
+
+    def run_coroutine(self, coro: Coroutine, name: str) -> Any:
+        """Call coroutine from sync."""
+        try:
+            return asyncio.run_coroutine_threadsafe(coro, self._loop).result()
+        except CancelledError:  # pragma: no cover
+            _LOGGER.debug(
+                "run_coroutine: coroutine interrupted for %s",
+                name,
+            )
+            return None
+
+    def async_add_executor_job[T](
+        self,
+        target: Callable[..., T],
+        *args: Any,
+        name: str,
+        executor: ThreadPoolExecutor | None = None,
+    ) -> asyncio.Future[T]:
+        """Add an executor job from within the event_loop."""
+        try:
+            task = self._loop.run_in_executor(executor, target, *args)
+            self._tasks.add(task)
+            task.add_done_callback(self._tasks.remove)
+        except (TimeoutError, CancelledError) as err:  # pragma: no cover
+            message = f"async_add_executor_job: task cancelled for {name} [{extract_exc_args(exc=err)}]"
+            _LOGGER.debug(message)
+            raise AioHomematicException(message) from err
+        return task
+
+    def cancel_tasks(self) -> None:
+        """Cancel running tasks."""
+        for task in self._tasks.copy():
+            if not task.cancelled():
+                task.cancel()
+
+
+def cancelling(task: asyncio.Future[Any]) -> bool:
+    """Return True if task is cancelling."""
+    return bool((cancelling_ := getattr(task, "cancelling", None)) and cancelling_())
+
+
+def loop_check[**P, R](func: Callable[P, R]) -> Callable[P, R]:
+    """Annotation to mark method that must be run within the event loop."""
+
+    _with_loop: set = set()
+
+    @wraps(func)
+    def wrapper_loop_check(*args: P.args, **kwargs: P.kwargs) -> R:
+        """Wrap loop check."""
+        return_value = func(*args, **kwargs)
+
+        try:
+            asyncio.get_running_loop()
+            loop_running = True
+        except Exception:
+            loop_running = False
+
+        if not loop_running and func not in _with_loop:
+            _with_loop.add(func)
+            _LOGGER.warning("Method %s must run in the event_loop. No loop detected.", func.__name__)
+
+        return return_value
+
+    setattr(func, "_loop_check", True)
+    return cast(Callable[P, R], wrapper_loop_check) if debug_enabled() else func

aiohomematic-2025.8.6/aiohomematic/caches/__init__.py

@@ -0,0 +1,10 @@
+"""
+Cache packages for AioHomematic.
+
+This package groups cache implementations used throughout the library:
+- persistent: Long-lived on-disk caches for device and paramset descriptions.
+- dynamic: Short-lived in-memory caches for runtime values and connection health.
+- visibility: Parameter visibility rules to decide which parameters are relevant.
+"""
+
+from __future__ import annotations