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.
Files changed (57) hide show
  1. thzdaq_api/__init__.py +1 -0
  2. thzdaq_api/analysis.py +62 -0
  3. thzdaq_api/approvals.py +87 -0
  4. thzdaq_api/assistant/agents.md +202 -0
  5. thzdaq_api/assistant/assistant.md +23 -0
  6. thzdaq_api/assistant/hints.md +15 -0
  7. thzdaq_api/atomic.py +79 -0
  8. thzdaq_api/catalog.py +131 -0
  9. thzdaq_api/console.py +70 -0
  10. thzdaq_api/custom.py +326 -0
  11. thzdaq_api/daemon.py +183 -0
  12. thzdaq_api/data.py +55 -0
  13. thzdaq_api/declare.py +193 -0
  14. thzdaq_api/declaring.py +125 -0
  15. thzdaq_api/devices.py +307 -0
  16. thzdaq_api/errors.py +47 -0
  17. thzdaq_api/events.py +224 -0
  18. thzdaq_api/examples/hot_cold.py +67 -0
  19. thzdaq_api/examples/hot_cold_grid.py +74 -0
  20. thzdaq_api/examples/iv_analysis.py +34 -0
  21. thzdaq_api/examples/map.py +42 -0
  22. thzdaq_api/examples/monitor.py +35 -0
  23. thzdaq_api/examples/raw_instrument.py +37 -0
  24. thzdaq_api/examples/sweep.py +38 -0
  25. thzdaq_api/examples.py +79 -0
  26. thzdaq_api/guides.py +61 -0
  27. thzdaq_api/host.py +494 -0
  28. thzdaq_api/interpreters.py +422 -0
  29. thzdaq_api/kernel.py +137 -0
  30. thzdaq_api/lab.py +562 -0
  31. thzdaq_api/lanes.py +170 -0
  32. thzdaq_api/leases.py +29 -0
  33. thzdaq_api/lock.py +65 -0
  34. thzdaq_api/measurement_file.py +459 -0
  35. thzdaq_api/measurements.py +433 -0
  36. thzdaq_api/operation.py +52 -0
  37. thzdaq_api/origins.py +86 -0
  38. thzdaq_api/present.py +376 -0
  39. thzdaq_api/procedures.py +124 -0
  40. thzdaq_api/raw.py +272 -0
  41. thzdaq_api/remote.py +267 -0
  42. thzdaq_api/rights.py +81 -0
  43. thzdaq_api/script.py +382 -0
  44. thzdaq_api/scripts.py +133 -0
  45. thzdaq_api/sessions.py +176 -0
  46. thzdaq_api/station.py +192 -0
  47. thzdaq_api/terminal.py +66 -0
  48. thzdaq_api/tools.py +275 -0
  49. thzdaq_api/transport.py +93 -0
  50. thzdaq_api/ui.py +152 -0
  51. thzdaq_api/windows.py +192 -0
  52. thzdaq_api/wire.py +35 -0
  53. thzdaq_api/workspace.py +239 -0
  54. thzdaq_api-0.0.6b3.dist-info/METADATA +30 -0
  55. thzdaq_api-0.0.6b3.dist-info/RECORD +57 -0
  56. thzdaq_api-0.0.6b3.dist-info/WHEEL +4 -0
  57. 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
+ }