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/guides.py ADDED
@@ -0,0 +1,61 @@
1
+ """Guides for agents and the assistant: how to work with the bench, as text a
2
+ model reads (thzdaq://guide/<topic> of the MCP server, AGENTS.md of a
3
+ workspace, the system prompt of the assistant in the window). They are files
4
+ of this package, so every installation has them: the build, a PyPI install and
5
+ the sources. The rules are written once, in the agents' guide; the assistant
6
+ reads them as a section of it."""
7
+
8
+ from importlib import resources
9
+ from importlib.resources.abc import Traversable
10
+ from typing import Tuple
11
+
12
+ from thzdaq_api.errors import ErrorCode, LabError
13
+
14
+ FOLDER = "assistant"
15
+ SUFFIX = ".md"
16
+ AGENTS = "agents" # how an agent measures with the bench: the AGENTS.md of a workspace
17
+ ASSISTANT = "assistant" # the assistant in the window: its part of the system prompt
18
+ HINTS = "hints" # code the assistant writes in the editor and the console
19
+ # Sections of the agents' guide the assistant reads too
20
+ RULES = "Rules"
21
+ OWN_MEASUREMENT = "A measurement of the bench's own"
22
+
23
+
24
+ def folder() -> Traversable:
25
+ return resources.files(__package__) / FOLDER
26
+
27
+
28
+ def topics() -> Tuple[str, ...]:
29
+ return tuple(
30
+ sorted(
31
+ item.name.removesuffix(SUFFIX)
32
+ for item in folder().iterdir()
33
+ if item.name.endswith(SUFFIX)
34
+ )
35
+ )
36
+
37
+
38
+ def guide(topic: str) -> str:
39
+ """The guide's text (Markdown); LabError NOT_FOUND names the topics."""
40
+ if topic not in topics():
41
+ raise LabError(
42
+ ErrorCode.NOT_FOUND,
43
+ f"No guide {topic!r}",
44
+ f"known: {', '.join(topics())}",
45
+ )
46
+ return (folder() / f"{topic}{SUFFIX}").read_text(encoding="utf-8")
47
+
48
+
49
+ def section(topic: str, heading: str) -> str:
50
+ """One section of a guide (## heading), with its heading, up to the next
51
+ one; LabError NOT_FOUND when the guide has none so named."""
52
+ lines = guide(topic).splitlines()
53
+ head = f"## {heading}"
54
+ if head not in lines:
55
+ raise LabError(ErrorCode.NOT_FOUND, f"No section {heading!r} in {topic}")
56
+ start = lines.index(head)
57
+ end = next(
58
+ (i for i in range(start + 1, len(lines)) if lines[i].startswith("## ")),
59
+ len(lines),
60
+ )
61
+ return "\n".join(lines[start:end]).strip()
thzdaq_api/host.py ADDED
@@ -0,0 +1,494 @@
1
+ """Where a client finds the daemon, and how it starts one when none runs.
2
+
3
+ A daemon writes its host file (port, token, versions) once it serves and
4
+ removes it when it ends; a lock the operating system holds keeps it the only
5
+ one. The simulator daemon is another daemon with its own files, so it runs
6
+ next to the real one. The files live in the temp folder, or in
7
+ THZDAQ_DAEMON_DIR (tests, a second bench on one machine).
8
+
9
+ A build runs its daemon as ThzDAQ.exe --serve, whichever of its programs
10
+ starts it; it notes itself in the install file of the user at each start, so
11
+ a client from PyPI without the daemon package starts that build's daemon.
12
+ """
13
+
14
+ import ctypes
15
+ import logging
16
+ import os
17
+ import signal
18
+ import subprocess
19
+ import sys
20
+ import tempfile
21
+ import time
22
+ from dataclasses import dataclass
23
+ from importlib import metadata, util
24
+ from pathlib import Path
25
+ from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
26
+
27
+ import msgspec
28
+
29
+ from thzdaq_api.atomic import file_access
30
+ from thzdaq_api.daemon import API_VERSION, HostInfo, Installation
31
+ from thzdaq_api.errors import ErrorCode, LabError
32
+ from thzdaq_api.lock import FileLock
33
+ from thzdaq_api.remote import RemoteLab, health
34
+
35
+ logger = logging.getLogger(__name__)
36
+
37
+ DIR_ENV = "THZDAQ_DAEMON_DIR"
38
+ NO_AUTOSTART_ENV = "THZDAQ_NO_AUTOSTART" # report "not running" instead of starting
39
+ START_S = 15.0 # how long a client waits for a daemon it started
40
+ LOG_KEEP = 5_000_000 # bytes of log kept before the next start moves it aside
41
+ SERVE = "--serve" # how a built program runs as the daemon
42
+ SIMULATE = "--simulate" # a program works with the simulator's daemon
43
+ PROGRAM = "ThzDAQ" # the built program: the window, and the daemon with SERVE
44
+ CLI_PROGRAM = "thzdaq-cli" # the built command line, next to it
45
+ RUN_SCRIPT = "run-script" # thzdaq-cli run-script <file>: a build's Python runs it
46
+ MODULE = "-m" # thzdaq-cli run-script -m <module>: a module run as a program
47
+ PASSED = "--" # what follows is the script's (or module's) own arguments
48
+ UNKNOWN = "unknown" # the version of a build without package metadata
49
+
50
+
51
+ @dataclass(frozen=True)
52
+ class DaemonFiles:
53
+ """The files of one daemon: the real one, or the simulator's."""
54
+
55
+ directory: Path
56
+ name: str # thzdaq, thzdaq-sim
57
+
58
+ @classmethod
59
+ def of(cls, simulate: bool = False) -> "DaemonFiles":
60
+ directory = Path(os.environ.get(DIR_ENV) or tempfile.gettempdir())
61
+ return cls(directory, "thzdaq-sim" if simulate else "thzdaq")
62
+
63
+ @property
64
+ def host(self) -> Path:
65
+ return self.directory / f"{self.name}-host.json"
66
+
67
+ @property
68
+ def lock(self) -> Path:
69
+ """Held by the living daemon: one per machine."""
70
+ return self.directory / f"{self.name}-daemon.lock"
71
+
72
+ @property
73
+ def start_lock(self) -> Path:
74
+ """Held while a client starts the daemon: two clients start one."""
75
+ return self.directory / f"{self.name}-daemon-start.lock"
76
+
77
+ @property
78
+ def log(self) -> Path:
79
+ return self.directory / f"{self.name}-daemon.log"
80
+
81
+
82
+ def frozen() -> bool:
83
+ """A built program (PyInstaller), not a run from sources."""
84
+ return bool(getattr(sys, "frozen", False))
85
+
86
+
87
+ def program_dir() -> Path:
88
+ """Folder of the program: next to the .exe when built, the working folder
89
+ from sources. The working folder of a built program depends on how it was
90
+ started (a shortcut, the updater), so files are never looked up relative
91
+ to it."""
92
+ if frozen():
93
+ return Path(sys.executable).resolve().parent
94
+ return Path.cwd()
95
+
96
+
97
+ def executable(folder: Path, name: str) -> Path:
98
+ """A built program in folder (.exe on Windows, no suffix elsewhere)."""
99
+ return folder / (name + (".exe" if sys.platform == "win32" else ""))
100
+
101
+
102
+ def program_file() -> Path:
103
+ """The built program of this installation (ThzDAQ.exe next to
104
+ thzdaq-cli.exe)."""
105
+ return executable(program_dir(), PROGRAM)
106
+
107
+
108
+ def user_dir() -> Path:
109
+ """The program's folder of the user: files it keeps between its runs."""
110
+ if sys.platform == "win32":
111
+ base = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData/Local")
112
+ elif sys.platform == "darwin":
113
+ base = Path.home() / "Library/Application Support"
114
+ else:
115
+ base = Path(os.environ.get("XDG_DATA_HOME") or Path.home() / ".local/share")
116
+ return base / PROGRAM
117
+
118
+
119
+ def install_file() -> Path:
120
+ """Where the build that started last notes itself, per user."""
121
+ return user_dir() / "install.json"
122
+
123
+
124
+ def note_installation() -> None:
125
+ """A build notes itself at each start; from sources nothing is noted."""
126
+ if not frozen():
127
+ return
128
+ path = install_file()
129
+ noted = Installation(str(program_file()), app_version())
130
+ try:
131
+ path.parent.mkdir(parents=True, exist_ok=True)
132
+ partial = path.with_suffix(".partial")
133
+ partial.write_bytes(msgspec.json.encode(noted))
134
+ os.replace(partial, path)
135
+ except OSError as e: # the build works without it: only PyPI clients need it
136
+ logger.warning(f"{path} not written: {e}")
137
+
138
+
139
+ def read_installation() -> Optional[Installation]:
140
+ try:
141
+ return msgspec.json.decode(install_file().read_bytes(), type=Installation)
142
+ except (FileNotFoundError, msgspec.DecodeError, msgspec.ValidationError):
143
+ return None
144
+
145
+
146
+ def app_version() -> str:
147
+ try:
148
+ return metadata.version("thzdaq-api")
149
+ except metadata.PackageNotFoundError: # a build without package metadata
150
+ return UNKNOWN
151
+
152
+
153
+ def read_host(files: DaemonFiles) -> Optional[HostInfo]:
154
+ """The host file, None when there is none (or it is not one)."""
155
+ if not files.directory.exists():
156
+ return None
157
+ with file_access(files.host):
158
+ return _read_host(files)
159
+
160
+
161
+ def _read_host(files: DaemonFiles) -> Optional[HostInfo]:
162
+ try:
163
+ return msgspec.json.decode(files.host.read_bytes(), type=HostInfo)
164
+ except FileNotFoundError:
165
+ return None
166
+ except (msgspec.DecodeError, msgspec.ValidationError):
167
+ logger.warning(f"{files.host} is not a host file: ignored")
168
+ return None
169
+
170
+
171
+ def write_host(files: DaemonFiles, host: HostInfo) -> None:
172
+ """Atomically: a client never reads half of it."""
173
+ files.directory.mkdir(parents=True, exist_ok=True)
174
+ with file_access(files.host):
175
+ partial = files.host.with_suffix(".partial")
176
+ partial.write_bytes(msgspec.json.encode(host))
177
+ os.replace(partial, files.host)
178
+
179
+
180
+ def remove_host(files: DaemonFiles, pid: int) -> None:
181
+ """The host file of this process goes; one another daemon wrote stays."""
182
+ if not files.directory.exists():
183
+ return
184
+ with file_access(files.host):
185
+ host = _read_host(files)
186
+ if host is not None and host.pid == pid:
187
+ files.host.unlink(missing_ok=True)
188
+
189
+
190
+ def _discard_host(files: DaemonFiles) -> None:
191
+ if not files.directory.exists():
192
+ return
193
+ with file_access(files.host):
194
+ files.host.unlink(missing_ok=True)
195
+
196
+
197
+ def pid_alive(pid: int) -> bool:
198
+ if sys.platform == "win32":
199
+ # os.kill(pid, 0) would terminate the process on Windows
200
+ synchronize, limited_query, still_active = 0x100000, 0x1000, 0x102
201
+ kernel = ctypes.windll.kernel32
202
+ handle = kernel.OpenProcess(synchronize | limited_query, False, pid)
203
+ if not handle:
204
+ return False
205
+ try:
206
+ return kernel.WaitForSingleObject(handle, 0) == still_active
207
+ finally:
208
+ kernel.CloseHandle(handle)
209
+ try:
210
+ # A daemon this client started is its child: once it ends it stays a
211
+ # zombie, which kill(pid, 0) still finds, until it is reaped here
212
+ ended, _ = os.waitpid(pid, os.WNOHANG)
213
+ return ended != pid
214
+ except ChildProcessError:
215
+ pass # not a child of this process
216
+ try:
217
+ os.kill(pid, 0)
218
+ except ProcessLookupError:
219
+ return False
220
+ except PermissionError:
221
+ return True # alive, another user's
222
+ return True
223
+
224
+
225
+ def terminate(pid: int) -> None:
226
+ """End a process at once (TerminateProcess, SIGKILL): a daemon that hangs."""
227
+ os.kill(pid, signal.SIGTERM if sys.platform == "win32" else signal.SIGKILL)
228
+
229
+
230
+ def built_or_installed(name: str, package: str, *arguments: str) -> Optional[List[str]]:
231
+ """How a program of ThzDAQ starts: the built one of this installation
232
+ (name) with arguments; else this Python with its package; else the one of
233
+ the build the install file names. None when there is none of them."""
234
+ if frozen():
235
+ return [str(executable(program_dir(), name)), *arguments]
236
+ if util.find_spec(package) is not None:
237
+ return [sys.executable, "-m", package]
238
+ installed = read_installation()
239
+ if installed is not None and Path(installed.program).exists():
240
+ return [str(executable(Path(installed.program).parent, name)), *arguments]
241
+ return None
242
+
243
+
244
+ def start_command() -> List[str]:
245
+ """How the daemon starts: the built program with --serve, or the daemon
246
+ package. LabError when there is neither."""
247
+ found = built_or_installed(PROGRAM, "thzdaq_daemon", SERVE)
248
+ if found is None:
249
+ raise LabError(
250
+ ErrorCode.UNREACHABLE,
251
+ "No daemon runs and none can be started here",
252
+ "install thzdaq[daemon], or start the ThzDAQ build once",
253
+ )
254
+ return found
255
+
256
+
257
+ def window_command() -> List[str]:
258
+ """How the window starts: the built program, or the GUI package. LabError
259
+ when there is neither."""
260
+ found = built_or_installed(PROGRAM, "thzdaq_gui")
261
+ if found is None:
262
+ raise LabError(
263
+ ErrorCode.NOT_FOUND,
264
+ "No ThzDAQ window is installed here",
265
+ "install thzdaq[gui], or start the ThzDAQ build once",
266
+ )
267
+ return found
268
+
269
+
270
+ def cli_command() -> List[str]:
271
+ """How the command line starts from another program (the window): the
272
+ built thzdaq-cli, or the CLI package. LabError when there is neither."""
273
+ found = built_or_installed(CLI_PROGRAM, "thzdaq_cli")
274
+ if found is None:
275
+ raise LabError(
276
+ ErrorCode.NOT_FOUND,
277
+ "No thzdaq command is installed here",
278
+ "install thzdaq, or start the ThzDAQ build once",
279
+ )
280
+ return found
281
+
282
+
283
+ def script_python() -> Tuple[str, ...]:
284
+ """How a script runs with this program's Python (thzdaq script start, Run
285
+ in a window): this interpreter from sources; a build has none but its own,
286
+ through thzdaq-cli run-script, a console program whose print and
287
+ tracebacks reach the script's log."""
288
+ if frozen():
289
+ return (str(executable(program_dir(), CLI_PROGRAM)), RUN_SCRIPT)
290
+ return (sys.executable,)
291
+
292
+
293
+ def python_module(module: str, *arguments: str) -> List[str]:
294
+ """How a module runs as a program with the scripts' Python (python -m
295
+ module arguments): this interpreter from sources, a build's own."""
296
+ if frozen():
297
+ return built_module(executable(program_dir(), CLI_PROGRAM), module, *arguments)
298
+ return [sys.executable, "-m", module, *arguments]
299
+
300
+
301
+ def built_module(cli: Path, module: str, *arguments: str) -> List[str]:
302
+ """How a build's thzdaq-cli runs a module as a program: run-script -m,
303
+ the arguments after --."""
304
+ return [str(cli), RUN_SCRIPT, MODULE, module, PASSED, *arguments]
305
+
306
+
307
+ def apart() -> Dict[str, Any]:
308
+ """Popen options that start a process apart from this one: without its
309
+ console or terminal session, so it outlives them."""
310
+ if sys.platform == "win32":
311
+ return dict(
312
+ creationflags=subprocess.CREATE_NEW_PROCESS_GROUP
313
+ | subprocess.DETACHED_PROCESS
314
+ | subprocess.CREATE_NO_WINDOW
315
+ )
316
+ return dict(start_new_session=True)
317
+
318
+
319
+ def windowless() -> Dict[str, Any]:
320
+ """Popen options that start a console program without a window of its own
321
+ on Windows (a console's kernel, thzdaq-cli of a build, started by the
322
+ window)."""
323
+ if sys.platform == "win32":
324
+ return dict(creationflags=subprocess.CREATE_NO_WINDOW)
325
+ return {}
326
+
327
+
328
+ def start_apart(command: Sequence[str]) -> subprocess.Popen:
329
+ """Start a program apart from this process, without its output: it
330
+ outlives this one (a window, an editor)."""
331
+ return subprocess.Popen(
332
+ list(command),
333
+ stdin=subprocess.DEVNULL,
334
+ stdout=subprocess.DEVNULL,
335
+ stderr=subprocess.DEVNULL,
336
+ close_fds=True,
337
+ **apart(),
338
+ )
339
+
340
+
341
+ def spawn(command: Sequence[str], files: DaemonFiles) -> subprocess.Popen:
342
+ """Start the daemon apart from this process (it outlives the client); its
343
+ output goes to its log."""
344
+ files.directory.mkdir(parents=True, exist_ok=True)
345
+ if files.log.exists() and files.log.stat().st_size > LOG_KEEP:
346
+ os.replace(files.log, files.log.with_suffix(".log.1"))
347
+ with open(files.log, "ab") as log:
348
+ return subprocess.Popen(
349
+ list(command),
350
+ stdin=subprocess.DEVNULL,
351
+ stdout=log,
352
+ stderr=subprocess.STDOUT,
353
+ close_fds=True,
354
+ **apart(),
355
+ )
356
+
357
+
358
+ def log_tail(files: DaemonFiles, lines: int = 20) -> str:
359
+ try:
360
+ text = files.log.read_text(encoding="utf-8", errors="replace")
361
+ except FileNotFoundError:
362
+ return ""
363
+ return "\n".join(text.splitlines()[-lines:])
364
+
365
+
366
+ def connect(
367
+ simulate: bool = False,
368
+ origin: str = "client",
369
+ kind: str = "client",
370
+ window: str = "",
371
+ ) -> RemoteLab:
372
+ """The running daemon; LabError UNREACHABLE when none answers, WRONG_VERSION
373
+ when it speaks another contract. window: the id of the main window the
374
+ client is (RemoteLab)."""
375
+ files = DaemonFiles.of(simulate)
376
+ host = read_host(files)
377
+ if host is None:
378
+ raise LabError(
379
+ ErrorCode.UNREACHABLE,
380
+ f"No {'simulator ' if simulate else ''}daemon runs",
381
+ "connect_or_start() starts it",
382
+ )
383
+ answer = health(host)
384
+ if answer is None:
385
+ raise LabError(
386
+ ErrorCode.UNREACHABLE,
387
+ f"The daemon (pid {host.pid}, port {host.port}) does not answer",
388
+ "it may hang: kill() ends it",
389
+ )
390
+ if answer.api_version != API_VERSION:
391
+ raise LabError(
392
+ ErrorCode.WRONG_VERSION,
393
+ f"The daemon (pid {host.pid}, {answer.app_version}) speaks contract "
394
+ f"{answer.api_version}, this client {API_VERSION}",
395
+ "restart it with this installation when no measurement runs",
396
+ )
397
+ return RemoteLab(host, origin, kind, lambda: read_host(files), window)
398
+
399
+
400
+ def connect_or_start(
401
+ simulate: bool = False,
402
+ station: Optional[str] = None,
403
+ origin: str = "client",
404
+ kind: str = "client",
405
+ command: Optional[Sequence[str]] = None,
406
+ timeout: float = START_S,
407
+ window: str = "",
408
+ ) -> RemoteLab:
409
+ """The running daemon, started first when none runs. Two clients starting
410
+ at once start one daemon: the second finds the first one's. window: the
411
+ id of the main window the client is (RemoteLab)."""
412
+
413
+ def reach() -> RemoteLab:
414
+ return connect(simulate, origin, kind, window)
415
+
416
+ try:
417
+ return reach()
418
+ except LabError as e:
419
+ if e.code != ErrorCode.UNREACHABLE or os.environ.get(NO_AUTOSTART_ENV):
420
+ raise
421
+ files = DaemonFiles.of(simulate)
422
+ starting = FileLock(files.start_lock)
423
+ if not starting.acquire(timeout):
424
+ raise LabError(
425
+ ErrorCode.UNREACHABLE,
426
+ "Another client is starting the daemon and it did not come up",
427
+ log_tail(files),
428
+ )
429
+ try:
430
+ try:
431
+ return reach() # another client started it
432
+ except LabError as e:
433
+ if e.code != ErrorCode.UNREACHABLE:
434
+ raise
435
+ host = read_host(files)
436
+ if host is not None and pid_alive(host.pid):
437
+ raise LabError(
438
+ ErrorCode.UNREACHABLE,
439
+ f"The daemon (pid {host.pid}) runs but does not answer",
440
+ "kill() ends it",
441
+ )
442
+ _discard_host(files) # left by a daemon that died
443
+ arguments = list(command or start_command())
444
+ if station:
445
+ arguments += ["--station", str(station)]
446
+ if simulate:
447
+ arguments.append(SIMULATE)
448
+ process = spawn(arguments, files)
449
+ lab = _wait_for_start(files, process, reach, timeout)
450
+ logger.info(f"daemon started (pid {lab.host.pid})")
451
+ return lab
452
+ finally:
453
+ starting.release()
454
+
455
+
456
+ def _wait_for_start(
457
+ files: DaemonFiles,
458
+ process: subprocess.Popen,
459
+ reach: Callable[[], RemoteLab],
460
+ timeout: float,
461
+ ) -> RemoteLab:
462
+ deadline = time.monotonic() + timeout
463
+ while time.monotonic() < deadline:
464
+ if process.poll() is not None:
465
+ raise LabError(
466
+ ErrorCode.UNREACHABLE,
467
+ f"The daemon exited at start (code {process.returncode})",
468
+ log_tail(files),
469
+ )
470
+ if read_host(files) is not None:
471
+ try:
472
+ return reach()
473
+ except LabError as e:
474
+ if e.code != ErrorCode.UNREACHABLE:
475
+ raise
476
+ time.sleep(0.1) # the daemon is another process: look again
477
+ raise LabError(
478
+ ErrorCode.UNREACHABLE,
479
+ f"The daemon did not start in {timeout:g} s",
480
+ log_tail(files),
481
+ )
482
+
483
+
484
+ def kill(simulate: bool = False) -> Optional[int]:
485
+ """End a daemon that does not answer; its pid, None when none ran.
486
+ Measurement files it left running read as interrupted."""
487
+ files = DaemonFiles.of(simulate)
488
+ host = read_host(files)
489
+ if host is None or not pid_alive(host.pid):
490
+ _discard_host(files)
491
+ return None
492
+ terminate(host.pid)
493
+ remove_host(files, host.pid)
494
+ return host.pid