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/lanes.py ADDED
@@ -0,0 +1,170 @@
1
+ """Lanes: one thread and queue per key, an instrument in the daemon.
2
+
3
+ The jobs of one instrument run in order in its lane; instruments do not wait
4
+ for each other, so a slow or hung power meter does not hold the SIS bias.
5
+ Instruments sharing a connection (a Prologix) still take turns on its lock. A
6
+ client calls the daemon in lanes too: the calls about one device in order,
7
+ none waiting for a device that hangs.
8
+ """
9
+
10
+ import logging
11
+ import queue
12
+ import threading
13
+ import time
14
+ from typing import Any, Callable, Dict, List, Optional, Tuple
15
+
16
+ logger = logging.getLogger(__name__)
17
+
18
+ # Called with (result, error) in the lane's thread when a job ends
19
+ Deliver = Callable[[Any, Optional[BaseException]], None]
20
+
21
+
22
+ class LaneReset(Exception):
23
+ """A job that waited in a lane given up by reset()."""
24
+
25
+
26
+ class _Lane:
27
+ def __init__(self, key: str):
28
+ self.queue: "queue.Queue" = queue.Queue()
29
+ self.started: Optional[float] = None
30
+ self.label: Optional[str] = None
31
+ name = f"lane {key}" if key else "lane"
32
+ self.thread = threading.Thread(target=self.loop, name=name, daemon=True)
33
+ self.thread.start()
34
+
35
+ def loop(self) -> None:
36
+ while True:
37
+ item = self.queue.get()
38
+ if item is None:
39
+ return
40
+ job, deliver, label = item
41
+ self.label = label
42
+ self.started = time.monotonic()
43
+ try:
44
+ result = job()
45
+ except Exception as e:
46
+ logger.exception(f"Device job failed{f' ({label})' if label else ''}")
47
+ deliver(None, e)
48
+ else:
49
+ deliver(result, None)
50
+ finally:
51
+ self.started = None
52
+ self.label = None
53
+ # What deliver holds (GUI callbacks hold widgets) must not die here:
54
+ # its last reference stays with whoever deliver handed it to
55
+ del item, job, deliver
56
+ result = None
57
+
58
+ def abandon(self, key: str) -> None:
59
+ """Fail the jobs that wait; the one running ends here when it can."""
60
+ while True:
61
+ try:
62
+ item = self.queue.get_nowait()
63
+ except queue.Empty:
64
+ break
65
+ if item is not None:
66
+ _, deliver, _ = item
67
+ deliver(None, LaneReset(f"the queue of {key} was reset"))
68
+ self.queue.put(None) # the thread ends after the job it runs
69
+
70
+
71
+ class Lanes:
72
+ def __init__(self):
73
+ self._lanes: Dict[str, _Lane] = {}
74
+ self._lock = threading.Lock()
75
+ self._lane("") # jobs without an instrument
76
+
77
+ def _lane(self, key: str) -> _Lane:
78
+ with self._lock:
79
+ lane = self._lanes.get(key)
80
+ if lane is None:
81
+ lane = self._lanes[key] = _Lane(key)
82
+ return lane
83
+
84
+ def submit(
85
+ self,
86
+ key: str,
87
+ job: Callable[[], Any],
88
+ deliver: Deliver,
89
+ label: Optional[str] = None,
90
+ ) -> None:
91
+ """key: the instrument whose lane the job joins; label: the device it
92
+ talks to, named when it does not answer."""
93
+ self._lane(key).queue.put((job, deliver, label))
94
+
95
+ def call(
96
+ self, key: str, job: Callable[[], Any], label: Optional[str] = None
97
+ ) -> Any:
98
+ """Run the job in its lane and wait for it; its error is raised here."""
99
+ done = threading.Event()
100
+ outcome: list = []
101
+
102
+ def deliver(result, error):
103
+ outcome.append((result, error))
104
+ done.set()
105
+
106
+ self.submit(key, job, deliver, label)
107
+ done.wait()
108
+ result, error = outcome[0]
109
+ if error is not None:
110
+ raise error
111
+ return result
112
+
113
+ def reset(self, key: str) -> bool:
114
+ """A new lane for key: the old one, held by a job that hangs, is given
115
+ up. Returns whether key had a lane."""
116
+ with self._lock:
117
+ old = self._lanes.pop(key, None)
118
+ if old is None:
119
+ return False
120
+ old.abandon(key)
121
+ return True
122
+
123
+ def status(self) -> List[Tuple[str, int, Optional[str], float]]:
124
+ """Each instrument's lane: (instrument, jobs waiting, the device the
125
+ running job talks to, seconds it has run)."""
126
+ now = time.monotonic()
127
+ found = []
128
+ for key, lane in list(self._lanes.items()):
129
+ if not key:
130
+ continue # jobs of no instrument
131
+ started, label = lane.started, lane.label # the lane changes meanwhile
132
+ busy = 0.0 if started is None else now - started
133
+ found.append((key, lane.queue.qsize(), label, busy))
134
+ return found
135
+
136
+ @property
137
+ def pending(self) -> int:
138
+ return sum(lane.queue.qsize() for lane in list(self._lanes.values()))
139
+
140
+ def _slowest(self) -> Tuple[Optional[float], Optional[str]]:
141
+ """(start, label) of the longest job in progress; lanes change meanwhile."""
142
+ busy = []
143
+ for lane in list(self._lanes.values()):
144
+ started, label = lane.started, lane.label
145
+ if started is not None:
146
+ busy.append((started, label))
147
+ return min(busy, key=lambda item: item[0], default=(None, None))
148
+
149
+ def busy_for(self) -> float:
150
+ """Seconds the longest job in progress has been running (0 when idle)."""
151
+ started, _ = self._slowest()
152
+ return 0.0 if started is None else time.monotonic() - started
153
+
154
+ @property
155
+ def current(self) -> Optional[str]:
156
+ """Label of the longest job in progress."""
157
+ return self._slowest()[1]
158
+
159
+ @property
160
+ def started_at(self) -> Optional[float]:
161
+ """When the longest job in progress started (monotonic), None when idle."""
162
+ return self._slowest()[0]
163
+
164
+ def stop(self, timeout: float = 2.0) -> None:
165
+ lanes = list(self._lanes.values())
166
+ for lane in lanes:
167
+ lane.queue.put(None)
168
+ deadline = time.monotonic() + timeout
169
+ for lane in lanes:
170
+ lane.thread.join(max(0.0, deadline - time.monotonic()))
thzdaq_api/leases.py ADDED
@@ -0,0 +1,29 @@
1
+ """Who uses a device now and how: the leases of running measurements.
2
+
3
+ read: only reads it; shared: sets it, others may too (a load, the LO);
4
+ exclusive: sweeps it, so another's change spoils its data. Only exclusive use
5
+ conflicts, and an explicit intent (share) goes on anyway; both measurements
6
+ record it.
7
+ """
8
+
9
+ from typing import Tuple
10
+
11
+ import msgspec
12
+
13
+ from thzdaq_api.operation import Operation
14
+
15
+ READ = "read"
16
+ SHARED = "shared"
17
+ EXCLUSIVE = "exclusive"
18
+
19
+
20
+ class LeaseInfo(msgspec.Struct, frozen=True):
21
+ device: str
22
+ mode: str # read, shared or exclusive
23
+ run: int # the measurement using it
24
+ title: str # of that measurement
25
+
26
+
27
+ class ListLeases(Operation[Tuple[LeaseInfo, ...]]):
28
+ """Devices in use by running measurements and how: read (only reads),
29
+ shared (sets it, others may too) or exclusive (sweeps it)."""
thzdaq_api/lock.py ADDED
@@ -0,0 +1,65 @@
1
+ """A lock the operating system holds for a process on a file: it goes when the
2
+ process ends, however it ends, so a crashed daemon leaves no stale lock."""
3
+
4
+ import sys
5
+ import time
6
+ from pathlib import Path
7
+ from typing import IO, Optional
8
+
9
+ # Taking a lock held by another process is retried this often until the timeout:
10
+ # the operating systems offer no timed wait on a file lock
11
+ RETRY_S = 0.05
12
+
13
+
14
+ class FileLock:
15
+ def __init__(self, path: Path):
16
+ self.path = Path(path)
17
+ self._file: Optional[IO] = None
18
+
19
+ def acquire(self, timeout: float = 0.0) -> bool:
20
+ """Take the lock, waiting up to timeout seconds; False if another holds it."""
21
+ self.path.parent.mkdir(parents=True, exist_ok=True)
22
+ file = open(self.path, "a+b")
23
+ deadline = time.monotonic() + timeout
24
+ while True:
25
+ try:
26
+ _lock(file)
27
+ except OSError:
28
+ if time.monotonic() >= deadline:
29
+ file.close()
30
+ return False
31
+ time.sleep(RETRY_S)
32
+ else:
33
+ self._file = file
34
+ return True
35
+
36
+ def release(self) -> None:
37
+ if self._file is not None:
38
+ _unlock(self._file)
39
+ self._file.close()
40
+ self._file = None
41
+
42
+ @property
43
+ def held(self) -> bool:
44
+ return self._file is not None
45
+
46
+
47
+ if sys.platform == "win32":
48
+ import msvcrt
49
+
50
+ def _lock(file: IO) -> None:
51
+ file.seek(0)
52
+ msvcrt.locking(file.fileno(), msvcrt.LK_NBLCK, 1)
53
+
54
+ def _unlock(file: IO) -> None:
55
+ file.seek(0)
56
+ msvcrt.locking(file.fileno(), msvcrt.LK_UNLCK, 1)
57
+
58
+ else:
59
+ import fcntl
60
+
61
+ def _lock(file: IO) -> None:
62
+ fcntl.flock(file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
63
+
64
+ def _unlock(file: IO) -> None:
65
+ fcntl.flock(file.fileno(), fcntl.LOCK_UN)