aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/interfaces/operations.py

@@ -0,0 +1,217 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Operation protocol interfaces.
+
+This module defines protocol interfaces for operational tasks like
+scheduling, caching, and parameter visibility management.
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+import asyncio
+from collections.abc import Callable, Mapping
+from concurrent.futures import ThreadPoolExecutor
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+from aiohomematic.const import DeviceDescription, Interface, ParameterData, ParamsetKey
+from aiohomematic.type_aliases import AsyncTaskFactoryAny, CoroutineAny
+
+if TYPE_CHECKING:
+    from aiohomematic.interfaces import ChannelProtocol
+    from aiohomematic.store import CacheName, CacheStatistics
+    from aiohomematic.store.types import IncidentSeverity, IncidentSnapshot, IncidentType, PingPongJournal
+
+
+@runtime_checkable
+class TaskSchedulerProtocol(Protocol):
+    """
+    Protocol for scheduling async tasks.
+
+    Implemented by Looper.
+    """
+
+    @abstractmethod
+    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."""
+
+    @abstractmethod
+    async def block_till_done(self, *, wait_time: float | None = None) -> None:
+        """Block until all pending work is done."""
+
+    @abstractmethod
+    def cancel_tasks(self) -> None:
+        """Cancel running tasks."""
+
+    @abstractmethod
+    def create_task(self, *, target: CoroutineAny | AsyncTaskFactoryAny, name: str) -> None:
+        """Create and schedule an async task."""
+
+
+@runtime_checkable
+class ParameterVisibilityProviderProtocol(Protocol):
+    """
+    Protocol for accessing parameter visibility information.
+
+    Implemented by ParameterVisibilityRegistry.
+    """
+
+    @abstractmethod
+    def is_relevant_paramset(self, *, channel: ChannelProtocol, paramset_key: ParamsetKey) -> bool:
+        """
+        Return if a paramset is relevant.
+
+        Required to load MASTER paramsets, which are not initialized by default.
+        """
+
+    @abstractmethod
+    def model_is_ignored(self, *, model: str) -> bool:
+        """Check if a model should be ignored for custom data points."""
+
+    @abstractmethod
+    def parameter_is_hidden(self, *, channel: ChannelProtocol, paramset_key: ParamsetKey, parameter: str) -> bool:
+        """Check if a parameter is hidden."""
+
+    @abstractmethod
+    def parameter_is_un_ignored(
+        self, *, channel: ChannelProtocol, paramset_key: ParamsetKey, parameter: str, custom_only: bool = False
+    ) -> bool:
+        """Check if a parameter is un-ignored (visible)."""
+
+    @abstractmethod
+    def should_skip_parameter(
+        self, *, channel: ChannelProtocol, paramset_key: ParamsetKey, parameter: str, parameter_is_un_ignored: bool
+    ) -> bool:
+        """Determine if a parameter should be skipped."""
+
+
+@runtime_checkable
+class DeviceDetailsProviderProtocol(Protocol):
+    """
+    Protocol for accessing device details.
+
+    Implemented by DeviceDescriptionRegistry.
+    """
+
+    @abstractmethod
+    def get_address_id(self, *, address: str) -> int:
+        """Get an ID for an address."""
+
+    @abstractmethod
+    def get_channel_rooms(self, *, channel_address: str) -> set[str]:
+        """Get rooms for a channel."""
+
+    @abstractmethod
+    def get_device_rooms(self, *, device_address: str) -> set[str]:
+        """Get rooms for a device."""
+
+    @abstractmethod
+    def get_function_text(self, *, address: str) -> str | None:
+        """Get function text for an address."""
+
+    @abstractmethod
+    def get_interface(self, *, address: str) -> Interface:
+        """Get interface for an address."""
+
+    @abstractmethod
+    def get_name(self, *, address: str) -> str | None:
+        """Get name for an address."""
+
+
+@runtime_checkable
+class DeviceDescriptionProviderProtocol(Protocol):
+    """
+    Protocol for accessing device descriptions.
+
+    Implemented by DeviceDescriptionRegistry.
+    """
+
+    @abstractmethod
+    def get_device_description(self, *, interface_id: str, address: str) -> DeviceDescription:
+        """Get device description."""
+
+    @abstractmethod
+    def get_device_with_channels(self, *, interface_id: str, device_address: str) -> Mapping[str, DeviceDescription]:
+        """Get device with all channel descriptions."""
+
+
+@runtime_checkable
+class ParamsetDescriptionProviderProtocol(Protocol):
+    """
+    Protocol for accessing paramset descriptions.
+
+    Implemented by ParamsetDescriptionRegistry.
+    """
+
+    @abstractmethod
+    def get_channel_paramset_descriptions(
+        self, *, interface_id: str, channel_address: str
+    ) -> Mapping[ParamsetKey, Mapping[str, ParameterData]]:
+        """Get all paramset descriptions for a channel."""
+
+    @abstractmethod
+    def get_parameter_data(
+        self, *, interface_id: str, channel_address: str, paramset_key: ParamsetKey, parameter: str
+    ) -> ParameterData | None:
+        """Get parameter data from paramset description."""
+
+    @abstractmethod
+    def has_parameter(
+        self, *, interface_id: str, channel_address: str, paramset_key: ParamsetKey, parameter: str
+    ) -> bool:
+        """Check if a parameter exists in the paramset description."""
+
+    @abstractmethod
+    def is_in_multiple_channels(self, *, channel_address: str, parameter: str) -> bool:
+        """Check if parameter is in multiple channels per device."""
+
+
+@runtime_checkable
+class CacheWithStatisticsProtocol(Protocol):
+    """
+    Protocol for caches that provide statistics.
+
+    Caches implementing this protocol provide local counters for hits, misses,
+    and evictions that can be read directly by MetricsAggregator without
+    requiring EventBus events.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> CacheName:
+        """Return the cache name for identification."""
+
+    @property
+    @abstractmethod
+    def size(self) -> int:
+        """Return current number of entries in the cache."""
+
+    @property
+    @abstractmethod
+    def statistics(self) -> CacheStatistics:
+        """Return the cache statistics container."""
+
+
+@runtime_checkable
+class IncidentRecorderProtocol(Protocol):
+    """
+    Protocol for recording diagnostic incidents.
+
+    Implemented by IncidentStore.
+    """
+
+    @abstractmethod
+    async def record_incident(
+        self,
+        *,
+        incident_type: IncidentType,
+        severity: IncidentSeverity,
+        message: str,
+        interface_id: str | None = None,
+        context: dict[str, Any] | None = None,
+        journal: PingPongJournal | None = None,
+    ) -> IncidentSnapshot:
+        """Record a new incident and persist it."""

