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/script.py ADDED
@@ -0,0 +1,382 @@
1
+ """A script's own measurement as the script writes it: the daemon keeps a
2
+ session (thzdaq_api.sessions), a measurement with its file, number and events,
3
+ and the script fills it.
4
+
5
+ with lab.measurement("pv_fine", devices=[bias, pm], exclusive=[bias]) as m:
6
+ m.plot("scan", x="voltage", y="power") # a live plot where it is followed
7
+ m.show() # in a window of its own (or "gui")
8
+ m.restore(bias, "voltage_set") # set back however it ends
9
+ for v in m.sweep("2:3:51", unit="mV"): # each step looks for a cancel
10
+ bias.voltage_set = v
11
+ m.record("scan", voltage=v, power=pm.power)
12
+ m.progress()
13
+
14
+ The daemon does what restore and on_exit name when the session ends, however
15
+ it ends: at the end of the with block; at a cancel (thzdaq cancel <id>, Stop
16
+ in a window), where m.sweep, m.sleep and m.check_cancel raise Cancelled and the
17
+ with block ends the session cancelled and goes on after it; at Ctrl+C
18
+ (interrupted); or when the script dies and falls silent (interrupted too).
19
+
20
+ While the with block runs, a thread tells the daemon the script is alive and
21
+ hears a cancel at once (keep_session).
22
+ """
23
+
24
+ import hashlib
25
+ import queue
26
+ import sys
27
+ import threading
28
+ import traceback
29
+ from pathlib import Path
30
+ from typing import (
31
+ Any,
32
+ Callable,
33
+ Dict,
34
+ Iterable,
35
+ Iterator,
36
+ Optional,
37
+ Set,
38
+ TypeVar,
39
+ Union,
40
+ )
41
+
42
+ from thzdaq_api.approvals import AnswerApproval, Approval
43
+ from thzdaq_api.data import Measured, encode_values
44
+ from thzdaq_api.errors import ErrorCode, LabError
45
+ from thzdaq_api.events import ApprovalAnswered, ApprovalRequested
46
+ from thzdaq_api.measurement_file import (
47
+ CANCELLED,
48
+ COMPLETED,
49
+ FAILED,
50
+ INTERRUPTED,
51
+ RUNNING,
52
+ Column,
53
+ column_for,
54
+ )
55
+ from thzdaq_api.measurements import PlotInfo, RunInfo
56
+ from thzdaq_api.origins import PLOTS
57
+ from thzdaq_api.sessions import (
58
+ KEEP_S,
59
+ AdvanceSession,
60
+ CallOnExit,
61
+ EndSession,
62
+ KeepSession,
63
+ LogSession,
64
+ ParseSweep,
65
+ PlotSession,
66
+ RecordSession,
67
+ RestoreOnExit,
68
+ ScriptSource,
69
+ SessionState,
70
+ StartSession,
71
+ Swept,
72
+ )
73
+ from thzdaq_api.terminal import ALLOW, line, yes
74
+
75
+ # A device as a session names it: its ref, or the bench's object (lab["ref"])
76
+ Device = Union[str, Any]
77
+ # A column described by a script: (title, unit), or a Column
78
+ Described = Union[Column, tuple]
79
+ Typed = Callable[[str, threading.Event], Optional[str]] # a person's line, or None
80
+ # Where a measurement is shown: a window of its plots (plots, True), the main
81
+ # window (gui); False: nowhere
82
+ Where = Union[bool, str]
83
+ Show = Callable[[int, str], None] # the bench's: a measurement in a window
84
+
85
+
86
+ def place(where: Where) -> str:
87
+ """Where a measurement is shown, by the name of its window."""
88
+ return PLOTS if where is True else str(where)
89
+
90
+
91
+ R = TypeVar("R")
92
+
93
+
94
+ class Cancelled(Exception):
95
+ """The measurement was asked to stop: its session ends cancelled."""
96
+
97
+
98
+ def ref_of(device: Device) -> str:
99
+ return device if isinstance(device, str) else device.ref
100
+
101
+
102
+ def described(key: str, given: Described) -> Column:
103
+ return given if isinstance(given, Column) else Column(key, *given)
104
+
105
+
106
+ def script_source(
107
+ path: Optional[str], workspace: Optional[Path]
108
+ ) -> Optional[ScriptSource]:
109
+ """The script a process runs, kept with its measurements: its path (within
110
+ the workspace when it is in one), hash and text; None without a file (a
111
+ notebook, the interpreter's prompt)."""
112
+ if path is None:
113
+ return None
114
+ file = Path(path).resolve()
115
+ data = file.read_bytes()
116
+ inside = workspace is not None and file.is_relative_to(workspace)
117
+ shown = file.relative_to(workspace) if inside else file
118
+ text = data.decode("utf-8", errors="replace")
119
+ return ScriptSource(shown.as_posix(), hashlib.sha256(data).hexdigest(), text)
120
+
121
+
122
+ def ending(kind, error, trace) -> tuple:
123
+ """How a with block ended, as its session ends: status, error, traceback."""
124
+ if kind is None:
125
+ return COMPLETED, None, ""
126
+ if issubclass(kind, Cancelled):
127
+ return CANCELLED, None, ""
128
+ if issubclass(kind, KeyboardInterrupt):
129
+ return INTERRUPTED, "stopped by Ctrl+C", ""
130
+ told = "".join(traceback.format_exception(kind, error, trace))
131
+ return FAILED, f"{kind.__name__}: {error}", told
132
+
133
+
134
+ class Session:
135
+ """A script's measurement while its with block runs (lab.measurement)."""
136
+
137
+ def __init__(
138
+ self,
139
+ lab,
140
+ start: StartSession,
141
+ approve: Callable[[Callable[[], RunInfo]], RunInfo],
142
+ entered: Callable[[Optional["Session"]], None],
143
+ show: Show,
144
+ ):
145
+ """lab: the bench's Lab; approve(call): the start as a person allows
146
+ it; entered(session): the bench's calls belong to it (None: no more);
147
+ show(id, where): the bench's window of a measurement."""
148
+ self.lab = lab
149
+ self._start = start
150
+ self._approve = approve
151
+ self._entered = entered
152
+ self._show = show
153
+ self._shown: Set[str] = set() # where it is on screen already
154
+ self.run: Optional[RunInfo] = None # as it started; as it ended, after
155
+ self.id = 0
156
+ self._columns: Dict[str, Column] = {c.key: c for c in start.columns}
157
+ self._sent: Dict[str, Column] = dict(self._columns)
158
+ self._cancel = threading.Event()
159
+ self._stopped = threading.Event()
160
+ self._status = RUNNING
161
+ self._keeper = threading.Thread(target=self._keep, daemon=True)
162
+
163
+ def __enter__(self) -> "Session":
164
+ self.run = self._approve(lambda: self.lab.call(self._start))
165
+ self.id = self.run.id
166
+ self._keeper.name = f"keep session #{self.id}"
167
+ self._keeper.start()
168
+ self._entered(self)
169
+ return self
170
+
171
+ def __exit__(self, kind, error, trace) -> bool:
172
+ self._entered(None)
173
+ self._stopped.set()
174
+ status, message, told = ending(kind, error, trace)
175
+ try:
176
+ self.run = self.lab.call(EndSession(self.id, status, message, told))
177
+ finally:
178
+ self._keeper.join()
179
+ return kind is not None and issubclass(kind, Cancelled)
180
+
181
+ def _keep(self) -> None:
182
+ while not self._stopped.is_set() and self._status == RUNNING:
183
+ try:
184
+ self._heard(self.lab.call(KeepSession(id=self.id, wait=KEEP_S)))
185
+ except LabError:
186
+ self._cancel.set() # the daemon is gone: stop at the next check
187
+ return
188
+
189
+ def _heard(self, state: SessionState) -> None:
190
+ self._status = state.status
191
+ if state.cancelled or state.status != RUNNING:
192
+ self._cancel.set()
193
+
194
+ # Cancel
195
+ @property
196
+ def cancelled(self) -> bool:
197
+ """It was asked to stop (or the daemon ended it)."""
198
+ return self._cancel.is_set()
199
+
200
+ def check_cancel(self) -> None:
201
+ if self._cancel.is_set():
202
+ raise Cancelled(f"measurement #{self.id} was asked to stop")
203
+
204
+ def sleep(self, seconds: float) -> None:
205
+ """Sleep that ends at once with Cancelled when a cancel comes."""
206
+ self._cancel.wait(max(0.0, seconds))
207
+ self.check_cancel()
208
+
209
+ def sweep(
210
+ self, values: Union[str, Swept, Iterable[float]], unit: str = ""
211
+ ) -> Iterator[Measured]:
212
+ """The values of a sweep, typed as people type it ("2:3:51" with unit
213
+ "mV"), declared (value(...) of a sweep) or given (SI); each in SI
214
+ units with its unit, after a look for a cancel."""
215
+ if isinstance(values, Swept):
216
+ values, unit = values.typed(), values.unit
217
+ if isinstance(values, str):
218
+ parsed = self.lab.call(ParseSweep(text=values, unit=unit))
219
+ values, unit = parsed.values, parsed.unit
220
+ for value in values:
221
+ self.check_cancel()
222
+ yield Measured(value, unit)
223
+
224
+ # Data
225
+ def columns(self, **given: Described) -> None:
226
+ """Titles and units of record keys, (title, unit) or a Column: over what
227
+ a value knows of itself (a device's reading), and for computed values."""
228
+ for key, column in given.items():
229
+ self._columns[key] = described(key, column)
230
+
231
+ def record(self, table: str, /, **values: Any) -> None:
232
+ """A record of a table: each key a column, values in SI units (a
233
+ reading, a swept value or a number of the script's)."""
234
+ fresh = []
235
+ for key, value in values.items():
236
+ column = self._column(key, value)
237
+ if column is not None and self._sent.get(key) != column:
238
+ fresh.append(column)
239
+ self._sent[key] = column
240
+ row = encode_values(values)
241
+ self._heard(
242
+ self.lab.call(
243
+ RecordSession(
244
+ id=self.id, table=table, rows=(row,), columns=tuple(fresh)
245
+ )
246
+ )
247
+ )
248
+
249
+ def _column(self, key: str, value: Any) -> Optional[Column]:
250
+ if key in self._columns:
251
+ return self._columns[key]
252
+ if isinstance(value, Measured):
253
+ title = value.title or column_for(key).title
254
+ return Column(key, title, value.unit, value.source)
255
+ return None
256
+
257
+ def progress(self, done: Optional[int] = None, total: Optional[int] = None) -> None:
258
+ """Steps done (one more when not given) of total."""
259
+ self._heard(self.lab.call(AdvanceSession(id=self.id, done=done, total=total)))
260
+
261
+ def log(self, message: str) -> None:
262
+ self.lab.call(LogSession(id=self.id, message=message))
263
+
264
+ def plot(
265
+ self,
266
+ table: str,
267
+ x: str,
268
+ y: str,
269
+ group_by: Iterable[str] = (),
270
+ title: str = "",
271
+ kind: str = "line",
272
+ z: Optional[str] = None,
273
+ show: Where = False,
274
+ into: Optional[str] = None,
275
+ ) -> PlotInfo:
276
+ """A live plot of a table where the measurement is followed, kept in
277
+ its file for Data to draw again; curves by the values of group_by.
278
+ into: a graph of the window (its title) it is drawn into, when there
279
+ is one of the same units; show: the measurement on screen at once
280
+ (see show)."""
281
+ plot = PlotInfo(
282
+ key="", title=title, table=table, x=x, y=y,
283
+ group_by=tuple(group_by), kind=kind, z=z, into=into,
284
+ ) # fmt: skip
285
+ drawn = self.lab.call(PlotSession(id=self.id, plot=plot))
286
+ if show:
287
+ self.show(show)
288
+ return drawn
289
+
290
+ def show(self, where: Where = PLOTS) -> None:
291
+ """Its plots on screen as it runs, once for each place: in a window
292
+ of their own (plots, True), or in the main window (gui), opened in
293
+ the script's workspace unless one is open already."""
294
+ shown = place(where)
295
+ if shown not in self._shown:
296
+ self._show(self.id, shown)
297
+ self._shown.add(shown)
298
+
299
+ # What the daemon does at the end
300
+ def restore(self, device: Device, key: str) -> Any:
301
+ """Set the quantity back to its value now when the session ends,
302
+ however it ends; returns that value."""
303
+ kept = self.lab.call(RestoreOnExit(id=self.id, ref=ref_of(device), key=key))
304
+ return kept.value
305
+
306
+ def on_exit(self, device: Device, action: str, **arguments: Any) -> None:
307
+ """Make the device do an action when the session ends (to_cold)."""
308
+ self.lab.call(
309
+ CallOnExit(
310
+ id=self.id, ref=ref_of(device), action=action, arguments=arguments
311
+ )
312
+ )
313
+
314
+
315
+ class AnsweredHere:
316
+ """While a call waits for a person, the person at this terminal is asked
317
+ too; the first answer, here or in a window, counts."""
318
+
319
+ def __init__(self, person, origin: str, typed: Typed = line):
320
+ """person: the bench as the person here answers in it (cli:answers);
321
+ origin: whose requests are asked here (the script's)."""
322
+ self.person = person
323
+ self.origin = origin
324
+ self.typed = typed
325
+
326
+ def __call__(self, call: Callable[[], R]) -> R:
327
+ asked: "queue.Queue[Optional[Approval]]" = queue.Queue()
328
+ gone: Dict[int, threading.Event] = {}
329
+
330
+ def heard(event) -> None:
331
+ body = event.body
332
+ if (
333
+ isinstance(body, ApprovalRequested)
334
+ and body.approval.origin == self.origin
335
+ ):
336
+ gone.setdefault(body.approval.id, threading.Event())
337
+ asked.put(body.approval)
338
+ elif isinstance(body, ApprovalAnswered):
339
+ gone.setdefault(body.id, threading.Event()).set()
340
+
341
+ outcome: Dict[str, Any] = {}
342
+
343
+ def run() -> None:
344
+ try:
345
+ outcome["result"] = call()
346
+ except LabError as e: # handed to the thread that waits for it
347
+ outcome["error"] = e
348
+ finally:
349
+ for event in list(gone.values()):
350
+ event.set()
351
+ asked.put(None)
352
+
353
+ stop = self.person.subscribe(heard)
354
+ try:
355
+ threading.Thread(target=run, daemon=True).start()
356
+ for approval in iter(asked.get, None):
357
+ self._ask(approval, gone[approval.id])
358
+ finally:
359
+ stop()
360
+ if "error" in outcome:
361
+ raise outcome["error"]
362
+ return outcome["result"]
363
+
364
+ def _ask(self, approval: Approval, gone: threading.Event) -> None:
365
+ print(f"\n{approval.title}: {approval.text}", file=sys.stderr)
366
+ if approval.warning:
367
+ print(f"warning: {approval.warning}", file=sys.stderr)
368
+ typed = self.typed(ALLOW, gone)
369
+ if typed is None:
370
+ return # answered in a window
371
+ confirm = ""
372
+ allowed = yes(typed)
373
+ if allowed and approval.confirm:
374
+ confirm = self.typed(f"type {approval.confirm} to allow it: ", gone) or ""
375
+ try:
376
+ self.person.call(
377
+ AnswerApproval(id=approval.id, allowed=allowed, confirm=confirm)
378
+ )
379
+ except LabError as e:
380
+ if e.code != ErrorCode.NOT_FOUND:
381
+ raise
382
+ print("answered elsewhere first", file=sys.stderr)
thzdaq_api/scripts.py ADDED
@@ -0,0 +1,133 @@
1
+ """Scripts the daemon runs (thzdaq script start): a file run by an interpreter
2
+ apart from any terminal, so it outlives the one it was started from. Its
3
+ output goes to <workspace>/data/scripts/<id>.log; it finds the daemon that
4
+ started it by THZDAQ_SCRIPT_ID and THZDAQ_SIMULATE, works in its workspace
5
+ (THZDAQ_WORKSPACE) and calls the daemon as script:<name>@<id>.
6
+
7
+ A script has the rights of whoever started it (thzdaq_api.rights): a
8
+ person's changes the bench as the person would in a dock, an agent's asks as
9
+ the agent does. A person may allow their script in advance what it would
10
+ otherwise ask for (allow): set:<ref> its quantities, call:<ref> its actions
11
+ (a jump or a value beyond the warn range), run:<procedure> a procedure,
12
+ raw:<instrument> raw writes to an instrument (lab.raw), which no limit checks;
13
+ a session (lab.measurement) starts without asking when every device it names
14
+ is allowed. A dangerous step is never allowed in advance. share names devices
15
+ its measurements share while another one sweeps them. An agent's allow and
16
+ share allow nothing.
17
+ """
18
+
19
+ from typing import Optional, Tuple
20
+
21
+ import msgspec
22
+
23
+ from thzdaq_api.operation import Operation, Rights
24
+ from thzdaq_api.procedures import current_name
25
+
26
+ SCRIPTS = "scripts" # the folder of a workspace's data/ that holds their logs
27
+ SCRIPT_ID_ENV = "THZDAQ_SCRIPT_ID" # a script the daemon started: its number
28
+ SIMULATE_ENV = "THZDAQ_SIMULATE" # "1": the daemon that started it simulates
29
+ STOP_S = 5.0 # a stopped script has this long to end after its cancel
30
+ OUTPUT_ENV = {"PYTHONUNBUFFERED": "1", "PYTHONIOENCODING": "utf-8"}
31
+
32
+ # Statuses of a script
33
+ RUNNING = "running"
34
+ EXITED = "exited" # ended by itself (exit_code says how)
35
+ STOPPED = "stopped" # ended by stop_script
36
+
37
+ # What may be allowed in advance: <kind>:<target>
38
+ SET, CALL, RUN, RAW = "set", "call", "run", "raw"
39
+ KINDS = (SET, CALL, RUN, RAW)
40
+ SEPARATOR = ":"
41
+
42
+
43
+ class Grant(msgspec.Struct, frozen=True):
44
+ """Allowed in advance: set (quantities) or call (actions) of a device by
45
+ its ref, run a built-in procedure by its name, or raw writes to an
46
+ instrument by its id."""
47
+
48
+ kind: str
49
+ target: str
50
+
51
+ def __str__(self) -> str:
52
+ return f"{self.kind}{SEPARATOR}{self.target}"
53
+
54
+ @classmethod
55
+ def parse(cls, text: str) -> "Grant":
56
+ """ "set:sis_bias_1" -> Grant("set", "sis_bias_1"); a procedure by
57
+ the name it has now; ValueError otherwise."""
58
+ kind, separator, target = text.strip().partition(SEPARATOR)
59
+ if not separator or kind not in KINDS or not target:
60
+ raise ValueError(
61
+ f"{text!r}: allow {', '.join(f'{k}:…' for k in KINDS)}"
62
+ " (set:sis_bias_1, call:chopper_1, run:sis.current_vs_voltage,"
63
+ " raw:signal_generator_1)"
64
+ )
65
+ return cls(kind, current_name(target) if kind == RUN else target)
66
+
67
+
68
+ class ScriptInfo(msgspec.Struct, frozen=True):
69
+ """A script the daemon runs or ran."""
70
+
71
+ id: int
72
+ name: str # its file's name without the suffix
73
+ path: str
74
+ command: Tuple[str, ...] # what was started
75
+ workspace: str # its working folder; its log is under data/scripts
76
+ log: str
77
+ origin: str # what it calls the daemon as: script:<name>@<id>
78
+ by: str # who started it
79
+ pid: Optional[int]
80
+ status: str # running, exited, stopped
81
+ started: str
82
+ ended: Optional[str] = None
83
+ exit_code: Optional[int] = None
84
+ allow: Tuple[Grant, ...] = ()
85
+ share: Tuple[str, ...] = ()
86
+ # The measurement it was started for: a run of the bench's own (custom.*)
87
+ measurement: Optional[int] = None
88
+
89
+
90
+ class ScriptLog(msgspec.Struct, frozen=True):
91
+ """UTF-8 output with CRLF as LF; next is a byte offset in the original log,
92
+ not the encoded length of text. More follows while the script runs."""
93
+
94
+ text: str
95
+ next: int
96
+ running: bool
97
+
98
+
99
+ class StartScript(Operation[ScriptInfo]):
100
+ """Run a Python script apart from any terminal: python is how a file is run
101
+ ([python], or a build's [thzdaq-cli.exe, run-script]), arguments go after
102
+ the file, workspace is its working folder (its log under data/scripts).
103
+ allow: what it may do without asking (set:<ref>, call:<ref>,
104
+ run:<procedure>, raw:<instrument> raw writes; never a dangerous step);
105
+ share: devices it shares while another measurement sweeps them."""
106
+
107
+ rights = Rights.RUN
108
+ path: str
109
+ python: Tuple[str, ...]
110
+ arguments: Tuple[str, ...] = ()
111
+ workspace: Optional[str] = None
112
+ allow: Tuple[Grant, ...] = ()
113
+ share: Tuple[str, ...] = ()
114
+
115
+
116
+ class ListScripts(Operation[Tuple[ScriptInfo, ...]]):
117
+ """Scripts the daemon runs, and those that ended lately."""
118
+
119
+
120
+ class ReadScriptLog(Operation[ScriptLog]):
121
+ """A script's output from byte since (0: from its start), up to a part at a
122
+ time; call again from next while it runs."""
123
+
124
+ id: int
125
+ since: int = 0
126
+
127
+
128
+ class StopScript(Operation[ScriptInfo]):
129
+ """Stop a script: its measurements are cancelled (they restore what they
130
+ changed), and a script that has not ended a few seconds later is ended."""
131
+
132
+ rights = Rights.STOP
133
+ id: int
thzdaq_api/sessions.py ADDED
@@ -0,0 +1,176 @@
1
+ """A script's own measurement: a session the daemon keeps while a script drives
2
+ it from outside (lab.measurement, thzdaq_api.script).
3
+
4
+ A session is a measurement like any other: a number, a file, leases on its
5
+ devices, events windows draw from. The script records into it, tells its
6
+ progress and what the daemon restores when it ends, however it ends: by the
7
+ script, by a cancel (thzdaq cancel, Stop in a window), or when the script falls
8
+ silent (it died, its terminal closed), which ends it interrupted.
9
+
10
+ Calls that belong to a session carry its number (session in read_device,
11
+ set_quantity, call_action): the session's leases are their own, and what a
12
+ person allowed when it started (its devices) is not asked again, except a
13
+ dangerous step or another measurement's sweep.
14
+ """
15
+
16
+ from typing import Any, Dict, Optional, Tuple, Union
17
+
18
+ import msgspec
19
+
20
+ from thzdaq_api.devices import QuantityValue
21
+ from thzdaq_api.measurement_file import Column
22
+ from thzdaq_api.measurements import PlotInfo, RunInfo
23
+ from thzdaq_api.operation import Operation, Rights
24
+
25
+ SILENT_S = 10.0 # a script silent this long is gone: its session is interrupted
26
+ KEEP_S = 2.0 # how long keep_session waits for a cancel before it answers
27
+
28
+
29
+ class ScriptSource(msgspec.Struct, frozen=True):
30
+ """The script a session ran, kept with its data to measure the same again."""
31
+
32
+ path: str
33
+ sha256: str
34
+ text: str
35
+
36
+
37
+ class SessionState(msgspec.Struct, frozen=True):
38
+ """How a session stands: cancelled is a request to stop (end it cancelled)."""
39
+
40
+ id: int
41
+ status: str # running, or how it ended
42
+ cancelled: bool = False
43
+
44
+
45
+ class SweepValues(msgspec.Struct, frozen=True):
46
+ values: Tuple[float, ...]
47
+ unit: str # the SI unit of the values
48
+
49
+
50
+ class Swept(msgspec.Struct, frozen=True):
51
+ """A sweep a script was given (a form's value): SI start and stop, points,
52
+ the SI unit; m.sweep(it) goes over its values."""
53
+
54
+ start: float
55
+ stop: float
56
+ points: int
57
+ unit: str = ""
58
+
59
+ def typed(self) -> str:
60
+ """As people type it, in its SI unit: start:stop:points."""
61
+ return f"{self.start!r}:{self.stop!r}:{self.points}"
62
+
63
+
64
+ class StartSession(Operation[RunInfo]):
65
+ """Start a script's own measurement (a session) named title: its file,
66
+ number and events as any measurement has. devices it uses (shared), those
67
+ of them it sweeps (exclusive: another's change spoils its data), and those
68
+ it agrees to share while another measurement sweeps them (share). A device
69
+ it uses later without naming it joins then. silent: seconds without a word
70
+ from the script (keep_session) before the session ends interrupted and the
71
+ daemon restores what the script asked to restore. plots: those it fills
72
+ from its start, as plot_session takes them."""
73
+
74
+ rights = Rights.RUN
75
+ title: str
76
+ devices: Tuple[str, ...] = ()
77
+ exclusive: Tuple[str, ...] = ()
78
+ share: Tuple[str, ...] = ()
79
+ parameters: Dict[str, Any] = {}
80
+ comment: str = ""
81
+ workspace: Optional[str] = None
82
+ script: Optional[ScriptSource] = None
83
+ columns: Tuple[Column, ...] = () # titles and units of record keys
84
+ total: Optional[int] = None # steps, when known
85
+ silent: float = SILENT_S
86
+ plots: Tuple[PlotInfo, ...] = () # those it fills from its start (declared)
87
+
88
+
89
+ class KeepSession(Operation[SessionState]):
90
+ """The script of a session is alive: the daemon keeps the session. Waits up
91
+ to wait seconds (at most 5) for a cancel and answers at once when one comes."""
92
+
93
+ id: int
94
+ wait: float = 0.0
95
+
96
+
97
+ class RecordSession(Operation[SessionState]):
98
+ """Records of a session's table, values encoded as in measurement files
99
+ (thzdaq_api.data); columns describe keys (title, unit, source) the session
100
+ does not know yet or describes anew."""
101
+
102
+ rights = Rights.RUN
103
+ id: int
104
+ table: str
105
+ rows: Tuple[Dict[str, Any], ...]
106
+ columns: Tuple[Column, ...] = ()
107
+
108
+
109
+ class AdvanceSession(Operation[SessionState]):
110
+ """Progress of a session: done steps (one more when not given) of total."""
111
+
112
+ rights = Rights.RUN
113
+ id: int
114
+ done: Optional[int] = None
115
+ total: Optional[int] = None
116
+
117
+
118
+ class LogSession(Operation[None]):
119
+ """A line of a session's log, shown where the measurement is followed."""
120
+
121
+ rights = Rights.RUN
122
+ id: int
123
+ message: str
124
+
125
+
126
+ class PlotSession(Operation[PlotInfo]):
127
+ """A plot of a session's records, drawn from now on and kept in its file;
128
+ labels left empty take the columns' titles and units. Returns it as drawn."""
129
+
130
+ rights = Rights.RUN
131
+ id: int
132
+ plot: PlotInfo
133
+
134
+
135
+ class RestoreOnExit(Operation[QuantityValue]):
136
+ """When the session ends, however it ends, the daemon sets this quantity of
137
+ a device back to the value it has now (returned), in steps where the bench
138
+ limits ask for them."""
139
+
140
+ rights = Rights.SET
141
+ id: int
142
+ ref: str
143
+ key: str
144
+
145
+
146
+ class CallOnExit(Operation[None]):
147
+ """When the session ends, however it ends, the daemon makes a device do an
148
+ action (to_cold); arguments as call_action takes them."""
149
+
150
+ rights = Rights.SET
151
+ id: int
152
+ ref: str
153
+ action: str
154
+ arguments: Dict[str, Union[bool, int, float, str]] = msgspec.field(
155
+ default_factory=dict
156
+ )
157
+
158
+
159
+ class EndSession(Operation[RunInfo]):
160
+ """End a session as the script ended: completed, cancelled (it was asked
161
+ to), failed (error and traceback say why) or interrupted (stopped by hand).
162
+ The daemon restores what it was asked to, then the measurement ends."""
163
+
164
+ rights = Rights.STOP
165
+ id: int
166
+ status: str = "completed"
167
+ error: Optional[str] = None
168
+ traceback: str = ""
169
+
170
+
171
+ class ParseSweep(Operation[SweepValues]):
172
+ """The values of a sweep typed as people type it, start:stop:points in a
173
+ unit ("2:3:51" in mV), as SI values with their SI unit."""
174
+
175
+ text: str
176
+ unit: str = ""