Coverage for arrakis/api.py: 93.3%

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

7

8"""Clientless API access."""

9

10 from collections.abc import Generator

11

12 from . import constants

13 from .block import SeriesBlock

14 from .channel import Channel

15 from .client import Client, DataTypeLike

16

17

18 def 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

26

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.

39

40 Yields

41 -------

42 Channel

43 Channel objects for all channels matching query.

44

45 """

46 yield from Client().find(pattern, data_type, min_rate, max_rate, publisher)

47

48

49 def 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

57

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.

70

71 Returns

72 -------

73 int

74 The number of channels matching query.

75

76 """

77 return Client().count(pattern, data_type, min_rate, max_rate, publisher)

78

79

80 def describe(channels: list[str]) -> dict[str, Channel]:

81 """Get channel metadata for channels requested

82

83 Parameters

84 ----------

85 channels : list[str]

86 List of channels to request.

87

88 Returns

89 -------

90 dict[str, Channel]

91 Mapping of channel names to channel metadata.

92

93 """

94 return Client().describe(channels)

95

96

97 def 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

103

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.

112

113 Yields

114 ------

115 SeriesBlock

116 Dictionary-like object containing all requested channel data.

117

118 Setting neither start nor end begins a live stream starting

119 from now.

120

121 """

122 yield from Client().stream(channels, start, end)

123

124

125 def fetch(

126 channels: list[str],

127 start: float,

128 end: float,

129) -> SeriesBlock:

130 """Fetch timeseries data

131

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.

140

141 Returns

142 -------

143 SeriesBlock

144 Series block with all channels requested.

145

146 """

147 return Client().fetch(channels, start, end)