aiohomematic/logging_context.py

@@ -0,0 +1,134 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Logging integration with request context.
+
+This module provides logging utilities that automatically include request context
+information in log messages, enabling correlation of logs across async call chains.
+
+Key features:
+- ContextualLoggerAdapter: Logger adapter that prefixes messages with request ID
+- RequestContextFilter: Logging filter that adds context fields to log records
+- get_contextual_logger: Factory function for contextual loggers
+
+Example:
+    _LOGGER = get_contextual_logger(name=__name__)
+    _LOGGER.info("Processing device")  # → "[abc12345:set_value] Processing device"
+
+Public API of this module is defined by __all__.
+
+"""
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+import logging
+from typing import Any
+
+from aiohomematic.context import get_request_context
+
+
+class ContextualLoggerAdapter(logging.LoggerAdapter[logging.Logger]):
+    """
+    Logger adapter that includes request context in log messages.
+
+    Automatically prefixes log messages with request_id and operation
+    from the current RequestContext.
+
+    Example:
+        _LOGGER = ContextualLoggerAdapter(logging.getLogger(__name__), {})
+        # With request context set:
+        _LOGGER.info("Processing")  # → "[abc12345:set_value] Processing"
+        # Without request context:
+        _LOGGER.info("Processing")  # → "Processing"
+
+    """
+
+    def process(  # kwonly: disable
+        self,
+        msg: str,
+        kwargs: MutableMapping[str, Any],
+    ) -> tuple[str, MutableMapping[str, Any]]:
+        """
+        Process log message to include request context.
+
+        Args:
+            msg: The log message.
+            kwargs: Additional logging keyword arguments.
+
+        Returns:
+            Tuple of (processed message, kwargs).
+
+        """
+        if ctx := get_request_context():
+            prefix = f"[{ctx.request_id}]"
+            if ctx.operation:
+                prefix = f"[{ctx.request_id}:{ctx.operation}]"
+            msg = f"{prefix} {msg}"
+
+        return msg, kwargs
+
+
+class RequestContextFilter(logging.Filter):
+    """
+    Logging filter that adds context fields to log records.
+
+    Use with JSON formatters or structured logging to include request context
+    as separate fields in log records.
+
+    Example:
+        handler = logging.StreamHandler()
+        handler.addFilter(RequestContextFilter())
+        # Log records will have: request_id, operation, device_address, elapsed_ms
+
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:  # kwonly: disable
+        """
+        Add request context fields to log record.
+
+        Args:
+            record: The log record to augment.
+
+        Returns:
+            Always True (never filters out records).
+
+        """
+        ctx = get_request_context()
+
+        record.request_id = ctx.request_id if ctx else "none"
+        record.operation = ctx.operation if ctx else "none"
+        record.device_address = ctx.device_address if ctx else "none"
+        record.elapsed_ms = ctx.elapsed_ms if ctx else 0.0
+
+        return True
+
+
+def get_contextual_logger(*, name: str) -> ContextualLoggerAdapter:
+    """
+    Get a logger that includes request context in messages.
+
+    Factory function that creates a ContextualLoggerAdapter wrapping a
+    standard logger. Use this instead of logging.getLogger() to get
+    automatic request context prefixing.
+
+    Args:
+        name: Logger name (typically __name__).
+
+    Returns:
+        ContextualLoggerAdapter that prefixes messages with request context.
+
+    Example:
+        _LOGGER = get_contextual_logger(name=__name__)
+        _LOGGER.info("Processing device")  # → "[abc12345:set_value] Processing device"
+
+    """
+    return ContextualLoggerAdapter(logging.getLogger(name), {})
+
+
+# Define public API for this module
+__all__ = [
+    "ContextualLoggerAdapter",
+    "RequestContextFilter",
+    "get_contextual_logger",
+]

