aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/central/events/integration.py

@@ -0,0 +1,424 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Integration-level events for Home Assistant and other consumers.
+
+Overview
+--------
+This module provides focused integration events that aggregate multiple internal
+events into consumer-friendly structures. These events are designed for:
+
+- Home Assistant integration (control_unit.py, generic_entity.py)
+- Third-party integrations
+- Monitoring and debugging tools
+
+Event Hierarchy
+---------------
+Integration Events (this module):
+    - SystemStatusChangedEvent: Infrastructure + lifecycle changes
+    - DeviceLifecycleEvent: Device creation, removal, availability
+    - DataPointsCreatedEvent: data point discovery
+    - DeviceTriggerEvent: Device triggers (button press, etc.)
+
+Data Point-Level Events (event_bus.py):
+    - DataPointUpdatedEvent: High-frequency value updates (per-data point subscription)
+
+Design Philosophy
+-----------------
+- Each event has a clear, single responsibility
+- Immutable dataclasses (frozen=True, slots=True) for safety and performance
+- Minimal payload - only relevant fields are populated
+- Targeted registration - subscribe only to what you need
+
+Example Usage
+-------------
+    from aiohomematic.central.events import (
+        SystemStatusChangedEvent,
+        DeviceLifecycleEvent,
+        DataPointsCreatedEvent,
+        DeviceTriggerEvent,
+    )
+
+    # Subscribe to system status changes
+    central.event_bus.subscribe(
+        event_type=SystemStatusChangedEvent,
+        event_key=None,
+        handler=on_system_status,
+    )
+
+    # Subscribe to device lifecycle events
+    central.event_bus.subscribe(
+        event_type=DeviceLifecycleEvent,
+        event_key=None,
+        handler=on_device_lifecycle,
+    )
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING, Any
+
+from aiohomematic.central.events.types import Event
+from aiohomematic.const import (
+    CentralState,
+    ClientState,
+    DataPointCategory,
+    DeviceTriggerEventType,
+    FailureReason,
+    IntegrationIssueSeverity,
+    IntegrationIssueType,
+    PingPongMismatchType,
+)
+
+if TYPE_CHECKING:
+    from aiohomematic.interfaces import CallbackDataPointProtocol
+
+
+__all__ = [
+    "DataPointsCreatedEvent",
+    "DeviceLifecycleEvent",
+    "DeviceLifecycleEventType",
+    "DeviceTriggerEvent",
+    "IntegrationIssue",
+    "SystemStatusChangedEvent",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class IntegrationIssue:
+    """
+    Issue that should be presented to user via integration's UI.
+
+    Used to communicate problems that require user attention
+    (e.g., connection failures, configuration errors).
+
+    Example:
+        ```python
+        # Creating a ping-pong mismatch issue
+        issue = IntegrationIssue(
+            issue_type=IntegrationIssueType.PING_PONG_MISMATCH,
+            severity=IntegrationIssueSeverity.WARNING,
+            interface_id="ccu-HmIP-RF",
+            mismatch_type=PingPongMismatchType.PENDING,
+            mismatch_count=5,
+        )
+
+        # Creating a fetch data failed issue
+        issue = IntegrationIssue(
+            issue_type=IntegrationIssueType.FETCH_DATA_FAILED,
+            severity=IntegrationIssueSeverity.WARNING,
+            interface_id="ccu-BidCos-RF",
+        )
+
+        # Accessing computed properties for HA integration
+        issue.issue_id  # "ping_pong_mismatch_ccu-HmIP-RF"
+        issue.translation_key  # "ping_pong_mismatch"
+        issue.translation_placeholders  # {"interface_id": "ccu-HmIP-RF", ...}
+        ```
+
+    """
+
+    issue_type: IntegrationIssueType
+    """Type of issue - determines translation_key and issue_id prefix."""
+
+    severity: IntegrationIssueSeverity
+    """Issue severity level."""
+
+    interface_id: str
+    """Interface ID where the issue occurred."""
+
+    mismatch_type: PingPongMismatchType | None = None
+    """Mismatch type (only for PING_PONG_MISMATCH issues)."""
+
+    mismatch_count: int | None = None
+    """Mismatch count (only for PING_PONG_MISMATCH issues)."""
+
+    @property
+    def issue_id(self) -> str:
+        """Generate unique issue ID from type and interface."""
+        return f"{self.issue_type.value}_{self.interface_id}"
+
+    @property
+    def translation_key(self) -> str:
+        """Return translation key (same as issue_type value)."""
+        return self.issue_type.value
+
+    @property
+    def translation_placeholders(self) -> dict[str, str]:
+        """Return all placeholders for translation interpolation."""
+        result: dict[str, str] = {"interface_id": self.interface_id}
+        if self.mismatch_type is not None:
+            result["mismatch_type"] = self.mismatch_type.value
+        if self.mismatch_count is not None:
+            result["mismatch_count"] = str(self.mismatch_count)
+        return result
+
+
+@dataclass(frozen=True, slots=True)
+class SystemStatusChangedEvent(Event):
+    """
+    System infrastructure and lifecycle status event.
+
+    Aggregates: CentralStateChangedEvent, ConnectionStateChangedEvent,
+    ClientStateChangedEvent, CallbackStateChangedEvent, FetchDataFailedEvent,
+    PingPongMismatchEvent.
+
+    **HA Registration Point**: `control_unit.py`
+
+    Example:
+        ```python
+        async def on_system_status(*, event: SystemStatusChangedEvent) -> None:
+            if event.central_state == CentralState.FAILED:
+                if event.failure_reason == FailureReason.AUTH:
+                    async_create_issue(..., translation_key="auth_failed")
+                elif event.failure_reason == FailureReason.NETWORK:
+                    async_create_issue(..., translation_key="connection_failed")
+
+            elif event.central_state == CentralState.DEGRADED:
+                # Show status per degraded interface
+                for iface_id, reason in (event.degraded_interfaces or {}).items():
+                    _LOGGER.warning("Interface %s degraded: %s", iface_id, reason)
+
+            for issue in event.issues:
+                async_create_issue(...)
+
+        central.event_bus.subscribe(
+            event_type=SystemStatusChangedEvent,
+            event_key=None,
+            handler=on_system_status,
+        )
+        ```
+
+    """
+
+    # Lifecycle
+    central_state: CentralState | None = None
+    """Central unit state change (STARTING, INITIALIZING, RUNNING, DEGRADED, RECOVERING, FAILED, STOPPED)."""
+
+    # Failure details (populated when central_state is FAILED)
+    failure_reason: FailureReason | None = None
+    """
+    Categorized reason for the failure.
+
+    Only set when central_state is FAILED. Enables integrations to distinguish
+    between different error types (AUTH, NETWORK, INTERNAL, etc.) and show
+    appropriate user-facing messages.
+    """
+
+    failure_interface_id: str | None = None
+    """Interface ID that caused the failure, if applicable."""
+
+    # Degraded details (populated when central_state is DEGRADED)
+    degraded_interfaces: Mapping[str, FailureReason] | None = None
+    """
+    Interfaces that are degraded with their failure reasons.
+
+    Only set when central_state is DEGRADED. Maps interface_id to its
+    FailureReason, enabling integrations to show detailed status per interface.
+    Example: {"ccu-HmIP-RF": FailureReason.NETWORK, "ccu-BidCos-RF": FailureReason.AUTH}
+    """
+
+    # Infrastructure
+    connection_state: tuple[str, bool] | None = None
+    """Connection state change: (interface_id, connected)."""
+
+    client_state: tuple[str, ClientState, ClientState] | None = None
+    """Client state change: (interface_id, old_state, new_state)."""
+
+    callback_state: tuple[str, bool] | None = None
+    """Callback server state change: (interface_id, alive)."""
+
+    # Issues
+    issues: tuple[IntegrationIssue, ...] = ()
+    """Issues that should be presented to user (errors, warnings)."""
+
+    @property
+    def key(self) -> Any:
+        """Key identifier for this event."""
+        return None
+
+
+class DeviceLifecycleEventType(StrEnum):
+    """Type of device lifecycle event."""
+
+    CREATED = "created"
+    DELAYED = "delayed"
+    UPDATED = "updated"
+    REMOVED = "removed"
+    AVAILABILITY_CHANGED = "availability_changed"
+
+
+@dataclass(frozen=True, slots=True)
+class DeviceLifecycleEvent(Event):
+    """
+    Device lifecycle and availability event.
+
+    Aggregates: SystemEventTypeData (DEVICES_CREATED, DEVICES_DELAYED, DEVICE_REMOVED),
+    DeviceAvailabilityChangedEvent.
+
+    **HA Registration Points**:
+    - `control_unit.py`: Device registry updates, virtual remotes, repair issues
+    - `generic_entity.py`: Data point availability updates (optional)
+
+    Example:
+        ```python
+        async def on_device_lifecycle(*, event: DeviceLifecycleEvent) -> None:
+            if event.event_type == DeviceLifecycleEventType.CREATED:
+                # Add to device registry
+                for device_address in event.device_addresses:
+                    device_registry.async_get_or_create(...)
+
+            elif event.event_type == DeviceLifecycleEventType.DELAYED:
+                # Create repair issue for delayed device
+                for address in event.device_addresses:
+                    async_create_issue(
+                        issue_id=f"devices_delayed|{event.interface_id}|{address}",
+                        ...
+                    )
+
+            elif event.event_type == DeviceLifecycleEventType.AVAILABILITY_CHANGED:
+                # Update data point availability
+                for address, available in event.availability_changes:
+                    ...
+
+        central.event_bus.subscribe(
+            event_type=DeviceLifecycleEvent,
+            event_key=None,
+            handler=on_device_lifecycle,
+        )
+        ```
+
+    """
+
+    event_type: DeviceLifecycleEventType
+    """Type of device lifecycle event."""
+
+    # For CREATED/UPDATED/REMOVED/DELAYED
+    device_addresses: tuple[str, ...] = ()
+    """Affected device addresses."""
+
+    # For AVAILABILITY_CHANGED
+    availability_changes: tuple[tuple[str, bool], ...] = ()
+    """Availability changes: tuple of (device_address, is_available)."""
+
+    # For CREATED - includes virtual remotes flag
+    includes_virtual_remotes: bool = False
+    """Whether virtual remotes are included in this creation event."""
+
+    # For DELAYED - interface where devices were delayed
+    interface_id: str | None = None
+    """Interface ID for delayed device creation (used for repair issues)."""
+
+    @property
+    def key(self) -> Any:
+        """Key identifier for this event."""
+        return None
+
+
+@dataclass(frozen=True, slots=True)
+class DataPointsCreatedEvent(Event):
+    """
+    New data points created event.
+
+    Emitted when new data points are created (device addition, config reload).
+    Data points are grouped by category for platform-specific handling.
+
+    **HA Registration Point**: `control_unit.py`
+    (Dispatches to platform async_add_entities functions)
+
+    Example:
+        ```python
+        async def on_data_points_created(*, event: DataPointsCreatedEvent) -> None:
+            for category, data_points in event.new_data_points:
+                async_dispatcher_send(
+                    hass,
+                    signal_new_data_point(entry_id=entry_id, platform=category),
+                    data_points,
+                )
+
+        central.event_bus.subscribe(
+            event_type=DataPointsCreatedEvent,
+            event_key=None,
+            handler=on_data_points_created,
+        )
+        ```
+
+    """
+
+    new_data_points: Mapping[DataPointCategory, tuple[CallbackDataPointProtocol, ...]]
+    """
+    New data points grouped by category.
+
+    Tuple of (category, data_points) pairs.
+    Only includes data points that should be exposed to integrations.
+    """
+
+    @property
+    def key(self) -> Any:
+        """Key identifier for this event."""
+        return None
+
+
+@dataclass(frozen=True, slots=True)
+class DeviceTriggerEvent(Event):
+    """
+    Device trigger event (button press, sensor trigger, etc.).
+
+    Forwarded to Home Assistant's event bus for automations.
+
+    **HA Registration Point**: `control_unit.py`
+    (Fires HA event on homematicip_local.event)
+
+    Example:
+        ```python
+        async def on_device_trigger(*, event: DeviceTriggerEvent) -> None:
+            hass.bus.async_fire(
+                event_type=f"{DOMAIN}.event",
+                event_data={
+                    "trigger_type": event.trigger_type,
+                    "model": event.model,
+                    "interface_id": event.interface_id,
+                    "device_address": event.device_address,
+                    "channel_no": event.channel_no,
+                    "parameter": event.parameter,
+                    "value": event.value,
+                },
+            )
+
+        central.event_bus.subscribe(
+            event_type=DeviceTriggerEvent,
+            event_key=None,
+            handler=on_device_trigger,
+        )
+        ```
+
+    """
+
+    trigger_type: DeviceTriggerEventType
+    """Type of device trigger event."""
+
+    model: str
+    """Model of the device."""
+
+    interface_id: str
+    """Interface ID where event occurred."""
+
+    device_address: str
+    """Device address of the device."""
+
+    channel_no: int | None
+    """Channel number of the device."""
+
+    parameter: str
+    """Parameter name (e.g., PRESS_SHORT, MOTION)."""
+
+    value: str | int | float | bool
+    """Event value."""
+
+    @property
+    def key(self) -> Any:
+        """Key identifier for this event."""
+        return None

aiohomematic/central/events/types.py

@@ -0,0 +1,194 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Event type definitions for the aiohomematic event system.
+
+This module contains event dataclasses that are used across the codebase.
+These events are defined separately from the EventBus to avoid circular
+import dependencies.
+
+All event types in this module:
+- Are immutable dataclasses (frozen=True, slots=True)
+- Inherit from the Event base class
+- Have a `key` property for event routing
+
+These events are re-exported from `central.events` for backward compatibility.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import datetime
+from enum import IntEnum
+from typing import Any
+
+from aiohomematic.const import CentralState, CircuitState, ClientState
+
+__all__ = [
+    "CentralStateChangedEvent",
+    "CircuitBreakerStateChangedEvent",
+    "CircuitBreakerTrippedEvent",
+    "ClientStateChangedEvent",
+    "Event",
+    "EventPriority",
+    "HealthRecordedEvent",
+]
+
+
+class EventPriority(IntEnum):
+    """
+    Priority levels for event handlers.
+
+    Higher priority handlers are called before lower priority handlers.
+    Handlers with the same priority are called in subscription order.
+
+    Use priorities sparingly - most handlers should use NORMAL priority.
+    Reserve CRITICAL for handlers that must run before all others (e.g., logging, metrics).
+    Reserve LOW for handlers that should run after all others (e.g., cleanup, notifications).
+    """
+
+    LOW = 0
+    """Lowest priority - runs after all other handlers."""
+
+    NORMAL = 50
+    """Default priority for most handlers."""
+
+    HIGH = 100
+    """Higher priority - runs before NORMAL handlers."""
+
+    CRITICAL = 200
+    """Highest priority - runs before all other handlers (e.g., logging, metrics)."""
+
+
+@dataclass(frozen=True, slots=True)
+class Event(ABC):
+    """
+    Base class for all events in the EventBus.
+
+    All events are immutable dataclasses with slots for memory efficiency.
+    The timestamp field is included in all events for debugging and auditing.
+    A key must be provided to uniquely identify the event.
+    """
+
+    timestamp: datetime
+
+    @property
+    @abstractmethod
+    def key(self) -> Any:
+        """Key identifier for this event."""
+
+
+@dataclass(frozen=True, slots=True)
+class CircuitBreakerStateChangedEvent(Event):
+    """
+    Circuit breaker state transition.
+
+    Key is interface_id.
+
+    Emitted when a circuit breaker transitions between states
+    (CLOSED, OPEN, HALF_OPEN).
+    """
+
+    timestamp: datetime
+    interface_id: str
+    old_state: CircuitState
+    new_state: CircuitState
+    failure_count: int
+    success_count: int
+    last_failure_time: datetime | None
+
+    @property
+    def key(self) -> Any:
+        """Key identifier for this event."""
+        return self.interface_id
+
+
+@dataclass(frozen=True, slots=True)
+class CircuitBreakerTrippedEvent(Event):
+    """
+    Circuit breaker tripped (opened due to failures).
+
+    Key is interface_id.
+
+    Emitted when a circuit breaker transitions to OPEN state,
+    indicating repeated failures.
+    """
+
+    timestamp: datetime
+    interface_id: str
+    failure_count: int
+    last_failure_reason: str | None
+    cooldown_seconds: float
+
+    @property
+    def key(self) -> Any:
+        """Key identifier for this event."""
+        return self.interface_id
+
+
+@dataclass(frozen=True, slots=True)
+class ClientStateChangedEvent(Event):
+    """
+    Client state machine transition.
+
+    Key is interface_id.
+
+    Emitted when a client transitions between states
+    (INIT, CONNECTED, DISCONNECTED, etc.).
+    """
+
+    timestamp: datetime
+    interface_id: str
+    old_state: ClientState
+    new_state: ClientState
+    trigger: str | None
+
+    @property
+    def key(self) -> Any:
+        """Key identifier for this event."""
+        return self.interface_id
+
+
+@dataclass(frozen=True, slots=True)
+class CentralStateChangedEvent(Event):
+    """
+    Central unit state machine transition.
+
+    Key is central_name.
+
+    Emitted when the central unit transitions between states
+    (STARTING, RUNNING, DEGRADED, etc.).
+    """
+
+    timestamp: datetime
+    central_name: str
+    old_state: CentralState
+    new_state: CentralState
+    trigger: str | None
+
+    @property
+    def key(self) -> Any:
+        """Key identifier for this event."""
+        return self.central_name
+
+
+@dataclass(frozen=True, slots=True)
+class HealthRecordedEvent(Event):
+    """
+    Health status recorded for an interface.
+
+    Key is interface_id.
+
+    Emitted by CircuitBreaker when a request succeeds or fails,
+    enabling health tracking without direct callback coupling.
+    """
+
+    timestamp: datetime
+    interface_id: str
+    success: bool
+
+    @property
+    def key(self) -> Any:
+        """Key identifier for this event."""
+        return self.interface_id