aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/client/_rpc_errors.py

@@ -0,0 +1,187 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Error mapping helpers for RPC transports.
+
+This module centralizes small, transport-agnostic utilities to turn the backend
+errors into domain-specific exceptions with useful context. It is used by both
+JSON-RPC and XML-RPC clients.
+
+Key types and functions
+- RpcContext: Lightweight context container that formats protocol/method/host
+  for readable error messages and logs.
+- map_jsonrpc_error: Maps a JSON-RPC error object to an appropriate exception
+  (AuthFailure, InternalBackendException, ClientException).
+- map_transport_error: Maps generic transport-level exceptions like OSError to
+  domain exceptions (NoConnectionException/ClientException).
+- map_xmlrpc_fault: Maps XML-RPC faults to domain exceptions with context.
+- sanitize_error_message: Sanitizes error messages to remove sensitive data.
+"""
+
+from __future__ import annotations
+
+from asyncio import TimeoutError as AsyncTimeoutError
+from collections.abc import Mapping
+from dataclasses import dataclass
+import re
+from typing import Any, Final
+
+from aiohomematic.const import FailureReason
+from aiohomematic.exceptions import (
+    AuthFailure,
+    CircuitBreakerOpenException,
+    ClientException,
+    InternalBackendException,
+    NoConnectionException,
+)
+
+# Patterns that may contain sensitive information
+_SENSITIVE_PATTERNS: Final[tuple[tuple[str, str], ...]] = (
+    # IP addresses (IPv4)
+    (r"\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b", "<ip-redacted>"),
+    # Hostnames with domains
+    (r"\b[a-zA-Z0-9][-a-zA-Z0-9]*(\.[a-zA-Z0-9][-a-zA-Z0-9]*)+\b", "<host-redacted>"),
+    # Session IDs (common patterns)
+    (r"['\"]?session[_-]?id['\"]?\s*[:=]\s*['\"]?[\w-]+['\"]?", "session_id=<redacted>"),
+    # Passwords in URLs or params
+    (r"['\"]?password['\"]?\s*[:=]\s*['\"][^'\"]*['\"]", "password=<redacted>"),
+    (r"['\"]?passwd['\"]?\s*[:=]\s*['\"][^'\"]*['\"]", "passwd=<redacted>"),
+)
+
+
+def sanitize_error_message(*, message: str) -> str:
+    """
+    Sanitize error message by removing potentially sensitive information.
+
+    Removes or masks:
+    - IP addresses
+    - Hostnames
+    - Session IDs
+    - Passwords
+
+    Args:
+        message: The error message to sanitize.
+
+    Returns:
+        Sanitized error message.
+
+    """
+    result = message
+    for pattern, replacement in _SENSITIVE_PATTERNS:
+        result = re.sub(pattern, replacement, result, flags=re.IGNORECASE)
+    return result
+
+
+@dataclass(slots=True)
+class RpcContext:
+    """
+    Context container for RPC operations.
+
+    Provides formatted output for error messages with optional sanitization
+    to protect sensitive information in logs.
+    """
+
+    protocol: str
+    method: str
+    host: str | None = None
+    interface: str | None = None
+    params: Mapping[str, Any] | None = None
+
+    def fmt(self, *, sanitize: bool = False) -> str:
+        """
+        Format context for error messages.
+
+        Args:
+            sanitize: If True, omit host information for security.
+
+        Returns:
+            Formatted context string.
+
+        """
+        parts: list[str] = [f"protocol={self.protocol}", f"method={self.method}"]
+        if self.interface:
+            parts.append(f"interface={self.interface}")
+        if self.host and not sanitize:
+            parts.append(f"host={self.host}")
+        return ", ".join(parts)
+
+    def fmt_sanitized(self) -> str:
+        """Format context with sensitive information redacted."""
+        return self.fmt(sanitize=True)
+
+
+def map_jsonrpc_error(*, error: Mapping[str, Any], ctx: RpcContext) -> Exception:
+    """Map JSON-RPC error to exception."""
+    # JSON-RPC 2.0 like error: {code, message, data?}
+    code = int(error.get("code", 0))
+    message = str(error.get("message", ""))
+    # Enrich message with context
+    base_msg = f"{message} ({ctx.fmt()})"
+
+    # Map common codes
+    if message.startswith("access denied") or code in (401, -32001):
+        return AuthFailure(base_msg)
+    if "internal error" in message.lower() or code in (-32603, 500):
+        return InternalBackendException(base_msg)
+    # Generic client exception for others
+    return ClientException(base_msg)
+
+
+def map_transport_error(*, exc: BaseException, ctx: RpcContext) -> Exception:
+    """Map transport error to exception."""
+    msg = f"{exc} ({ctx.fmt()})"
+    if isinstance(exc, OSError):
+        return NoConnectionException(msg)
+    return ClientException(msg)
+
+
+def map_xmlrpc_fault(*, code: int, fault_string: str, ctx: RpcContext) -> Exception:
+    """Map XML-RPC fault to exception."""
+    # Enrich message with context
+    fault_msg = f"XMLRPC Fault {code}: {fault_string} ({ctx.fmt()})"
+    # Simple mappings
+    if "unauthorized" in fault_string.lower():
+        return AuthFailure(fault_msg)
+    if "internal" in fault_string.lower():
+        return InternalBackendException(fault_msg)
+    return ClientException(fault_msg)
+
+
+def exception_to_failure_reason(*, exc: BaseException) -> FailureReason:
+    """
+    Map an exception to a FailureReason enum value.
+
+    This function translates exceptions into categorized failure reasons
+    that can be used by state machines and propagated to integrations.
+
+    Args:
+        exc: The exception to categorize.
+
+    Returns:
+        The appropriate FailureReason for the exception type.
+
+    Example:
+        ```python
+        try:
+            await client.login()
+        except BaseException as exc:
+            reason = exception_to_failure_reason(exc=exc)
+            state_machine.transition_to(
+                target=ClientState.FAILED,
+                reason=str(exc),
+                failure_reason=reason,
+            )
+        ```
+
+    """
+    if isinstance(exc, AuthFailure):
+        return FailureReason.AUTH
+    if isinstance(exc, NoConnectionException):
+        return FailureReason.NETWORK
+    if isinstance(exc, InternalBackendException):
+        return FailureReason.INTERNAL
+    if isinstance(exc, CircuitBreakerOpenException):
+        return FailureReason.CIRCUIT_BREAKER
+    if isinstance(exc, TimeoutError | AsyncTimeoutError):
+        return FailureReason.TIMEOUT
+    return FailureReason.UNKNOWN

aiohomematic/client/backends/__init__.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Backend implementations for different Homematic systems.
+
+This package provides backend-specific implementations that abstract
+the transport layer (XML-RPC, JSON-RPC) from the client business logic.
+
+Public API
+----------
+- BackendOperationsProtocol: Interface for all backend operations
+- BackendCapabilities: Capability flags dataclass
+- CcuBackend: CCU backend (XML-RPC + JSON-RPC)
+- JsonCcuBackend: CCU-Jack backend (JSON-RPC only)
+- HomegearBackend: Homegear backend (XML-RPC with extensions)
+- create_backend: Factory function to create appropriate backend
+
+"""
+
+from __future__ import annotations
+
+from aiohomematic.client.backends.capabilities import (
+    CCU_CAPABILITIES,
+    HOMEGEAR_CAPABILITIES,
+    JSON_CCU_CAPABILITIES,
+    BackendCapabilities,
+)
+from aiohomematic.client.backends.ccu import CcuBackend
+from aiohomematic.client.backends.factory import create_backend
+from aiohomematic.client.backends.homegear import HomegearBackend
+from aiohomematic.client.backends.json_ccu import JsonCcuBackend
+from aiohomematic.client.backends.protocol import BackendOperationsProtocol
+
+__all__ = [
+    # Protocol
+    "BackendOperationsProtocol",
+    # Capabilities
+    "BackendCapabilities",
+    "CCU_CAPABILITIES",
+    "HOMEGEAR_CAPABILITIES",
+    "JSON_CCU_CAPABILITIES",
+    # Backends
+    "CcuBackend",
+    "HomegearBackend",
+    "JsonCcuBackend",
+    # Factory
+    "create_backend",
+]

