Coverage for src / lexigram / contracts / data / timeseries / protocols.py: 0%

1"""Time-series database protocols for event and metric storage. 

2 

3Provides driver-agnostic abstractions for time-series stores 

4(TimescaleDB, InfluxDB, etc.) supporting continuous event insertion 

5and windowed querying. 

6""" 

7 

8from __future__ import annotations 

9 

10from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable 

11 

12if TYPE_CHECKING: 

13 from lexigram.contracts.core.health import HealthCheckResult 

14 

15 

16@runtime_checkable 

17class TimeSeriesStoreProtocol(Protocol): 

18 """Protocol for a time-series database provider. 

19 

20 Provides continuous data stream ingestion, windowed queries, and 

21 lifecycle management. 

22 """ 

23 

24 async def connect(self) -> None: 

25 """Establish connection to the time-series store.""" 

26 ... 

27 

28 async def disconnect(self) -> None: 

29 """Close all connections.""" 

30 ... 

31 

32 def is_connected(self) -> bool: 

33 """Check if the store is connected.""" 

34 ... 

35 

36 async def insert(self, series: str, data: list[dict[str, Any]]) -> None: 

37 """Insert sequence data points into a specific series/measurement. 

38 

39 Args: 

40 series: The series, measurement, or bucket name. 

41 data: Data points, typically including a timestamp and values. 

42 """ 

43 ... 

44 

45 async def query( 

46 self, 

47 series: str, 

48 start_time: Any, 

49 end_time: Any, 

50 filter: dict[str, Any] | None = None, 

51 ) -> list[dict[str, Any]]: 

52 """Query data points within a time window. 

53 

54 Args: 

55 series: The series name to query. 

56 start_time: Timestamp representing the beginning of the window. 

57 end_time: Timestamp representing the end of the window. 

58 filter: Optional tags/metadata to filter on. 

59 

60 Returns: 

61 List of matched data point dicts. 

62 """ 

63 ... 

64 

65 async def health_check(self, timeout: float = 5.0) -> HealthCheckResult: 

66 """Check time-series store connectivity and health.""" 

67 ... 

68 

69 

70__all__ = [ 

71 "TimeSeriesStoreProtocol", 

72]