aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/client/handlers/backup.py

@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Backup handler.
+
+Handles backup creation and download operations.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+import logging
+from typing import TYPE_CHECKING, Final
+
+from aiohomematic import i18n
+from aiohomematic.client.handlers.base import BaseHandler
+from aiohomematic.const import BackupData, BackupStatus, SystemInformation
+from aiohomematic.decorators import inspector
+from aiohomematic.interfaces import BackupOperationsProtocol
+from aiohomematic.property_decorators import DelegatedProperty
+
+if TYPE_CHECKING:
+    from aiohomematic.client import AioJsonRpcAioHttpClient, BaseRpcProxy
+    from aiohomematic.const import Interface
+    from aiohomematic.interfaces import ClientDependenciesProtocol
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class BackupHandler(BaseHandler, BackupOperationsProtocol):
+    """
+    Handler for backup operations.
+
+    Implements BackupOperationsProtocol protocol for ISP-compliant client operations.
+
+    Handles:
+    - Creating backups on the CCU
+    - Downloading backup files
+    """
+
+    __slots__ = ("_has_backup", "_system_information")
+
+    def __init__(
+        self,
+        *,
+        client_deps: ClientDependenciesProtocol,
+        interface: Interface,
+        interface_id: str,
+        json_rpc_client: AioJsonRpcAioHttpClient,
+        proxy: BaseRpcProxy,
+        proxy_read: BaseRpcProxy,
+        has_backup: bool,
+        system_information: SystemInformation,
+    ) -> None:
+        """Initialize the backup handler."""
+        super().__init__(
+            client_deps=client_deps,
+            interface=interface,
+            interface_id=interface_id,
+            json_rpc_client=json_rpc_client,
+            proxy=proxy,
+            proxy_read=proxy_read,
+        )
+        self._has_backup: Final = has_backup
+        self._system_information: Final = system_information
+
+    has_backup: Final = DelegatedProperty[bool](path="_has_backup")
+
+    @inspector(re_raise=False)
+    async def create_backup_and_download(
+        self,
+        *,
+        max_wait_time: float = 300.0,
+        poll_interval: float = 5.0,
+    ) -> BackupData | None:
+        """
+        Create a backup on the CCU and download it.
+
+        Start the backup process in the background and poll for completion.
+        This avoids blocking the ReGa scripting engine during backup creation.
+
+        Args:
+            max_wait_time: Maximum time to wait for backup completion in seconds.
+            poll_interval: Time between status polls in seconds.
+
+        Returns:
+            BackupData with filename and content, or None if backup creation or download failed.
+
+        """
+        if not self._has_backup:
+            _LOGGER.debug("CREATE_BACKUP_AND_DOWNLOAD: Not supported by client for %s", self._interface_id)
+            return None
+
+        # Start backup in background
+        if not await self._json_rpc_client.create_backup_start():
+            _LOGGER.warning(  # i18n-log: ignore
+                "CREATE_BACKUP_AND_DOWNLOAD: Failed to start backup process"
+            )
+            return None
+
+        _LOGGER.debug("CREATE_BACKUP_AND_DOWNLOAD: Backup process started, polling for completion")
+
+        # Poll for completion
+        elapsed = 0.0
+        while elapsed < max_wait_time:
+            await asyncio.sleep(poll_interval)
+            elapsed += poll_interval
+
+            status_data = await self._json_rpc_client.create_backup_status()
+
+            if status_data.status == BackupStatus.COMPLETED:
+                _LOGGER.info(
+                    i18n.tr(
+                        key="log.client.create_backup_and_download.completed",
+                        filename=status_data.filename,
+                        size=status_data.size,
+                    )
+                )
+                if (content := await self._json_rpc_client.download_backup()) is None:
+                    return None
+                return BackupData(filename=self._generate_filename(), content=content)
+
+            if status_data.status == BackupStatus.FAILED:
+                _LOGGER.warning(i18n.tr(key="log.client.create_backup_and_download.failed"))
+                return None
+
+            if status_data.status == BackupStatus.IDLE:
+                _LOGGER.warning(i18n.tr(key="log.client.create_backup_and_download.idle"))
+                return None
+
+            _LOGGER.info(
+                i18n.tr(
+                    key="log.client.create_backup_and_download.running",
+                    elapsed=elapsed,
+                )
+            )
+
+        _LOGGER.warning(
+            i18n.tr(
+                key="log.client.create_backup_and_download.timeout",
+                max_wait_time=max_wait_time,
+            )
+        )
+        return None
+
+    def _generate_filename(self) -> str:
+        """
+        Generate backup filename with hostname, version, and timestamp.
+
+        Format: <hostname>-<version>-<date>-<time>.sbk
+        Example: Otto-3.83.6.20251025-2025-12-10-1937.sbk
+        """
+        hostname = self._system_information.hostname or "CCU"
+        version = self._system_information.version or "unknown"
+        timestamp = datetime.now().strftime("%Y-%m-%d-%H%M")
+        return f"{hostname}-{version}-{timestamp}.sbk"

aiohomematic/client/handlers/base.py

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Base handler class for client operations.
+
+Provides common dependencies and shared functionality for all handler classes.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Final
+
+from aiohomematic.const import Interface
+from aiohomematic.decorators import inspector
+from aiohomematic.property_decorators import DelegatedProperty
+
+if TYPE_CHECKING:
+    from aiohomematic.client import AioJsonRpcAioHttpClient, BaseRpcProxy
+    from aiohomematic.interfaces import ClientDependenciesProtocol
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class BaseHandler:
+    """
+    Base class for all client handler classes.
+
+    Provides access to common dependencies needed by all handlers.
+    """
+
+    __slots__ = (
+        "_client_deps",
+        "_interface",
+        "_interface_id",
+        "_json_rpc_client",
+        "_proxy",
+        "_proxy_read",
+    )
+
+    def __init__(
+        self,
+        *,
+        client_deps: ClientDependenciesProtocol,
+        interface: Interface,
+        interface_id: str,
+        json_rpc_client: AioJsonRpcAioHttpClient,
+        proxy: BaseRpcProxy,
+        proxy_read: BaseRpcProxy,
+    ) -> None:
+        """
+        Initialize the base handler.
+
+        Args:
+            client_deps: Client dependencies for accessing central functionality.
+            interface: The interface type (e.g., HMIP_RF, BIDCOS_RF).
+            interface_id: Unique identifier for this interface.
+            json_rpc_client: JSON-RPC client for CCU communication.
+            proxy: XML-RPC proxy for write operations.
+            proxy_read: XML-RPC proxy for read operations (higher concurrency).
+
+        """
+        self._client_deps: Final = client_deps
+        self._interface: Final = interface
+        self._interface_id: Final = interface_id
+        self._json_rpc_client: Final = json_rpc_client
+        self._proxy: Final = proxy
+        self._proxy_read: Final = proxy_read
+
+    client_deps: Final = DelegatedProperty["ClientDependenciesProtocol"](path="_client_deps")
+    interface: Final = DelegatedProperty[Interface](path="_interface")
+    interface_id: Final = DelegatedProperty[str](path="_interface_id")
+    json_rpc_client: Final = DelegatedProperty["AioJsonRpcAioHttpClient"](path="_json_rpc_client")
+    proxy: Final = DelegatedProperty["BaseRpcProxy"](path="_proxy")
+    proxy_read: Final = DelegatedProperty["BaseRpcProxy"](path="_proxy_read")
+
+
+# Re-export inspector decorator for use in handlers
+__all__ = ["BaseHandler", "inspector"]