aiohomematic/client/backends/base.py

@@ -0,0 +1,335 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+# pylint: disable=unnecessary-ellipsis
+"""
+Base backend class with shared functionality.
+
+Provides default implementations that return empty/False for unsupported
+operations, allowing subclasses to only implement what they support.
+
+Public API
+----------
+- BaseBackend: Abstract base class for backend implementations
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+import logging
+from typing import TYPE_CHECKING, Any, Final
+
+from aiohomematic.client.backends.capabilities import BackendCapabilities
+from aiohomematic.const import (
+    BackupData,
+    CommandRxMode,
+    DescriptionMarker,
+    DeviceDescription,
+    DeviceDetail,
+    InboxDeviceData,
+    Interface,
+    ParameterData,
+    ParamsetKey,
+    ProgramData,
+    ServiceMessageData,
+    ServiceMessageType,
+    SystemInformation,
+    SystemUpdateData,
+    SystemVariableData,
+)
+
+if TYPE_CHECKING:
+    from aiohomematic.client.circuit_breaker import CircuitBreaker
+
+__all__ = ["BaseBackend"]
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+class BaseBackend(ABC):
+    """
+    Abstract base class for backend implementations.
+
+    Provides default implementations that return empty/False for
+    unsupported operations, allowing subclasses to only implement
+    what they support.
+    """
+
+    __slots__ = (
+        "_capabilities",
+        "_interface",
+        "_interface_id",
+        "_system_information",
+    )
+
+    def __init__(
+        self,
+        *,
+        interface: Interface,
+        interface_id: str,
+        capabilities: BackendCapabilities,
+    ) -> None:
+        """Initialize the base backend."""
+        self._interface: Final = interface
+        self._interface_id: Final = interface_id
+        self._capabilities = capabilities
+        self._system_information: SystemInformation
+
+    @property
+    def all_circuit_breakers_closed(self) -> bool:
+        """Return True if all circuit breakers are in closed state."""
+        return True
+
+    @property
+    def capabilities(self) -> BackendCapabilities:
+        """Return the capability flags for this backend."""
+        return self._capabilities
+
+    @property
+    def circuit_breaker(self) -> CircuitBreaker | None:
+        """Return the primary circuit breaker for metrics access."""
+        return None
+
+    @property
+    def interface(self) -> Interface:
+        """Return the interface type."""
+        return self._interface
+
+    @property
+    def interface_id(self) -> str:
+        """Return the interface identifier."""
+        return self._interface_id
+
+    @property
+    @abstractmethod
+    def model(self) -> str:
+        """Return the backend model name."""
+        ...
+
+    @property
+    def system_information(self) -> SystemInformation:
+        """Return system information."""
+        return self._system_information
+
+    async def accept_device_in_inbox(self, *, device_address: str) -> bool:
+        """Accept inbox device (unsupported by default)."""
+        return False
+
+    async def add_link(
+        self,
+        *,
+        sender_address: str,
+        receiver_address: str,
+        name: str,
+        description: str,
+    ) -> None:
+        """Add link (unsupported by default)."""
+
+    @abstractmethod
+    async def check_connection(self, *, handle_ping_pong: bool, caller_id: str | None = None) -> bool:
+        """Check if connection is alive."""
+        ...
+
+    async def create_backup_and_download(
+        self,
+        *,
+        max_wait_time: float = 300.0,
+        poll_interval: float = 5.0,
+    ) -> BackupData | None:
+        """Create backup (unsupported by default)."""
+        return None
+
+    @abstractmethod
+    async def deinit_proxy(self, *, init_url: str) -> None:
+        """De-initialize proxy."""
+        ...
+
+    async def delete_system_variable(self, *, name: str) -> bool:
+        """Delete system variable (unsupported by default)."""
+        return False
+
+    async def execute_program(self, *, pid: str) -> bool:
+        """Execute program (unsupported by default)."""
+        return False
+
+    async def get_all_device_data(self, *, interface: Interface) -> dict[str, Any] | None:
+        """Return all device data (unsupported by default)."""
+        return None
+
+    async def get_all_functions(self) -> dict[str, set[str]]:
+        """Return all functions (unsupported by default)."""
+        return {}
+
+    async def get_all_programs(self, *, markers: tuple[DescriptionMarker | str, ...]) -> tuple[ProgramData, ...]:
+        """Return all programs (unsupported by default)."""
+        return ()
+
+    async def get_all_rooms(self) -> dict[str, set[str]]:
+        """Return all rooms (unsupported by default)."""
+        return {}
+
+    async def get_all_system_variables(
+        self, *, markers: tuple[DescriptionMarker | str, ...]
+    ) -> tuple[SystemVariableData, ...] | None:
+        """Return all system variables (unsupported by default)."""
+        return None
+
+    @abstractmethod
+    async def get_device_description(self, *, address: str) -> DeviceDescription | None:
+        """Return device description for address."""
+        ...
+
+    async def get_device_details(self, *, addresses: tuple[str, ...] | None = None) -> list[DeviceDetail] | None:
+        """Return device details (unsupported by default)."""
+        return None
+
+    async def get_inbox_devices(self) -> tuple[InboxDeviceData, ...]:
+        """Return inbox devices (unsupported by default)."""
+        return ()
+
+    async def get_install_mode(self) -> int:
+        """Return install mode time (unsupported by default)."""
+        return 0
+
+    async def get_link_peers(self, *, address: str) -> tuple[str, ...]:
+        """Return link peers (unsupported by default)."""
+        return ()
+
+    async def get_links(self, *, address: str, flags: int) -> dict[str, Any]:
+        """Return links (unsupported by default)."""
+        return {}
+
+    async def get_metadata(self, *, address: str, data_id: str) -> dict[str, Any]:
+        """Return metadata (unsupported by default)."""
+        return {}
+
+    @abstractmethod
+    async def get_paramset(self, *, address: str, paramset_key: ParamsetKey | str) -> dict[str, Any]:
+        """Return paramset."""
+        ...
+
+    @abstractmethod
+    async def get_paramset_description(
+        self, *, address: str, paramset_key: ParamsetKey
+    ) -> dict[str, ParameterData] | None:
+        """Return paramset description."""
+        ...
+
+    async def get_rega_id_by_address(self, *, address: str) -> int | None:
+        """Return ReGa ID (unsupported by default)."""
+        return None
+
+    async def get_service_messages(
+        self, *, message_type: ServiceMessageType | None = None
+    ) -> tuple[ServiceMessageData, ...]:
+        """Return service messages (unsupported by default)."""
+        return ()
+
+    async def get_system_update_info(self) -> SystemUpdateData | None:
+        """Return system update info (unsupported by default)."""
+        return None
+
+    async def get_system_variable(self, *, name: str) -> Any:
+        """Return system variable value (unsupported by default)."""
+        return None
+
+    @abstractmethod
+    async def get_value(self, *, address: str, parameter: str) -> Any:
+        """Return parameter value."""
+        ...
+
+    async def has_program_ids(self, *, rega_id: int) -> bool:
+        """Check program IDs (unsupported by default)."""
+        return False
+
+    @abstractmethod
+    async def init_proxy(self, *, init_url: str, interface_id: str) -> None:
+        """Initialize proxy with callback URL."""
+        ...
+
+    @abstractmethod
+    async def initialize(self) -> None:
+        """Initialize the backend."""
+        ...
+
+    @abstractmethod
+    async def list_devices(self) -> tuple[DeviceDescription, ...] | None:
+        """Return all device descriptions."""
+        ...
+
+    @abstractmethod
+    async def put_paramset(
+        self,
+        *,
+        address: str,
+        paramset_key: ParamsetKey | str,
+        values: dict[str, Any],
+        rx_mode: CommandRxMode | None = None,
+    ) -> None:
+        """Set paramset values."""
+        ...
+
+    async def remove_link(self, *, sender_address: str, receiver_address: str) -> None:
+        """Remove link (unsupported by default)."""
+
+    async def rename_channel(self, *, rega_id: int, new_name: str) -> bool:
+        """Rename channel (unsupported by default)."""
+        return False
+
+    async def rename_device(self, *, rega_id: int, new_name: str) -> bool:
+        """Rename device (unsupported by default)."""
+        return False
+
+    async def report_value_usage(self, *, address: str, value_id: str, ref_counter: int) -> bool:
+        """Report value usage (unsupported by default)."""
+        return False
+
+    def reset_circuit_breakers(self) -> None:
+        """Reset all circuit breakers to closed state."""
+
+    async def set_install_mode(
+        self,
+        *,
+        on: bool = True,
+        time: int = 60,
+        mode: int = 1,
+        device_address: str | None = None,
+    ) -> bool:
+        """Set install mode (unsupported by default)."""
+        return False
+
+    async def set_metadata(self, *, address: str, data_id: str, value: dict[str, Any]) -> dict[str, Any]:
+        """Set metadata (unsupported by default)."""
+        return {}
+
+    async def set_program_state(self, *, pid: str, state: bool) -> bool:
+        """Set program state (unsupported by default)."""
+        return False
+
+    async def set_system_variable(self, *, name: str, value: Any) -> bool:
+        """Set system variable (unsupported by default)."""
+        return False
+
+    @abstractmethod
+    async def set_value(
+        self,
+        *,
+        address: str,
+        parameter: str,
+        value: Any,
+        rx_mode: CommandRxMode | None = None,
+    ) -> None:
+        """Set parameter value."""
+        ...
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """Stop the backend."""
+        ...
+
+    async def trigger_firmware_update(self) -> bool:
+        """Trigger system firmware update (unsupported by default)."""
+        return False
+
+    async def update_device_firmware(self, *, device_address: str) -> bool:
+        """Update device firmware (unsupported by default)."""
+        return False

aiohomematic/client/backends/capabilities.py

@@ -0,0 +1,138 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Backend capabilities dataclass.
+
+Consolidates all capability flags into a single immutable structure,
+replacing the 20+ properties spread across client classes.
+
+Public API
+----------
+- BackendCapabilities: Frozen dataclass with capability flags
+- CCU_CAPABILITIES: Default capabilities for CCU backend
+- JSON_CCU_CAPABILITIES: Default capabilities for CCU-Jack backend
+- HOMEGEAR_CAPABILITIES: Default capabilities for Homegear backend
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final
+
+__all__ = [
+    "BackendCapabilities",
+    "CCU_CAPABILITIES",
+    "HOMEGEAR_CAPABILITIES",
+    "JSON_CCU_CAPABILITIES",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class BackendCapabilities:
+    """
+    Immutable capability flags for a backend.
+
+    Consolidates the capability properties from ClientCCU, ClientJsonCCU,
+    and ClientHomegear into a single dataclass. Backends declare their
+    capabilities at initialization; clients expose them via the
+    `capabilities` property.
+    """
+
+    # Device Operations
+    device_firmware_update: bool = False
+    firmware_update_trigger: bool = False
+    firmware_updates: bool = False
+    linking: bool = False
+    value_usage_reporting: bool = False
+
+    # Metadata Operations
+    functions: bool = False
+    rooms: bool = False
+    metadata: bool = False
+    rename: bool = False
+    rega_id_lookup: bool = False
+    service_messages: bool = False
+    system_update_info: bool = False
+    inbox_devices: bool = False
+    install_mode: bool = False
+
+    # Programs & System Variables
+    programs: bool = False
+
+    # Backup
+    backup: bool = False
+
+    # Connection
+    ping_pong: bool = False
+    push_updates: bool = True
+    rpc_callback: bool = True
+
+
+# Default capability sets for each backend type.
+# These can be adjusted at runtime based on interface type or system info.
+
+CCU_CAPABILITIES: Final = BackendCapabilities(
+    device_firmware_update=True,
+    firmware_update_trigger=True,
+    firmware_updates=True,
+    linking=True,
+    value_usage_reporting=True,
+    functions=True,
+    rooms=True,
+    metadata=True,
+    rename=True,
+    rega_id_lookup=True,
+    service_messages=True,
+    system_update_info=True,
+    inbox_devices=True,
+    install_mode=True,
+    programs=True,
+    backup=True,
+    ping_pong=True,
+    push_updates=True,
+    rpc_callback=True,
+)
+
+JSON_CCU_CAPABILITIES: Final = BackendCapabilities(
+    device_firmware_update=False,
+    firmware_update_trigger=False,
+    firmware_updates=False,
+    linking=False,
+    value_usage_reporting=False,
+    functions=False,
+    rooms=False,
+    metadata=False,
+    rename=False,
+    rega_id_lookup=False,
+    service_messages=False,
+    system_update_info=False,
+    inbox_devices=False,
+    install_mode=False,
+    programs=False,
+    backup=False,
+    ping_pong=False,
+    push_updates=True,
+    rpc_callback=False,
+)
+
+HOMEGEAR_CAPABILITIES: Final = BackendCapabilities(
+    device_firmware_update=False,
+    firmware_update_trigger=False,
+    firmware_updates=False,
+    linking=False,
+    value_usage_reporting=False,
+    functions=False,
+    rooms=False,
+    metadata=False,
+    rename=False,
+    rega_id_lookup=False,
+    service_messages=False,
+    system_update_info=False,
+    inbox_devices=False,
+    install_mode=False,
+    programs=False,
+    backup=False,
+    ping_pong=False,
+    push_updates=True,
+    rpc_callback=True,
+)