thzdaq-api 0.0.6b3__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- thzdaq_api/__init__.py +1 -0
- thzdaq_api/analysis.py +62 -0
- thzdaq_api/approvals.py +87 -0
- thzdaq_api/assistant/agents.md +202 -0
- thzdaq_api/assistant/assistant.md +23 -0
- thzdaq_api/assistant/hints.md +15 -0
- thzdaq_api/atomic.py +79 -0
- thzdaq_api/catalog.py +131 -0
- thzdaq_api/console.py +70 -0
- thzdaq_api/custom.py +326 -0
- thzdaq_api/daemon.py +183 -0
- thzdaq_api/data.py +55 -0
- thzdaq_api/declare.py +193 -0
- thzdaq_api/declaring.py +125 -0
- thzdaq_api/devices.py +307 -0
- thzdaq_api/errors.py +47 -0
- thzdaq_api/events.py +224 -0
- thzdaq_api/examples/hot_cold.py +67 -0
- thzdaq_api/examples/hot_cold_grid.py +74 -0
- thzdaq_api/examples/iv_analysis.py +34 -0
- thzdaq_api/examples/map.py +42 -0
- thzdaq_api/examples/monitor.py +35 -0
- thzdaq_api/examples/raw_instrument.py +37 -0
- thzdaq_api/examples/sweep.py +38 -0
- thzdaq_api/examples.py +79 -0
- thzdaq_api/guides.py +61 -0
- thzdaq_api/host.py +494 -0
- thzdaq_api/interpreters.py +422 -0
- thzdaq_api/kernel.py +137 -0
- thzdaq_api/lab.py +562 -0
- thzdaq_api/lanes.py +170 -0
- thzdaq_api/leases.py +29 -0
- thzdaq_api/lock.py +65 -0
- thzdaq_api/measurement_file.py +459 -0
- thzdaq_api/measurements.py +433 -0
- thzdaq_api/operation.py +52 -0
- thzdaq_api/origins.py +86 -0
- thzdaq_api/present.py +376 -0
- thzdaq_api/procedures.py +124 -0
- thzdaq_api/raw.py +272 -0
- thzdaq_api/remote.py +267 -0
- thzdaq_api/rights.py +81 -0
- thzdaq_api/script.py +382 -0
- thzdaq_api/scripts.py +133 -0
- thzdaq_api/sessions.py +176 -0
- thzdaq_api/station.py +192 -0
- thzdaq_api/terminal.py +66 -0
- thzdaq_api/tools.py +275 -0
- thzdaq_api/transport.py +93 -0
- thzdaq_api/ui.py +152 -0
- thzdaq_api/windows.py +192 -0
- thzdaq_api/wire.py +35 -0
- thzdaq_api/workspace.py +239 -0
- thzdaq_api-0.0.6b3.dist-info/METADATA +30 -0
- thzdaq_api-0.0.6b3.dist-info/RECORD +57 -0
- thzdaq_api-0.0.6b3.dist-info/WHEEL +4 -0
- thzdaq_api-0.0.6b3.dist-info/licenses/LICENSE +21 -0
thzdaq_api/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
|