Coverage for arrakis/api.py: 93.3%
15 statements
« prev ^ index » next coverage.py v7.6.12, created at 2025-08-13 15:09 -0700
1# Copyright (c) 2022, California Institute of Technology and contributors
2#
3# You should have received a copy of the licensing terms for this
4# software included in the file "LICENSE" located in the top-level
5# directory of this package. If you did not, you can view a copy at
6# https://git.ligo.org/ngdd/arrakis-python/-/raw/main/LICENSE
8"""Clientless API access."""
10from collections.abc import Generator
12from . import constants
13from .block import SeriesBlock
14from .channel import Channel
15from .client import Client, DataTypeLike
18def find(
19 pattern: str = constants.DEFAULT_MATCH,
20 data_type: DataTypeLike | None = None,
21 min_rate: int | None = constants.MIN_SAMPLE_RATE,
22 max_rate: int | None = constants.MAX_SAMPLE_RATE,
23 publisher: str | list[str] | None = None,
24) -> Generator[Channel, None, None]:
25 """Find channels matching a set of conditions
27 Parameters
28 ----------
29 pattern : str, optional
30 Channel pattern to match channels with, using regular expressions.
31 data_type : numpy.dtype-like | list[numpy.dtype-like], optional
32 If set, find all channels with these data types.
33 min_rate : int, optional
34 Minimum sample rate for channels.
35 max_rate : int, optional
36 Maximum sample rate for channels.
37 publisher : str | list[str], optional
38 If set, find all channels associated with these publishers.
40 Yields
41 -------
42 Channel
43 Channel objects for all channels matching query.
45 """
46 yield from Client().find(pattern, data_type, min_rate, max_rate, publisher)
49def count(
50 pattern: str = constants.DEFAULT_MATCH,
51 data_type: DataTypeLike | None = None,
52 min_rate: int | None = constants.MIN_SAMPLE_RATE,
53 max_rate: int | None = constants.MAX_SAMPLE_RATE,
54 publisher: str | list[str] | None = None,
55) -> int:
56 """Count channels matching a set of conditions
58 Parameters
59 ----------
60 pattern : str, optional
61 Channel pattern to match channels with, using regular expressions.
62 data_type : numpy.dtype-like | list[numpy.dtype-like], optional
63 If set, find all channels with these data types.
64 min_rate : int, optional
65 Minimum sample rate for channels.
66 max_rate : int, optional
67 Maximum sample rate for channels.
68 publisher : str | list[str], optional
69 If set, find all channels associated with these publishers.
71 Returns
72 -------
73 int
74 The number of channels matching query.
76 """
77 return Client().count(pattern, data_type, min_rate, max_rate, publisher)
80def describe(channels: list[str]) -> dict[str, Channel]:
81 """Get channel metadata for channels requested
83 Parameters
84 ----------
85 channels : list[str]
86 List of channels to request.
88 Returns
89 -------
90 dict[str, Channel]
91 Mapping of channel names to channel metadata.
93 """
94 return Client().describe(channels)
97def stream(
98 channels: list[str],
99 start: float | None = None,
100 end: float | None = None,
101) -> Generator[SeriesBlock, None, None]:
102 """Stream live or offline timeseries data
104 Parameters
105 ----------
106 channels : list[str]
107 List of channels to request.
108 start : float, optional
109 GPS start time, in seconds.
110 end : float, optional
111 GPS end time, in seconds.
113 Yields
114 ------
115 SeriesBlock
116 Dictionary-like object containing all requested channel data.
118 Setting neither start nor end begins a live stream starting
119 from now.
121 """
122 yield from Client().stream(channels, start, end)
125def fetch(
126 channels: list[str],
127 start: float,
128 end: float,
129) -> SeriesBlock:
130 """Fetch timeseries data
132 Parameters
133 ----------
134 channels : list[str]
135 A list of channels to request.
136 start : float
137 GPS start time, in seconds.
138 end : float
139 GPS end time, in seconds.
141 Returns
142 -------
143 SeriesBlock
144 Series block with all channels requested.
146 """
147 return Client().fetch(channels, start, end)