thzdaq-api 0.0.6b3__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- thzdaq_api/__init__.py +1 -0
- thzdaq_api/analysis.py +62 -0
- thzdaq_api/approvals.py +87 -0
- thzdaq_api/assistant/agents.md +202 -0
- thzdaq_api/assistant/assistant.md +23 -0
- thzdaq_api/assistant/hints.md +15 -0
- thzdaq_api/atomic.py +79 -0
- thzdaq_api/catalog.py +131 -0
- thzdaq_api/console.py +70 -0
- thzdaq_api/custom.py +326 -0
- thzdaq_api/daemon.py +183 -0
- thzdaq_api/data.py +55 -0
- thzdaq_api/declare.py +193 -0
- thzdaq_api/declaring.py +125 -0
- thzdaq_api/devices.py +307 -0
- thzdaq_api/errors.py +47 -0
- thzdaq_api/events.py +224 -0
- thzdaq_api/examples/hot_cold.py +67 -0
- thzdaq_api/examples/hot_cold_grid.py +74 -0
- thzdaq_api/examples/iv_analysis.py +34 -0
- thzdaq_api/examples/map.py +42 -0
- thzdaq_api/examples/monitor.py +35 -0
- thzdaq_api/examples/raw_instrument.py +37 -0
- thzdaq_api/examples/sweep.py +38 -0
- thzdaq_api/examples.py +79 -0
- thzdaq_api/guides.py +61 -0
- thzdaq_api/host.py +494 -0
- thzdaq_api/interpreters.py +422 -0
- thzdaq_api/kernel.py +137 -0
- thzdaq_api/lab.py +562 -0
- thzdaq_api/lanes.py +170 -0
- thzdaq_api/leases.py +29 -0
- thzdaq_api/lock.py +65 -0
- thzdaq_api/measurement_file.py +459 -0
- thzdaq_api/measurements.py +433 -0
- thzdaq_api/operation.py +52 -0
- thzdaq_api/origins.py +86 -0
- thzdaq_api/present.py +376 -0
- thzdaq_api/procedures.py +124 -0
- thzdaq_api/raw.py +272 -0
- thzdaq_api/remote.py +267 -0
- thzdaq_api/rights.py +81 -0
- thzdaq_api/script.py +382 -0
- thzdaq_api/scripts.py +133 -0
- thzdaq_api/sessions.py +176 -0
- thzdaq_api/station.py +192 -0
- thzdaq_api/terminal.py +66 -0
- thzdaq_api/tools.py +275 -0
- thzdaq_api/transport.py +93 -0
- thzdaq_api/ui.py +152 -0
- thzdaq_api/windows.py +192 -0
- thzdaq_api/wire.py +35 -0
- thzdaq_api/workspace.py +239 -0
- thzdaq_api-0.0.6b3.dist-info/METADATA +30 -0
- thzdaq_api-0.0.6b3.dist-info/RECORD +57 -0
- thzdaq_api-0.0.6b3.dist-info/WHEEL +4 -0
- thzdaq_api-0.0.6b3.dist-info/licenses/LICENSE +21 -0
thzdaq_api/raw.py
ADDED
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
"""An instrument a script declares (instrument(...) of thzdaq), its raw
|
|
2
|
+
commands named as values: reading(...) asks the instrument and makes a value
|
|
3
|
+
of its answer (a number in SI with its unit and the quantity it came from, as
|
|
4
|
+
a device's reading is), setting(...) besides writes one, checked first
|
|
5
|
+
against the limits the script gives.
|
|
6
|
+
|
|
7
|
+
gauge = instrument("gauge_1", driver="generic.scpi",
|
|
8
|
+
connection="tcp://169.254.0.50:5025",
|
|
9
|
+
pressure=reading("PR1?", unit="Pa", parse=r"P=([0-9.Ee+-]+)", scale=100),
|
|
10
|
+
setpoint=setting("VOLT?", "VOLT {:.6f}", unit="V", minimum=0, maximum=5),
|
|
11
|
+
)
|
|
12
|
+
gauge.pressure # P=1.2E+00 (mbar) -> 120.0 Pa
|
|
13
|
+
gauge.setpoint = 2.5 # VOLT 2.500000, a raw write
|
|
14
|
+
gauge.raw("*IDN?") # any command as typed
|
|
15
|
+
|
|
16
|
+
Only the script knows these names: the daemon, the instrument's dock and
|
|
17
|
+
agents see its raw commands. A raw write waits for a person, unless the
|
|
18
|
+
script was started with --allow raw:<instrument>; within a measurement (with
|
|
19
|
+
lab.measurement) the person's yes to the first one holds until it ends. The
|
|
20
|
+
limits guard against a wrong value (25 for 2.5), not the bench: the script
|
|
21
|
+
may change them.
|
|
22
|
+
|
|
23
|
+
parse says how an answer becomes a value: None a number ("2.500"); a regular
|
|
24
|
+
expression the number its first group matches (r"P=([0-9.Ee+-]+)"); a dict
|
|
25
|
+
of answers and the values they mean ({"ON": True, "OFF": False}), which a
|
|
26
|
+
setting writes back as the answer; a function of the answer, for anything
|
|
27
|
+
else. scale multiplies a number read (and divides one written): mbar -> Pa
|
|
28
|
+
is scale=100, so that unit is SI.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
import re
|
|
32
|
+
from typing import Any, Callable, Dict, Iterable, Mapping, Optional, Union
|
|
33
|
+
|
|
34
|
+
from thzdaq_api.data import Measured
|
|
35
|
+
from thzdaq_api.devices import shown
|
|
36
|
+
from thzdaq_api.errors import ErrorCode, LabError
|
|
37
|
+
from thzdaq_api.lab import Bench, Device, Readout
|
|
38
|
+
from thzdaq_api.procedures import entry
|
|
39
|
+
|
|
40
|
+
Parse = Union[None, str, Mapping[str, Any], Callable[[str], Any]]
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def _number(value: Any) -> bool:
|
|
44
|
+
return isinstance(value, (int, float)) and not isinstance(value, bool)
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
class Reading:
|
|
48
|
+
"""A value the instrument answers a raw query with."""
|
|
49
|
+
|
|
50
|
+
def __init__(
|
|
51
|
+
self,
|
|
52
|
+
query: Optional[str],
|
|
53
|
+
unit: str = "",
|
|
54
|
+
parse: Parse = None,
|
|
55
|
+
scale: float = 1.0,
|
|
56
|
+
title: str = "",
|
|
57
|
+
):
|
|
58
|
+
self.query = query
|
|
59
|
+
self.unit = unit
|
|
60
|
+
self.parse = parse
|
|
61
|
+
self.scale = scale
|
|
62
|
+
self.title = title
|
|
63
|
+
|
|
64
|
+
def value(self, answer: str, source: str) -> Any:
|
|
65
|
+
"""The answer as the script uses it: a number scaled, with its unit
|
|
66
|
+
and source (Measured); another value as parse makes it."""
|
|
67
|
+
found = self._parsed(answer.strip(), source)
|
|
68
|
+
if not _number(found):
|
|
69
|
+
return found
|
|
70
|
+
return Measured(found * self.scale, self.unit, self.title, source)
|
|
71
|
+
|
|
72
|
+
def _parsed(self, answer: str, source: str) -> Any:
|
|
73
|
+
parse = self.parse
|
|
74
|
+
try:
|
|
75
|
+
if callable(parse):
|
|
76
|
+
return parse(answer)
|
|
77
|
+
if isinstance(parse, Mapping):
|
|
78
|
+
return parse[_key(parse, answer)]
|
|
79
|
+
if isinstance(parse, str):
|
|
80
|
+
found = re.search(parse, answer)
|
|
81
|
+
if found is None:
|
|
82
|
+
raise ValueError(f"{parse!r} finds nothing")
|
|
83
|
+
return float(found.group(1) if found.re.groups else found.group(0))
|
|
84
|
+
return float(answer)
|
|
85
|
+
except (ValueError, KeyError, TypeError) as e:
|
|
86
|
+
raise LabError(
|
|
87
|
+
ErrorCode.INSTRUMENT,
|
|
88
|
+
f"{source}: the answer {answer!r} to {self.query!r} reads as no"
|
|
89
|
+
f" value ({e})",
|
|
90
|
+
"parse= of reading(...) says how to read it: a regular"
|
|
91
|
+
" expression, a dict of answers, a function",
|
|
92
|
+
) from None
|
|
93
|
+
|
|
94
|
+
def __repr__(self) -> str:
|
|
95
|
+
return f"reading({self.query!r}, unit={self.unit!r})"
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def _key(answers: Mapping[str, Any], answer: str) -> str:
|
|
99
|
+
"""The key of a dict parse the answer is: as written, else in any case."""
|
|
100
|
+
if answer in answers:
|
|
101
|
+
return answer
|
|
102
|
+
for key in answers:
|
|
103
|
+
if key.lower() == answer.lower():
|
|
104
|
+
return key
|
|
105
|
+
raise KeyError(f"not one of {', '.join(map(repr, answers))}")
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
class Setting(Reading):
|
|
109
|
+
"""A value written to the instrument by a raw command; read back with
|
|
110
|
+
its query, when it has one."""
|
|
111
|
+
|
|
112
|
+
def __init__(
|
|
113
|
+
self,
|
|
114
|
+
query: Optional[str],
|
|
115
|
+
write: str,
|
|
116
|
+
unit: str = "",
|
|
117
|
+
minimum: Optional[float] = None,
|
|
118
|
+
maximum: Optional[float] = None,
|
|
119
|
+
parse: Parse = None,
|
|
120
|
+
scale: float = 1.0,
|
|
121
|
+
title: str = "",
|
|
122
|
+
):
|
|
123
|
+
super().__init__(query, unit, parse, scale, title)
|
|
124
|
+
self.write = write
|
|
125
|
+
self.minimum = minimum
|
|
126
|
+
self.maximum = maximum
|
|
127
|
+
|
|
128
|
+
def command(self, value: Any, source: str) -> str:
|
|
129
|
+
"""The raw command that writes the value, once it is within the
|
|
130
|
+
limits: a number divided by scale, a value of a dict parse as its
|
|
131
|
+
answer."""
|
|
132
|
+
if isinstance(self.parse, Mapping):
|
|
133
|
+
answers = [key for key, meant in self.parse.items() if meant == value]
|
|
134
|
+
if not answers:
|
|
135
|
+
raise LabError(
|
|
136
|
+
ErrorCode.INVALID_ARGUMENTS,
|
|
137
|
+
f"{source}: {value!r} is none of"
|
|
138
|
+
f" {', '.join(map(repr, self.parse.values()))}",
|
|
139
|
+
)
|
|
140
|
+
return self.write.format(answers[0])
|
|
141
|
+
if not _number(value):
|
|
142
|
+
raise LabError(
|
|
143
|
+
ErrorCode.INVALID_ARGUMENTS,
|
|
144
|
+
f"{source}: {value!r} is no number",
|
|
145
|
+
f"give it in {self.unit or 'its unit'}, as a number",
|
|
146
|
+
)
|
|
147
|
+
low, high = self.minimum, self.maximum
|
|
148
|
+
if (low is not None and value < low) or (high is not None and value > high):
|
|
149
|
+
limits = f"{'' if low is None else f'{low:g}'}..{'' if high is None else f'{high:g}'}"
|
|
150
|
+
raise LabError(
|
|
151
|
+
ErrorCode.OUT_OF_LIMITS,
|
|
152
|
+
f"{source}: {float(value):g} {self.unit} is beyond {limits}"
|
|
153
|
+
f" {self.unit}".rstrip(),
|
|
154
|
+
"minimum= and maximum= of setting(...) bound it",
|
|
155
|
+
)
|
|
156
|
+
return self.write.format(float(value) / self.scale)
|
|
157
|
+
|
|
158
|
+
def __repr__(self) -> str:
|
|
159
|
+
return f"setting({self.query!r}, {self.write!r}, unit={self.unit!r})"
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
def reading(
|
|
163
|
+
query: str,
|
|
164
|
+
unit: str = "",
|
|
165
|
+
parse: Parse = None,
|
|
166
|
+
scale: float = 1.0,
|
|
167
|
+
title: str = "",
|
|
168
|
+
) -> Reading:
|
|
169
|
+
"""A value the instrument answers query with (a raw command, "PR1?"):
|
|
170
|
+
parsed by parse, multiplied by scale, in unit (SI)."""
|
|
171
|
+
return Reading(query, unit, parse, scale, title)
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def setting(
|
|
175
|
+
query: Optional[str],
|
|
176
|
+
write: str,
|
|
177
|
+
unit: str = "",
|
|
178
|
+
minimum: Optional[float] = None,
|
|
179
|
+
maximum: Optional[float] = None,
|
|
180
|
+
parse: Parse = None,
|
|
181
|
+
scale: float = 1.0,
|
|
182
|
+
title: str = "",
|
|
183
|
+
) -> Setting:
|
|
184
|
+
"""A value written by write ("VOLT {:.6f}": the value divided by scale
|
|
185
|
+
goes into its braces) and read back by query (None: written only).
|
|
186
|
+
minimum and maximum (in unit) bound what is written."""
|
|
187
|
+
return Setting(query, write, unit, minimum, maximum, parse, scale, title)
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
class RawInstrument(Device):
|
|
191
|
+
"""An instrument of the profile as a script declared it: its device (its
|
|
192
|
+
own quantities and actions, none for a generic driver), the values the
|
|
193
|
+
script named its raw commands by, and raw(command) for any other."""
|
|
194
|
+
|
|
195
|
+
def __init__(self, bench: Bench, ref: str, named: Mapping[str, Reading]):
|
|
196
|
+
super().__init__(bench, ref)
|
|
197
|
+
object.__setattr__(self, "named", dict(named))
|
|
198
|
+
|
|
199
|
+
def raw(self, command: str, answer: bool = False) -> Optional[str]:
|
|
200
|
+
"""A command as typed (lab.raw): the answer of a query (with ?), or
|
|
201
|
+
of a write with answer."""
|
|
202
|
+
return self.bench.raw(self.ref, command, answer)
|
|
203
|
+
|
|
204
|
+
def _get(self, name: str) -> Any:
|
|
205
|
+
found = self.named[name]
|
|
206
|
+
source = entry(self.ref, name)
|
|
207
|
+
if found.query is None:
|
|
208
|
+
raise LabError(
|
|
209
|
+
ErrorCode.NOT_ALLOWED,
|
|
210
|
+
f"{source} is only written",
|
|
211
|
+
"give setting(...) a query to read it back",
|
|
212
|
+
)
|
|
213
|
+
return found.value(self.bench.raw(self.ref, found.query, True), source)
|
|
214
|
+
|
|
215
|
+
def _set(self, name: str, value: Any) -> None:
|
|
216
|
+
found = self.named[name]
|
|
217
|
+
if not isinstance(found, Setting):
|
|
218
|
+
raise LabError(
|
|
219
|
+
ErrorCode.NOT_ALLOWED,
|
|
220
|
+
f"{entry(self.ref, name)} is only read",
|
|
221
|
+
"declare it with setting(...) to write it",
|
|
222
|
+
)
|
|
223
|
+
self.bench.raw(self.ref, found.command(value, entry(self.ref, name)))
|
|
224
|
+
|
|
225
|
+
def read(self, *keys: str, display: bool = False) -> Readout:
|
|
226
|
+
"""What it reads: its own quantities and the readings named, or the
|
|
227
|
+
keys of them."""
|
|
228
|
+
named = [key for key in keys if key in self.named] if keys else list(self.named)
|
|
229
|
+
own = [key for key in keys if key not in self.named]
|
|
230
|
+
found = (
|
|
231
|
+
Readout(super().read(*own, display=display))
|
|
232
|
+
if own or not keys
|
|
233
|
+
else Readout()
|
|
234
|
+
)
|
|
235
|
+
for key in named:
|
|
236
|
+
if self.named[key].query is not None:
|
|
237
|
+
value = self._get(key)
|
|
238
|
+
found[key] = shown(value, self.named[key].unit) if display else value
|
|
239
|
+
return found
|
|
240
|
+
|
|
241
|
+
def __getattr__(self, name: str) -> Any:
|
|
242
|
+
if name in self.named:
|
|
243
|
+
return self._get(name)
|
|
244
|
+
return super().__getattr__(name)
|
|
245
|
+
|
|
246
|
+
def __setattr__(self, name: str, value: Any) -> None:
|
|
247
|
+
if name in self.named:
|
|
248
|
+
self._set(name, value)
|
|
249
|
+
else:
|
|
250
|
+
super().__setattr__(name, value)
|
|
251
|
+
|
|
252
|
+
def __setitem__(self, key: str, value: Any) -> None:
|
|
253
|
+
self.__setattr__(key, value)
|
|
254
|
+
|
|
255
|
+
def __dir__(self) -> Iterable[str]:
|
|
256
|
+
return [*self.named, *super().__dir__(), "raw"]
|
|
257
|
+
|
|
258
|
+
def __repr__(self) -> str:
|
|
259
|
+
return f"<instrument {self.ref}>"
|
|
260
|
+
|
|
261
|
+
|
|
262
|
+
def named_values(quantities: Dict[str, Any]) -> Dict[str, Reading]:
|
|
263
|
+
"""What instrument(...) was given besides its id, driver and
|
|
264
|
+
connection: readings and settings only."""
|
|
265
|
+
wrong = [
|
|
266
|
+
name for name, given in quantities.items() if not isinstance(given, Reading)
|
|
267
|
+
]
|
|
268
|
+
if wrong:
|
|
269
|
+
raise TypeError(
|
|
270
|
+
f"{', '.join(wrong)}: give an instrument reading(...) or setting(...)"
|
|
271
|
+
)
|
|
272
|
+
return dict(quantities)
|
thzdaq_api/remote.py
ADDED
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
"""RemoteLab: the bench in the daemon, over HTTP. Operations are POSTed as JSON,
|
|
2
|
+
events come on a stream (SSE) read by a thread per subscription.
|
|
3
|
+
|
|
4
|
+
When call() returns, every subscription has heard the events the operation
|
|
5
|
+
caused (the daemon names its last event in the answer), so a client sees the
|
|
6
|
+
change it made as everyone else does, in the same order. A stream that breaks
|
|
7
|
+
reconnects with the number of the last event it heard and gets what it missed,
|
|
8
|
+
or Resync when the daemon no longer has it. A restarted daemon serves on
|
|
9
|
+
another port: the lab finds it again by its host file (find), and its
|
|
10
|
+
listeners get Resync, since the new daemon numbers its events anew.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
import http.client
|
|
14
|
+
import os
|
|
15
|
+
import socket
|
|
16
|
+
import threading
|
|
17
|
+
from typing import Callable, List, Optional, TypeVar
|
|
18
|
+
|
|
19
|
+
import msgspec
|
|
20
|
+
|
|
21
|
+
from thzdaq_api import wire
|
|
22
|
+
from thzdaq_api.daemon import Health, Heartbeat, HostInfo
|
|
23
|
+
from thzdaq_api.errors import ErrorCode, LabError
|
|
24
|
+
from thzdaq_api.events import Event, Resync
|
|
25
|
+
from thzdaq_api.operation import Operation
|
|
26
|
+
from thzdaq_api.transport import (
|
|
27
|
+
CLIENT,
|
|
28
|
+
EVENTS,
|
|
29
|
+
HEALTH,
|
|
30
|
+
HEARTBEAT,
|
|
31
|
+
HEARTBEAT_S,
|
|
32
|
+
LAST_EVENT,
|
|
33
|
+
LOCALHOST,
|
|
34
|
+
OPERATIONS,
|
|
35
|
+
ORIGIN,
|
|
36
|
+
PID,
|
|
37
|
+
SEQ,
|
|
38
|
+
TOKEN,
|
|
39
|
+
WINDOW,
|
|
40
|
+
bearer,
|
|
41
|
+
frames,
|
|
42
|
+
request,
|
|
43
|
+
)
|
|
44
|
+
|
|
45
|
+
R = TypeVar("R")
|
|
46
|
+
|
|
47
|
+
CATCH_UP_S = 5.0 # how long call() waits for its events to be heard
|
|
48
|
+
SILENT_S = 3 * HEARTBEAT_S # a stream silent this long is broken: reconnect
|
|
49
|
+
RECONNECT_S = (0.5, 5.0) # first and longest pause before reconnecting
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def health(host: HostInfo, timeout: float = 1.0) -> Optional[Health]:
|
|
53
|
+
"""What the daemon of a host file says about itself; None if it does not answer."""
|
|
54
|
+
try:
|
|
55
|
+
status, _, data = request(host.port, host.token, "GET", HEALTH, timeout=timeout)
|
|
56
|
+
except LabError:
|
|
57
|
+
return None
|
|
58
|
+
if status != 200:
|
|
59
|
+
return None
|
|
60
|
+
return msgspec.json.decode(data, type=Health)
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
Find = Callable[[], Optional[HostInfo]] # where the daemon serves now
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
class RemoteLab:
|
|
67
|
+
def __init__(
|
|
68
|
+
self,
|
|
69
|
+
host: HostInfo,
|
|
70
|
+
origin: str = "client",
|
|
71
|
+
kind: str = "client",
|
|
72
|
+
find: Optional[Find] = None,
|
|
73
|
+
window: str = "",
|
|
74
|
+
):
|
|
75
|
+
"""window: the id of the main window this client is (thzdaq_api.ui),
|
|
76
|
+
told with its event streams: the daemon sends it what agents ask of
|
|
77
|
+
the window."""
|
|
78
|
+
self.host = host
|
|
79
|
+
self.origin = origin
|
|
80
|
+
self.kind = kind
|
|
81
|
+
self.find = find
|
|
82
|
+
self.window = window
|
|
83
|
+
self.heartbeat: Optional[Heartbeat] = None # the last one heard
|
|
84
|
+
self._streams: List["_Stream"] = []
|
|
85
|
+
self._lock = threading.Lock()
|
|
86
|
+
|
|
87
|
+
def call(self, operation: Operation[R]) -> R:
|
|
88
|
+
asked = self.host
|
|
89
|
+
try:
|
|
90
|
+
status, headers, data = self._post(asked, operation)
|
|
91
|
+
except LabError as e:
|
|
92
|
+
if e.code != ErrorCode.UNREACHABLE or self.current_host().pid == asked.pid:
|
|
93
|
+
raise
|
|
94
|
+
# The daemon restarted: the old one is gone, the new one is asked
|
|
95
|
+
status, headers, data = self._post(self.host, operation)
|
|
96
|
+
if status != 200:
|
|
97
|
+
raise wire.decode_failure(data)
|
|
98
|
+
with self._lock:
|
|
99
|
+
streams = list(self._streams)
|
|
100
|
+
for stream in streams:
|
|
101
|
+
stream.wait_for(int(headers[SEQ]), CATCH_UP_S)
|
|
102
|
+
return wire.decode_result(type(operation), data)
|
|
103
|
+
|
|
104
|
+
def _post(self, host: HostInfo, operation: Operation):
|
|
105
|
+
return request(
|
|
106
|
+
host.port,
|
|
107
|
+
host.token,
|
|
108
|
+
"POST",
|
|
109
|
+
OPERATIONS + operation.name,
|
|
110
|
+
wire.encode(operation),
|
|
111
|
+
{ORIGIN: self.origin},
|
|
112
|
+
)
|
|
113
|
+
|
|
114
|
+
def current_host(self) -> HostInfo:
|
|
115
|
+
"""Where the daemon serves now, as its host file says when it is known."""
|
|
116
|
+
if self.find is not None:
|
|
117
|
+
found = self.find()
|
|
118
|
+
if found is not None:
|
|
119
|
+
self.host = found
|
|
120
|
+
return self.host
|
|
121
|
+
|
|
122
|
+
def subscribe(
|
|
123
|
+
self, listener: Callable[[Event], None], since: Optional[int] = None
|
|
124
|
+
) -> Callable[[], None]:
|
|
125
|
+
stream = _Stream(self, listener, since)
|
|
126
|
+
with self._lock:
|
|
127
|
+
self._streams.append(stream)
|
|
128
|
+
stream.start()
|
|
129
|
+
stream.wait_connected(CATCH_UP_S)
|
|
130
|
+
return lambda: self._stop(stream)
|
|
131
|
+
|
|
132
|
+
def close(self) -> None:
|
|
133
|
+
with self._lock:
|
|
134
|
+
streams = list(self._streams)
|
|
135
|
+
for stream in streams:
|
|
136
|
+
self._stop(stream)
|
|
137
|
+
|
|
138
|
+
def _stop(self, stream: "_Stream") -> None:
|
|
139
|
+
stream.stop()
|
|
140
|
+
with self._lock:
|
|
141
|
+
if stream in self._streams:
|
|
142
|
+
self._streams.remove(stream)
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
class _Stream:
|
|
146
|
+
"""One subscription: a thread reading the event stream, reconnecting."""
|
|
147
|
+
|
|
148
|
+
def __init__(
|
|
149
|
+
self, lab: RemoteLab, listener: Callable[[Event], None], since: Optional[int]
|
|
150
|
+
):
|
|
151
|
+
self.lab = lab
|
|
152
|
+
self.listener = listener
|
|
153
|
+
self.seq = since # the last event heard
|
|
154
|
+
self.pid: Optional[int] = None # the daemon heard
|
|
155
|
+
self.connected = False
|
|
156
|
+
self.caught_up = False # the first heartbeat: what was missed is heard
|
|
157
|
+
self._heard = threading.Condition()
|
|
158
|
+
self._stopped = threading.Event()
|
|
159
|
+
self._connection: Optional[http.client.HTTPConnection] = None
|
|
160
|
+
self._socket: Optional[socket.socket] = None
|
|
161
|
+
self._thread = threading.Thread(target=self._run, name="events", daemon=True)
|
|
162
|
+
|
|
163
|
+
def start(self) -> None:
|
|
164
|
+
self._thread.start()
|
|
165
|
+
|
|
166
|
+
def stop(self) -> None:
|
|
167
|
+
self._stopped.set()
|
|
168
|
+
sock = self._socket
|
|
169
|
+
if sock is not None:
|
|
170
|
+
# The reader blocks on the socket: shutting it down wakes it
|
|
171
|
+
try:
|
|
172
|
+
sock.shutdown(socket.SHUT_RDWR)
|
|
173
|
+
except OSError:
|
|
174
|
+
pass # already closed by the other side
|
|
175
|
+
with self._heard:
|
|
176
|
+
self._heard.notify_all()
|
|
177
|
+
if threading.current_thread() is not self._thread:
|
|
178
|
+
self._thread.join(2.0)
|
|
179
|
+
|
|
180
|
+
def wait_connected(self, timeout: float) -> None:
|
|
181
|
+
"""Until the daemon has answered (its first heartbeat), or timeout."""
|
|
182
|
+
with self._heard:
|
|
183
|
+
self._heard.wait_for(
|
|
184
|
+
lambda: self.caught_up or self._stopped.is_set(), timeout
|
|
185
|
+
)
|
|
186
|
+
|
|
187
|
+
def wait_for(self, seq: int, timeout: float) -> None:
|
|
188
|
+
"""Until this stream has heard event seq (or it is down: nothing to wait for)."""
|
|
189
|
+
with self._heard:
|
|
190
|
+
self._heard.wait_for(
|
|
191
|
+
lambda: not self.connected
|
|
192
|
+
or self._stopped.is_set()
|
|
193
|
+
or (self.seq is not None and self.seq >= seq),
|
|
194
|
+
timeout,
|
|
195
|
+
)
|
|
196
|
+
|
|
197
|
+
def _run(self) -> None:
|
|
198
|
+
pause = RECONNECT_S[0]
|
|
199
|
+
while not self._stopped.is_set():
|
|
200
|
+
try:
|
|
201
|
+
self._listen()
|
|
202
|
+
pause = RECONNECT_S[0]
|
|
203
|
+
except (OSError, http.client.HTTPException, LabError):
|
|
204
|
+
pass # the daemon went or restarts: try again after a pause
|
|
205
|
+
finally:
|
|
206
|
+
self._down()
|
|
207
|
+
if self._stopped.wait(pause):
|
|
208
|
+
return
|
|
209
|
+
pause = min(pause * 2, RECONNECT_S[1])
|
|
210
|
+
|
|
211
|
+
def _listen(self) -> None:
|
|
212
|
+
host = self.lab.current_host()
|
|
213
|
+
if self.pid is not None and host.pid != self.pid:
|
|
214
|
+
self.seq = None # a new daemon numbers its events anew
|
|
215
|
+
self.listener(Event(0, "", Resync()))
|
|
216
|
+
self.pid = host.pid
|
|
217
|
+
headers = {
|
|
218
|
+
TOKEN: bearer(host.token),
|
|
219
|
+
CLIENT: self.lab.kind,
|
|
220
|
+
ORIGIN: self.lab.origin,
|
|
221
|
+
PID: str(os.getpid()),
|
|
222
|
+
}
|
|
223
|
+
if self.lab.window:
|
|
224
|
+
headers[WINDOW] = self.lab.window
|
|
225
|
+
if self.seq is not None:
|
|
226
|
+
headers[LAST_EVENT] = str(self.seq)
|
|
227
|
+
self._connection = http.client.HTTPConnection(
|
|
228
|
+
LOCALHOST, host.port, timeout=SILENT_S
|
|
229
|
+
)
|
|
230
|
+
self._connection.connect()
|
|
231
|
+
# The response takes the socket over; stop() needs it to wake the reader
|
|
232
|
+
self._socket = self._connection.sock
|
|
233
|
+
self._connection.request("GET", EVENTS, headers=headers)
|
|
234
|
+
response = self._connection.getresponse()
|
|
235
|
+
if response.status != 200:
|
|
236
|
+
raise wire.decode_failure(response.read())
|
|
237
|
+
for frame in frames(iter(response.readline, b"")):
|
|
238
|
+
if self._stopped.is_set():
|
|
239
|
+
return
|
|
240
|
+
if frame.event == HEARTBEAT:
|
|
241
|
+
beat = msgspec.json.decode(frame.data, type=Heartbeat)
|
|
242
|
+
self.lab.heartbeat = beat
|
|
243
|
+
self.caught_up = True
|
|
244
|
+
self._heard_up_to(beat.seq)
|
|
245
|
+
continue
|
|
246
|
+
event = wire.decode_event(frame.data.encode())
|
|
247
|
+
self.listener(event)
|
|
248
|
+
self._heard_up_to(event.seq)
|
|
249
|
+
if not self._stopped.is_set():
|
|
250
|
+
raise LabError(ErrorCode.UNREACHABLE, "The event stream ended")
|
|
251
|
+
|
|
252
|
+
def _heard_up_to(self, seq: int) -> None:
|
|
253
|
+
with self._heard:
|
|
254
|
+
self.connected = True
|
|
255
|
+
self.seq = seq if self.seq is None else max(self.seq, seq)
|
|
256
|
+
self._heard.notify_all()
|
|
257
|
+
|
|
258
|
+
def _down(self) -> None:
|
|
259
|
+
with self._heard:
|
|
260
|
+
self.connected = False
|
|
261
|
+
self._heard.notify_all()
|
|
262
|
+
if self._connection is not None:
|
|
263
|
+
self._connection.close()
|
|
264
|
+
self._connection = None
|
|
265
|
+
if self._socket is not None:
|
|
266
|
+
self._socket.close()
|
|
267
|
+
self._socket = None
|
thzdaq_api/rights.py
ADDED
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
"""What agents may do, by the rights a call needs: allow, ask (a person allows
|
|
2
|
+
it first) or deny. The daemon keeps the table in its settings; a person changes
|
|
3
|
+
it in the window (the Daemon dock) or with thzdaq daemon settings.
|
|
4
|
+
|
|
5
|
+
Some answers stay whatever the table says: agents never change the profile,
|
|
6
|
+
answer for a person or write raw commands, a dangerous step is always asked,
|
|
7
|
+
and a set an agent may do alone is still asked for a jump ×10 or a value
|
|
8
|
+
beyond warn_min..warn_max.
|
|
9
|
+
|
|
10
|
+
A script has the rights of whoever started it. An agent's script goes by this
|
|
11
|
+
table as its agent does. A person's script, and a console of a window (code a
|
|
12
|
+
person types), go by PERSON_SCRIPTS: it changes
|
|
13
|
+
the bench within its limits as the person would in a dock, and what a dock
|
|
14
|
+
confirms (a dangerous step, a jump or a value beyond the warn range, another's
|
|
15
|
+
sweep, a raw write, a change of the profile) waits for a person, unless the
|
|
16
|
+
person allowed it at the script's start (thzdaq script start --allow).
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
from enum import Enum
|
|
20
|
+
from typing import Mapping
|
|
21
|
+
|
|
22
|
+
from thzdaq_api.operation import Rights
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class Decision(str, Enum):
|
|
26
|
+
ALLOW = "allow"
|
|
27
|
+
ASK = "ask"
|
|
28
|
+
DENY = "deny"
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
# What agents may do until a person changes it
|
|
32
|
+
AGENTS: Mapping[Rights, Decision] = {
|
|
33
|
+
Rights.READ: Decision.ALLOW,
|
|
34
|
+
Rights.STOP: Decision.ALLOW,
|
|
35
|
+
Rights.SET: Decision.ASK,
|
|
36
|
+
Rights.RUN: Decision.ASK,
|
|
37
|
+
Rights.DAEMON: Decision.ASK,
|
|
38
|
+
Rights.STATION: Decision.DENY,
|
|
39
|
+
Rights.ANSWER: Decision.DENY,
|
|
40
|
+
Rights.RAW_QUERY: Decision.ASK,
|
|
41
|
+
Rights.RAW_WRITE: Decision.DENY,
|
|
42
|
+
Rights.LIBRARY: Decision.ASK,
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
# What nobody changes: an agent could raise its own limits or rights, stand
|
|
46
|
+
# for the person it asks, or change an instrument past every limit
|
|
47
|
+
FIXED: Mapping[Rights, Decision] = {
|
|
48
|
+
Rights.STATION: Decision.DENY,
|
|
49
|
+
Rights.ANSWER: Decision.DENY,
|
|
50
|
+
Rights.RAW_WRITE: Decision.DENY,
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
# What a script a person started, or a console, may do: what the person does in a dock goes
|
|
54
|
+
# at once, what a dock confirms waits for a person (a call that may harm the
|
|
55
|
+
# bench is asked besides, as an agent's)
|
|
56
|
+
PERSON_SCRIPTS: Mapping[Rights, Decision] = {
|
|
57
|
+
Rights.READ: Decision.ALLOW,
|
|
58
|
+
Rights.STOP: Decision.ALLOW,
|
|
59
|
+
Rights.SET: Decision.ALLOW,
|
|
60
|
+
Rights.RUN: Decision.ALLOW,
|
|
61
|
+
Rights.DAEMON: Decision.ASK,
|
|
62
|
+
Rights.STATION: Decision.ASK,
|
|
63
|
+
Rights.ANSWER: Decision.DENY,
|
|
64
|
+
Rights.RAW_QUERY: Decision.ALLOW,
|
|
65
|
+
Rights.RAW_WRITE: Decision.ASK,
|
|
66
|
+
Rights.LIBRARY: Decision.ALLOW,
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
# What a call of each rights does, for the person who chooses
|
|
70
|
+
MEANS: Mapping[Rights, str] = {
|
|
71
|
+
Rights.READ: "look at devices, measurements and the daemon",
|
|
72
|
+
Rights.SET: "set a quantity, run a device action",
|
|
73
|
+
Rights.RUN: "start measurements, comment on them",
|
|
74
|
+
Rights.STOP: "end measurements, bring devices to their safe state",
|
|
75
|
+
Rights.DAEMON: "change the daemon's settings, stop or restart it",
|
|
76
|
+
Rights.STATION: "change the profile and what agents may do",
|
|
77
|
+
Rights.ANSWER: "answer for a person what waits for one",
|
|
78
|
+
Rights.RAW_QUERY: "ask an instrument a raw command (with ?)",
|
|
79
|
+
Rights.RAW_WRITE: "send an instrument a raw command that no limit checks",
|
|
80
|
+
Rights.LIBRARY: "write the bench's own measurements (scripts of measurements/)",
|
|
81
|
+
}
|