aiohomematic/metrics/__init__.py

@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Metrics collection, aggregation, and observability.
+
+This module provides both event-driven and polling-based metrics collection.
+
+Event-Driven Metrics (MetricsObserver)
+--------------------------------------
+Components emit metric events to the EventBus, and MetricsObserver aggregates them.
+Use emit_* functions to emit metrics and MetricsObserver to query them.
+
+Polling-Based Metrics (MetricsAggregator)
+-----------------------------------------
+MetricsAggregator queries system components directly to collect metrics.
+Use for comprehensive system snapshots.
+
+Public API
+----------
+Event-driven:
+- MetricEvent, LatencyMetricEvent, CounterMetricEvent, GaugeMetricEvent, HealthMetricEvent
+- MetricsObserver, ObserverSnapshot, LatencyTracker, HealthState
+- emit_latency, emit_counter, emit_gauge, emit_health
+- MetricEmitterMixin, LatencyContext
+
+Polling-based:
+- MetricsAggregator, MetricsSnapshot
+- RpcMetrics, RpcServerMetrics, EventMetrics, CacheMetrics, HealthMetrics
+- RecoveryMetrics, ModelMetrics, ServiceMetrics
+
+Note: Protocol dependencies for MetricsAggregator are in aiohomematic.interfaces:
+- ClientProviderForMetricsProtocol
+- DeviceProviderForMetricsProtocol
+- HubDataPointManagerForMetricsProtocol
+
+"""
+
+from __future__ import annotations
+
+from aiohomematic.metrics.aggregator import MetricsAggregator
+from aiohomematic.metrics.dataclasses import (
+    CacheMetrics,
+    EventMetrics,
+    HealthMetrics,
+    MetricsSnapshot,
+    ModelMetrics,
+    RecoveryMetrics,
+    RpcMetrics,
+    RpcServerMetrics,
+    ServiceMetrics,
+)
+from aiohomematic.metrics.emitter import (
+    EventBusProviderProtocol,
+    LatencyContext,
+    MetricEmitterMixin,
+    emit_counter,
+    emit_gauge,
+    emit_health,
+    emit_latency,
+)
+from aiohomematic.metrics.events import (
+    METRIC_EVENT_TYPES,
+    AnyMetricEvent,
+    CounterMetricEvent,
+    GaugeMetricEvent,
+    HealthMetricEvent,
+    LatencyMetricEvent,
+    MetricEvent,
+    MetricType,
+)
+from aiohomematic.metrics.keys import MetricKey, MetricKeys
+from aiohomematic.metrics.observer import (
+    MAX_METRIC_KEYS,
+    HealthState,
+    LatencyTracker,
+    MetricsObserver,
+    ObserverSnapshot,
+)
+from aiohomematic.metrics.stats import CacheStats, LatencyStats, ServiceStats, SizeOnlyStats
+
+__all__ = [
+    # Aggregator
+    "MetricsAggregator",
+    # Dataclasses
+    "CacheMetrics",
+    "EventMetrics",
+    "HealthMetrics",
+    "MetricsSnapshot",
+    "ModelMetrics",
+    "RecoveryMetrics",
+    "RpcMetrics",
+    "RpcServerMetrics",
+    "ServiceMetrics",
+    # Emitter
+    "EventBusProviderProtocol",
+    "LatencyContext",
+    "MetricEmitterMixin",
+    "emit_counter",
+    "emit_gauge",
+    "emit_health",
+    "emit_latency",
+    # Events
+    "AnyMetricEvent",
+    "CounterMetricEvent",
+    "GaugeMetricEvent",
+    "HealthMetricEvent",
+    "LatencyMetricEvent",
+    "METRIC_EVENT_TYPES",
+    "MetricEvent",
+    "MetricType",
+    # Keys
+    "MetricKey",
+    "MetricKeys",
+    # Observer
+    "HealthState",
+    "LatencyTracker",
+    "MAX_METRIC_KEYS",
+    "MetricsObserver",
+    "ObserverSnapshot",
+    # Stats
+    "CacheStats",
+    "LatencyStats",
+    "ServiceStats",
+    "SizeOnlyStats",
+]

aiohomematic/metrics/_protocols.py

@@ -0,0 +1,140 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Minimal protocol interfaces for metrics aggregation.
+
+This private module defines minimal protocol interfaces used by MetricsAggregator.
+Located in metrics/ (not interfaces/) to avoid circular imports during initialization.
+
+Import path: aiohomematic.interfaces (public) or aiohomematic.metrics._protocols (internal)
+
+These protocols are:
+- Re-exported via interfaces/__init__.py for public use
+- Extended by full protocols (DeviceProviderProtocol, ClientProviderProtocol,
+  HubDataPointManagerProtocol) in interfaces/central.py and interfaces/client.py
+
+IMPORTANT: This module must NOT import from interfaces/ to avoid circular imports.
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from aiohomematic.store.types import CacheStatistics
+
+
+@runtime_checkable
+class DeviceProviderForMetricsProtocol(Protocol):
+    """
+    Minimal protocol for device access in metrics context.
+
+    Provides only the `devices` property needed by MetricsAggregator
+    to collect model statistics without requiring the full DeviceProviderProtocol.
+
+    Implemented by CentralUnit.
+    """
+
+    @property
+    @abstractmethod
+    def devices(self) -> tuple[Any, ...]:
+        """Return all registered devices."""
+
+
+@runtime_checkable
+class ClientProviderForMetricsProtocol(Protocol):
+    """
+    Minimal protocol for client access in metrics context.
+
+    Provides only the `clients` property needed by MetricsAggregator
+    to collect RPC metrics without requiring the full ClientProviderProtocol.
+
+    Implemented by CentralUnit.
+    """
+
+    @property
+    @abstractmethod
+    def clients(self) -> tuple[Any, ...]:
+        """Return all connected clients."""
+
+
+@runtime_checkable
+class HubDataPointManagerForMetricsProtocol(Protocol):
+    """
+    Minimal protocol for hub data point access in metrics context.
+
+    Provides only the properties needed by MetricsAggregator to collect
+    program/sysvar counts without requiring the full HubDataPointManagerProtocol.
+
+    Implemented by HubCoordinator.
+    """
+
+    @property
+    @abstractmethod
+    def program_data_points(self) -> tuple[Any, ...]:
+        """Return all program data points."""
+
+    @property
+    @abstractmethod
+    def sysvar_data_points(self) -> tuple[Any, ...]:
+        """Return all system variable data points."""
+
+
+@runtime_checkable
+class CacheProviderForMetricsProtocol(Protocol):
+    """
+    Minimal protocol for cache access in metrics context.
+
+    Provides cache sizes and statistics needed by MetricsAggregator to collect
+    cache metrics without requiring the full CacheCoordinator.
+
+    Implemented by CacheCoordinator.
+    """
+
+    @property
+    @abstractmethod
+    def data_cache_size(self) -> int:
+        """Return data cache size."""
+
+    @property
+    @abstractmethod
+    def data_cache_statistics(self) -> CacheStatistics:
+        """Return data cache statistics."""
+
+    @property
+    @abstractmethod
+    def device_descriptions_size(self) -> int:
+        """Return device descriptions cache size."""
+
+    @property
+    @abstractmethod
+    def paramset_descriptions_size(self) -> int:
+        """Return paramset descriptions cache size."""
+
+    @property
+    @abstractmethod
+    def visibility_cache_size(self) -> int:
+        """Return visibility cache size."""
+
+
+@runtime_checkable
+class RecoveryProviderForMetricsProtocol(Protocol):
+    """
+    Minimal protocol for recovery status access in metrics context.
+
+    Provides recovery statistics needed by MetricsAggregator to collect
+    recovery metrics without requiring the full ConnectionRecoveryCoordinator.
+
+    Implemented by ConnectionRecoveryCoordinator.
+    """
+
+    @property
+    @abstractmethod
+    def in_recovery(self) -> bool:
+        """Return True if any recovery is in progress."""
+
+    @property
+    @abstractmethod
+    def recovery_states(self) -> dict[str, Any]:
+        """Return recovery states for all tracked interfaces."""