thzdaq-cli 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_cli/daemon.py ADDED
@@ -0,0 +1,266 @@
1
+ """thzdaq daemon …: the daemon itself — what it holds, starting it (in the
2
+ background, or in this terminal with its log here), stopping and restarting
3
+ it, killing one that does not answer, its log, its clients, a queue that
4
+ hangs, its settings (and what agents may do). thzdaq serve runs it in this
5
+ terminal."""
6
+
7
+ import subprocess
8
+ import sys
9
+ import time
10
+ from typing import Dict, List
11
+
12
+ from thzdaq_api import host
13
+ from thzdaq_api.daemon import (
14
+ DaemonSettings,
15
+ DaemonStatus,
16
+ GetDaemonSettings,
17
+ GetDaemonStatus,
18
+ ReadDaemonLog,
19
+ ResetLane,
20
+ RestartDaemon,
21
+ SetDaemonSettings,
22
+ StopDaemon,
23
+ StopMode,
24
+ )
25
+ from thzdaq_api.errors import ErrorCode, LabError
26
+ from thzdaq_api.measurements import ListRuns
27
+ from thzdaq_api.measurement_file import RUNNING
28
+ from thzdaq_api.operation import Rights
29
+ from thzdaq_api.rights import FIXED, MEANS, Decision
30
+
31
+ from thzdaq_cli import show
32
+ from thzdaq_cli.client import FAILED, KIND, OK, Client, Mistyped, origin
33
+ from thzdaq_cli.devices import assignments
34
+
35
+ FOLLOW_S = 0.5 # how often a followed log is looked at
36
+
37
+
38
+ def add(commands) -> None:
39
+ group = commands.add_parser("daemon", help="the daemon: status, start, stop, log")
40
+ actions = group.add_subparsers(dest="action", required=True, metavar="ACTION")
41
+ actions.add_parser(
42
+ "status", help="what it is and holds (exit 1: problems, 3: none runs)"
43
+ ).set_defaults(run=status)
44
+ start = actions.add_parser("start", help="start it unless it runs")
45
+ start.add_argument("--station", help="the profile it loads when it starts")
46
+ start.add_argument(
47
+ "--foreground", action="store_true", help="in this terminal, its log here"
48
+ )
49
+ start.set_defaults(run=start_daemon)
50
+ for name, what in (("stop", "stop it"), ("restart", "stop and start it again")):
51
+ command = actions.add_parser(name, help=what)
52
+ modes = command.add_mutually_exclusive_group()
53
+ modes.add_argument(
54
+ "--cancel",
55
+ action="store_true",
56
+ help="end running measurements (they restore), then the safe state",
57
+ )
58
+ modes.add_argument(
59
+ "--abort", action="store_true", help="also break reads that hang"
60
+ )
61
+ command.set_defaults(run=stop, restart=name == "restart")
62
+ actions.add_parser("kill", help="end a daemon that does not answer").set_defaults(
63
+ run=kill
64
+ )
65
+ logs = actions.add_parser("logs", help="its log")
66
+ logs.add_argument("-n", "--lines", type=int, default=50)
67
+ logs.add_argument("-f", "--follow", action="store_true", help="then follow it")
68
+ logs.set_defaults(run=read_log)
69
+ actions.add_parser("clients", help="who listens to it").set_defaults(run=clients)
70
+ reset = actions.add_parser(
71
+ "reset-lane", help="give an instrument that hangs a new queue"
72
+ )
73
+ reset.add_argument("instrument")
74
+ reset.set_defaults(run=reset_lane)
75
+ settings = actions.add_parser("settings", help="show or change its settings")
76
+ settings.add_argument(
77
+ "--idle-timeout",
78
+ type=float,
79
+ metavar="SECONDS",
80
+ help="how long it waits with no client and no measurement; 0: never",
81
+ )
82
+ settings.add_argument(
83
+ "--agents", action="append", default=[], metavar="RIGHTS=DECISION",
84
+ help="what agents may do: set=allow, run=ask, read=deny "
85
+ f"({', '.join(r.value for r in Rights)}; {', '.join(d.value for d in Decision)})",
86
+ ) # fmt: skip
87
+ settings.set_defaults(run=change_settings)
88
+ serve = commands.add_parser(
89
+ "serve", help="the daemon in this terminal (daemon start --foreground)"
90
+ )
91
+ serve.add_argument("--station", help="the profile it loads")
92
+ serve.set_defaults(run=start_daemon, foreground=True)
93
+
94
+
95
+ def status_text(status: DaemonStatus) -> str:
96
+ process = status.process
97
+ lines = [
98
+ f"ThzDAQ {process.app_version} daemon{' (simulator)' if process.simulate else ''}"
99
+ f", pid {process.pid}, port {process.port}, since {process.started}"
100
+ + (f", {process.usage()}" if process.usage() else ""),
101
+ f"profile {show.profile(status.station, status.path)}",
102
+ ]
103
+ sections = (
104
+ ("clients", ("kind", "origin", "pid", "since"),
105
+ [(c.kind, c.origin, c.pid, c.since) for c in status.clients]),
106
+ ("measurements", ("id", "title", "done", "origin"),
107
+ [(r.id, r.title, f"{r.done}/{r.total or '?'}", r.origin) for r in status.runs]),
108
+ ("queues", ("instrument", "waiting", "running", "for"),
109
+ [(q.instrument, q.pending, q.current or "", f"{q.busy_for:.0f} s")
110
+ for q in status.lanes if q.pending or q.current]),
111
+ ("connections", ("connection", "state", "instruments"),
112
+ [(c.label, "broken" if c.broken else "open" if c.open else "closed",
113
+ ", ".join(c.instruments)) for c in status.connections]),
114
+ ("polls", ("device", "every", "subscribers"),
115
+ [(p.ref, f"{p.interval:g} s", p.subscribers) for p in status.polls]),
116
+ ) # fmt: skip
117
+ for title, headers, rows in sections:
118
+ text = show.table(headers, rows)
119
+ if text:
120
+ lines += ["", f"{title}:", text]
121
+ if status.problems:
122
+ lines += ["", "problems:", *status.problems]
123
+ if process.errors:
124
+ lines += ["", "last errors:", *process.errors]
125
+ return "\n".join(lines)
126
+
127
+
128
+ def status(args, client: Client) -> int:
129
+ found = client.running_lab().call(GetDaemonStatus())
130
+ client.out(found, status_text)
131
+ return FAILED if found.problems else OK
132
+
133
+
134
+ def start_daemon(args, client: Client) -> int:
135
+ if args.foreground:
136
+ given = ["--station", args.station] if args.station else []
137
+ given += ["--simulate"] if client.simulate else []
138
+ try:
139
+ return subprocess.call([*host.start_command(), *given])
140
+ except KeyboardInterrupt:
141
+ return OK # the daemon heard it too and stops
142
+ try:
143
+ lab = client.running_lab()
144
+ print("the daemon runs already")
145
+ except LabError as e:
146
+ if e.code != ErrorCode.UNREACHABLE:
147
+ raise
148
+ lab = host.connect_or_start(client.simulate, args.station, origin(), KIND)
149
+ print("the daemon started")
150
+ client.out(
151
+ lab.call(GetDaemonStatus()).process, lambda p: f"pid {p.pid}, port {p.port}"
152
+ )
153
+ return OK
154
+
155
+
156
+ def stop(args, client: Client) -> int:
157
+ mode = StopMode.ABORT if args.abort else StopMode.CANCEL if args.cancel else None
158
+ lab = client.running_lab()
159
+ if mode is not None:
160
+ running = [r for r in lab.call(ListRuns()) if r.status == RUNNING]
161
+ question = f"End {len(running)} running measurement(s)?"
162
+ if running and not client.ask(question):
163
+ return FAILED
164
+ operation = RestartDaemon if args.restart else StopDaemon
165
+ lab.call(operation(mode=mode or StopMode.GRACEFUL))
166
+ print("the daemon restarts" if args.restart else "the daemon stops")
167
+ return OK
168
+
169
+
170
+ def kill(args, client: Client) -> int:
171
+ killed = host.kill(client.simulate)
172
+ print(f"ended pid {killed}" if killed else "no daemon ran")
173
+ return OK
174
+
175
+
176
+ def read_log(args, client: Client) -> int:
177
+ try:
178
+ lines: List[str] = list(
179
+ client.running_lab().call(ReadDaemonLog(lines=args.lines))
180
+ )
181
+ except LabError as e: # a daemon that ended left its log: why it did
182
+ if e.code != ErrorCode.UNREACHABLE:
183
+ raise
184
+ files = host.DaemonFiles.of(client.simulate)
185
+ lines = host.log_tail(files, args.lines).splitlines()
186
+ print("\n".join(lines))
187
+ if args.follow:
188
+ follow(host.DaemonFiles.of(client.simulate).log)
189
+ return OK
190
+
191
+
192
+ def follow(path) -> None:
193
+ """What the log gets from now on, until Ctrl+C."""
194
+ seen = path.stat().st_size if path.exists() else 0
195
+ try:
196
+ while True:
197
+ time.sleep(FOLLOW_S) # the log is another process's file: look again
198
+ size = path.stat().st_size if path.exists() else 0
199
+ if size < seen:
200
+ seen = 0 # moved aside at a start: a new log
201
+ if size > seen:
202
+ with open(path, "rb") as log:
203
+ log.seek(seen)
204
+ sys.stdout.write(log.read().decode("utf-8", errors="replace"))
205
+ sys.stdout.flush()
206
+ seen = size
207
+ except KeyboardInterrupt:
208
+ pass
209
+
210
+
211
+ def clients(args, client: Client) -> int:
212
+ found = client.running_lab().call(GetDaemonStatus()).clients
213
+ client.out(
214
+ found,
215
+ lambda c: show.table(
216
+ ("kind", "origin", "pid", "window", "since"),
217
+ [(i.kind, i.origin, i.pid, i.window, i.since) for i in c],
218
+ )
219
+ or "no client",
220
+ )
221
+ return OK
222
+
223
+
224
+ def reset_lane(args, client: Client) -> int:
225
+ question = f"Break the commands of {args.instrument} and give it a new queue?"
226
+ if not client.ask(question):
227
+ return FAILED
228
+ had = client.running_lab().call(ResetLane(instrument=args.instrument))
229
+ print("a new queue" if had else f"{args.instrument} had no queue")
230
+ return OK
231
+
232
+
233
+ def change_settings(args, client: Client) -> int:
234
+ lab = client.running_lab()
235
+ agents = rights_given(args.agents)
236
+ if args.idle_timeout is None and not agents:
237
+ found = lab.call(GetDaemonSettings())
238
+ else:
239
+ found = lab.call(
240
+ SetDaemonSettings(idle_timeout=args.idle_timeout, agents=agents)
241
+ )
242
+ client.out(found, settings_text)
243
+ return OK
244
+
245
+
246
+ def rights_given(typed: List[str]) -> Dict[Rights, Decision]:
247
+ """set=allow, run=ask as the settings take them."""
248
+ given = {}
249
+ for name, decision in assignments(typed).items():
250
+ try:
251
+ given[Rights(name)] = Decision(decision)
252
+ except ValueError:
253
+ raise Mistyped(
254
+ f"--agents {name}={decision}: see daemon settings -h"
255
+ ) from None
256
+ return given
257
+
258
+
259
+ def settings_text(settings: DaemonSettings) -> str:
260
+ idle = settings.idle_timeout
261
+ rights = show.table(
262
+ ("rights", "agents", "what"),
263
+ [(r.value, d.value, MEANS[r] + (" (always)" if r in FIXED else ""))
264
+ for r, d in settings.agents.items()],
265
+ ) # fmt: skip
266
+ return f"idle timeout: {f'{idle:g} s' if idle else 'never'}\n\n{rights}"
thzdaq_cli/devices.py ADDED
@@ -0,0 +1,262 @@
1
+ """thzdaq devices, device, read, set, call, raw, safe, connections: the devices
2
+ of the bench, what they read and take, their actions, raw commands to an
3
+ instrument, the safe state, the shared connections. A value is typed with its
4
+ unit ("2.3mV", "223GHz"); the daemon parses it, checks it against the limits
5
+ and sets it in steps where they ask. A raw command goes as typed, for what a
6
+ driver does not wrap yet: a query (with ?) answers, a write is asked first,
7
+ since no limit checks it."""
8
+
9
+ from typing import Dict, List, Sequence
10
+
11
+ import msgspec
12
+ from thzdaq_api.devices import (
13
+ CallAction,
14
+ DescribeDevice,
15
+ DeviceDescription,
16
+ ListDevices,
17
+ QuantityInfo,
18
+ RawCommand,
19
+ RawReply,
20
+ ReadDevice,
21
+ SafeState,
22
+ SetQuantity,
23
+ Trace,
24
+ raw_question,
25
+ )
26
+ from thzdaq_api.station import ListConnections, ResetConnection
27
+
28
+ from thzdaq_cli import show
29
+ from thzdaq_cli.client import FAILED, OK, Client, Mistyped
30
+
31
+
32
+ def add(commands) -> None:
33
+ commands.add_parser("devices", help="the devices of the bench").set_defaults(
34
+ run=list_devices
35
+ )
36
+ device = commands.add_parser("device", help="what a device reads, takes, does")
37
+ device.add_argument("ref")
38
+ device.set_defaults(run=describe)
39
+ read = commands.add_parser("read", help="read a device")
40
+ read.add_argument("ref")
41
+ read.add_argument("keys", nargs="*", help="quantities; all it reads by default")
42
+ read.set_defaults(run=read_device)
43
+ set_ = commands.add_parser(
44
+ "set", help="set a quantity: thzdaq set sis_bias_1 voltage_set 2.3mV"
45
+ )
46
+ set_.add_argument("ref")
47
+ set_.add_argument("key")
48
+ set_.add_argument("value", help="with its unit, or SI; on/off for switches")
49
+ set_.add_argument(
50
+ "--share", action="store_true", help="also while a measurement sweeps it"
51
+ )
52
+ set_.set_defaults(run=set_quantity)
53
+ call = commands.add_parser("call", help="an action: thzdaq call chopper_1 to_hot")
54
+ call.add_argument("ref")
55
+ call.add_argument("action")
56
+ call.add_argument("arguments", nargs="*", metavar="NAME=VALUE")
57
+ call.add_argument(
58
+ "--share", action="store_true", help="also while a measurement sweeps it"
59
+ )
60
+ call.set_defaults(run=call_action)
61
+ raw = commands.add_parser(
62
+ "raw", help='a command as typed: thzdaq raw signal_generator_1 "*IDN?"'
63
+ )
64
+ raw.add_argument("instrument", help="its id in the profile")
65
+ raw.add_argument("command", help="with ? a query; else a write, asked first")
66
+ raw.add_argument(
67
+ "--answer", action="store_true", help="read the answer of a write too"
68
+ )
69
+ raw.add_argument(
70
+ "--share", action="store_true", help="also while a measurement sweeps it"
71
+ )
72
+ raw.set_defaults(run=raw_command)
73
+ safe = commands.add_parser("safe", help="set the profile's safe state")
74
+ safe.add_argument(
75
+ "--share", action="store_true", help="also where measurements sweep"
76
+ )
77
+ safe.set_defaults(run=safe_state)
78
+ connections = commands.add_parser("connections", help="shared connections")
79
+ actions = connections.add_subparsers(dest="action", metavar="ACTION")
80
+ reset = actions.add_parser("reset", help="break and reopen one that hangs")
81
+ reset.add_argument("number", type=int, help="as the list numbers it")
82
+ connections.set_defaults(run=list_connections, action=None)
83
+
84
+
85
+ def list_devices(args, client: Client) -> int:
86
+ found = client.call(ListDevices())
87
+ client.out(
88
+ found,
89
+ lambda d: show.table(
90
+ ("device", "type", "title"), [(i.ref, i.type, i.title) for i in d]
91
+ ),
92
+ )
93
+ return OK
94
+
95
+
96
+ def description_text(found: DeviceDescription) -> str:
97
+ device = found.device
98
+ lines = [f"{device.title} ({device.ref}, {device.type}, {device.driver})"]
99
+ quantities = show.table(
100
+ ("quantity", "title", "unit", "", "min", "max"),
101
+ [(q.key, q.title, q.unit, access(q), show.value(q.minimum), show.value(q.maximum))
102
+ for q in found.quantities],
103
+ ) # fmt: skip
104
+ if quantities:
105
+ lines += ["", quantities]
106
+ for action in found.actions:
107
+ arguments = ", ".join(f"{a.key}={a.unit or a.kind}" for a in action.arguments)
108
+ warning = f" ({action.danger})" if action.danger else ""
109
+ lines.append(f"action {action.key} {arguments}{warning}".rstrip())
110
+ for setting in found.settings:
111
+ lines.append(f"setting {setting.key} {setting.unit} (in the profile)")
112
+ return "\n".join(lines)
113
+
114
+
115
+ def access(quantity: QuantityInfo) -> str:
116
+ return ("r" if quantity.readable else "-") + ("w" if quantity.settable else "-")
117
+
118
+
119
+ def describe(args, client: Client) -> int:
120
+ client.out(client.call(DescribeDevice(ref=args.ref)), description_text)
121
+ return OK
122
+
123
+
124
+ def read_device(args, client: Client) -> int:
125
+ units = {
126
+ q.key: q.unit for q in client.call(DescribeDevice(ref=args.ref)).quantities
127
+ }
128
+ reading = client.call(ReadDevice(ref=args.ref, keys=tuple(args.keys) or None))
129
+ client.out(
130
+ reading,
131
+ lambda r: show.table(
132
+ ("quantity", "value"),
133
+ [(key, show.value(v, units.get(key, ""))) for key, v in r.values.items()],
134
+ ),
135
+ )
136
+ return OK
137
+
138
+
139
+ def quantity(client: Client, ref: str, key: str) -> QuantityInfo:
140
+ found = client.call(DescribeDevice(ref=ref)).quantities
141
+ return next((q for q in found if q.key == key), QuantityInfo(key, key))
142
+
143
+
144
+ def set_quantity(args, client: Client) -> int:
145
+ found = quantity(client, args.ref, args.key)
146
+ if found.danger and not client.ask(f"{found.danger}. Set {args.ref} {args.key}?"):
147
+ return FAILED
148
+ done = client.shared(
149
+ lambda share: client.call(
150
+ SetQuantity(
151
+ ref=args.ref, key=args.key, value=args.value, share=share or args.share
152
+ )
153
+ )
154
+ )
155
+ if done is None:
156
+ return FAILED
157
+ client.out(done, lambda d: f"{d.ref} {d.key} = {show.value(d.value, found.unit)}")
158
+ return OK
159
+
160
+
161
+ def assignments(given: Sequence[str]) -> Dict[str, str]:
162
+ """NAME=VALUE pairs as typed; the daemon parses the values."""
163
+ found = {}
164
+ for text in given:
165
+ name, sign, value = text.partition("=")
166
+ if not sign or not name:
167
+ raise Mistyped(f"{text!r} is not NAME=VALUE")
168
+ found[name] = value
169
+ return found
170
+
171
+
172
+ def call_action(args, client: Client) -> int:
173
+ arguments = assignments(args.arguments)
174
+ actions = client.call(DescribeDevice(ref=args.ref)).actions
175
+ danger = next((a.danger for a in actions if a.key == args.action), "")
176
+ if danger and not client.ask(f"{danger}. {args.action} on {args.ref}?"):
177
+ return FAILED
178
+ done = client.shared(
179
+ lambda share: client.call(
180
+ CallAction(
181
+ ref=args.ref,
182
+ action=args.action,
183
+ arguments=arguments,
184
+ share=share or args.share,
185
+ )
186
+ )
187
+ )
188
+ if done is None:
189
+ return FAILED
190
+ client.out(done, lambda d: result_text(d.result))
191
+ return OK
192
+
193
+
194
+ def raw_command(args, client: Client) -> int:
195
+ command = RawCommand(
196
+ instrument=args.instrument, command=args.command, answer=args.answer
197
+ )
198
+ question = raw_question(args.instrument, args.command)
199
+ if not command.query and not client.ask(question):
200
+ return FAILED
201
+ done = client.shared(
202
+ lambda share: client.call(
203
+ msgspec.structs.replace(command, share=share or args.share)
204
+ )
205
+ )
206
+ if done is None:
207
+ return FAILED
208
+ client.out(done, raw_text)
209
+ return OK
210
+
211
+
212
+ def raw_text(reply: RawReply) -> str:
213
+ if reply.answer is not None:
214
+ return reply.answer
215
+ return f"sent; read again: {', '.join(reply.unknown)}"
216
+
217
+
218
+ def result_text(result) -> str:
219
+ if isinstance(result, Trace):
220
+ points, frequency = len(result.frequency), result.frequency
221
+ name = f" {result.parameter}" if result.parameter else ""
222
+ span = f", {frequency[0]:.6g}..{frequency[-1]:.6g} Hz" if points else ""
223
+ return f"trace{name} of {points} points{span} (--json gives it all)"
224
+ return "done" if result is None else show.value(result)
225
+
226
+
227
+ def safe_state(args, client: Client) -> int:
228
+ if not client.ask("Set every value of the profile's safe state now?"):
229
+ return FAILED
230
+ done = client.call(SafeState(share=args.share))
231
+ client.out(
232
+ done,
233
+ lambda d: show.table(
234
+ ("device", "quantity", "value", "result"),
235
+ [(v.ref, v.key, show.value(v.value), v.error or "set") for v in d],
236
+ )
237
+ or "the profile names no safe state",
238
+ )
239
+ return FAILED if any(value.error for value in done) else OK
240
+
241
+
242
+ def list_connections(args, client: Client) -> int:
243
+ found = client.call(ListConnections())
244
+ if args.action == "reset":
245
+ if not 1 <= args.number <= len(found):
246
+ print(f"thzdaq: no connection {args.number}; thzdaq connections lists them")
247
+ return FAILED
248
+ chosen = found[args.number - 1]
249
+ reopened = client.call(ResetConnection(key=chosen.key))
250
+ print(f"{chosen.label}: {'reset' if reopened else 'was not open'}")
251
+ return OK
252
+ rows: List[tuple] = [
253
+ (number, c.label, "broken" if c.broken else "open" if c.open else "closed",
254
+ ", ".join(c.instruments))
255
+ for number, c in enumerate(found, 1)
256
+ ] # fmt: skip
257
+ client.out(
258
+ found,
259
+ lambda _: show.table(("", "connection", "state", "instruments"), rows)
260
+ or "no shared connection",
261
+ )
262
+ return OK