ultrazohm-cli 0.1.1.dev0__cp310-abi3-win_amd64.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.
- ultrazohm_cli/__init__.py +222 -0
- ultrazohm_cli/__main__.py +4 -0
- ultrazohm_cli/_native.pyd +0 -0
- ultrazohm_cli/cli.py +8 -0
- ultrazohm_cli-0.1.1.dev0.dist-info/METADATA +10 -0
- ultrazohm_cli-0.1.1.dev0.dist-info/RECORD +9 -0
- ultrazohm_cli-0.1.1.dev0.dist-info/WHEEL +4 -0
- ultrazohm_cli-0.1.1.dev0.dist-info/entry_points.txt +2 -0
- ultrazohm_cli-0.1.1.dev0.dist-info/sboms/ultrazohm_cli.cyclonedx.json +13684 -0
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
"""Named API v2; all device IO and logging execute in Rust.
|
|
2
|
+
|
|
3
|
+
Service errors raise RuntimeError with a ``code`` attribute (for example
|
|
4
|
+
``cursor_expired``, ``canceled_by_stop``, ``not_connected``, ``busy``).
|
|
5
|
+
"""
|
|
6
|
+
import atexit
|
|
7
|
+
import json
|
|
8
|
+
import sys
|
|
9
|
+
import weakref
|
|
10
|
+
from dataclasses import dataclass
|
|
11
|
+
from io import BytesIO
|
|
12
|
+
from ._native import (Connection as _Connection, Acquisition as _Acquisition,
|
|
13
|
+
recording_info as _recording_info, recording_data as _recording_data,
|
|
14
|
+
console_command as _console_command)
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def _position(value, name, *, positive=False):
|
|
18
|
+
if isinstance(value, bool) or not isinstance(value, int) or value < (1 if positive else 0):
|
|
19
|
+
raise ValueError(f"{name} must be a {'positive' if positive else 'non-negative'} integer")
|
|
20
|
+
return value
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def _source(stream, recording):
|
|
24
|
+
if stream not in ("fast", "slow"):
|
|
25
|
+
raise ValueError("stream must be fast or slow")
|
|
26
|
+
if recording is not None:
|
|
27
|
+
_position(recording, "recording", positive=True)
|
|
28
|
+
return {"stream": stream, "recording": recording}
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
@dataclass(frozen=True)
|
|
32
|
+
class DataPage:
|
|
33
|
+
"""Rows and an opaque cursor describing the next unread sample."""
|
|
34
|
+
data: object
|
|
35
|
+
cursor: dict
|
|
36
|
+
start: int
|
|
37
|
+
stop: int
|
|
38
|
+
info: dict
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class Recording:
|
|
42
|
+
"""A durable backend handle; usable without a running acquisition service.
|
|
43
|
+
|
|
44
|
+
Live pending samples are accessed through Client. This handle reads published
|
|
45
|
+
batches. Slow recordings expose raw updates; legacy exports are wide tables.
|
|
46
|
+
"""
|
|
47
|
+
def __init__(self, path):
|
|
48
|
+
from pathlib import Path
|
|
49
|
+
self.path = str(Path(path).resolve())
|
|
50
|
+
self.info() # Validate backend/version at open.
|
|
51
|
+
|
|
52
|
+
def info(self):
|
|
53
|
+
return json.loads(_recording_info(self.path))
|
|
54
|
+
|
|
55
|
+
def read_range(self, start, stop, *, channels=None):
|
|
56
|
+
import polars as pl
|
|
57
|
+
_position(start, "start")
|
|
58
|
+
_position(stop, "stop")
|
|
59
|
+
return pl.read_ipc_stream(BytesIO(_recording_data(self.path, start, stop, channels)))
|
|
60
|
+
|
|
61
|
+
def iter_batches(self, batch_samples=10_000, *, channels=None):
|
|
62
|
+
_position(batch_samples, "batch_samples", positive=True)
|
|
63
|
+
info = self.info()
|
|
64
|
+
start, stop = info["start"] or 0, info["stop"] or 0
|
|
65
|
+
for first in range(start, stop, batch_samples):
|
|
66
|
+
yield self.read_range(first, min(first + batch_samples, stop), channels=channels)
|
|
67
|
+
|
|
68
|
+
def read(self, *, channels=None):
|
|
69
|
+
import polars as pl
|
|
70
|
+
# Several stored row groups per request; well within the response limit.
|
|
71
|
+
batches = list(self.iter_batches(262_144, channels=channels))
|
|
72
|
+
return pl.concat(batches) if batches else self.read_range(0, 0, channels=channels)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def _close_at_exit(reference):
|
|
76
|
+
acquisition = reference()
|
|
77
|
+
if acquisition is not None and not acquisition.is_finished():
|
|
78
|
+
try:
|
|
79
|
+
acquisition.close()
|
|
80
|
+
except Exception as error: # noqa: BLE001 - interpreter exit cannot raise
|
|
81
|
+
print(f"UltraZohm acquisition closed with an error: {error}", file=sys.stderr)
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
class Acquisition(_Acquisition):
|
|
85
|
+
"""Own an embedded acquisition; close it before reading finalized recordings.
|
|
86
|
+
|
|
87
|
+
Prefer ``with Acquisition(...) as acquisition:``. An acquisition that is
|
|
88
|
+
never closed is closed when it is garbage collected or the interpreter
|
|
89
|
+
exits, which also sends device Stop and finalizes its recordings.
|
|
90
|
+
"""
|
|
91
|
+
|
|
92
|
+
def __init__(self, *args, **kwargs):
|
|
93
|
+
# The native constructor starts the service; only register its cleanup here.
|
|
94
|
+
atexit.register(_close_at_exit, weakref.ref(self))
|
|
95
|
+
|
|
96
|
+
def __enter__(self):
|
|
97
|
+
return self
|
|
98
|
+
|
|
99
|
+
def __exit__(self, *exc_info):
|
|
100
|
+
self.close()
|
|
101
|
+
return False
|
|
102
|
+
|
|
103
|
+
def read_recording(self, stream="fast", recording=1):
|
|
104
|
+
"""Return a completed recording as a Polars DataFrame after close()."""
|
|
105
|
+
return self.recording(stream, recording).read()
|
|
106
|
+
|
|
107
|
+
def recording(self, stream="fast", recording=1):
|
|
108
|
+
"""Get this acquisition's durable recording handle without repeating a path."""
|
|
109
|
+
_source(stream, recording)
|
|
110
|
+
return Recording(self.recording_handle_path(stream, recording))
|
|
111
|
+
|
|
112
|
+
class Client:
|
|
113
|
+
"""Control an existing external or embedded acquisition service.
|
|
114
|
+
|
|
115
|
+
One persistent connection carries all requests of this client in order. A
|
|
116
|
+
Client may be shared between threads; calls are serialized. Use separate
|
|
117
|
+
Clients when a command (such as Stop) must not wait behind a long read.
|
|
118
|
+
"""
|
|
119
|
+
def __init__(self, endpoint="127.0.0.1:19740"):
|
|
120
|
+
self.endpoint = endpoint
|
|
121
|
+
self._connection = _Connection(endpoint)
|
|
122
|
+
|
|
123
|
+
def close(self):
|
|
124
|
+
"""Close the connection; a later call reconnects."""
|
|
125
|
+
self._connection.close()
|
|
126
|
+
|
|
127
|
+
def _call(self, op, **fields):
|
|
128
|
+
return json.loads(self._connection.request(json.dumps({"op": op, **fields}, allow_nan=False)))
|
|
129
|
+
|
|
130
|
+
def connect(self, ip="192.168.1.233", port=1000):
|
|
131
|
+
"""Connect an offline service and apply its initial observables."""
|
|
132
|
+
return self._call("connect", ip=ip, port=port)
|
|
133
|
+
|
|
134
|
+
def start_logging(self, stream="fast"): return self._call("start_logging", stream=stream)
|
|
135
|
+
def stop_logging(self, stream="fast"): return self._call("stop_logging", stream=stream)
|
|
136
|
+
def pause_logging(self, stream="fast"):
|
|
137
|
+
"""Suspend a recording; keep acquisition/RAM and the recording open."""
|
|
138
|
+
return self._call("pause_logging", stream=stream)
|
|
139
|
+
def resume_logging(self, stream="fast"):
|
|
140
|
+
"""Resume the same recording; timestamps retain the pause gap."""
|
|
141
|
+
return self._call("resume_logging", stream=stream)
|
|
142
|
+
def start_logging_slow_data(self): return self.start_logging("slow")
|
|
143
|
+
def stop_logging_slow_data(self): return self.stop_logging("slow")
|
|
144
|
+
def pause_logging_slow_data(self): return self.pause_logging("slow")
|
|
145
|
+
def resume_logging_slow_data(self): return self.resume_logging("slow")
|
|
146
|
+
def observables(self):
|
|
147
|
+
"""Return all channel assignments requested in this session; no device readback."""
|
|
148
|
+
return self._call("observables")
|
|
149
|
+
def catalog(self):
|
|
150
|
+
"""Return the service's firmware mapping and runtime profile, not device readback."""
|
|
151
|
+
return self._call("catalog")
|
|
152
|
+
def recordings(self):
|
|
153
|
+
return self._call("recordings")["recordings"]
|
|
154
|
+
|
|
155
|
+
def data_info(self, *, stream="fast", recording=None):
|
|
156
|
+
"""Available sample positions; stop is exclusive. See position_basis for live vs recorded rows."""
|
|
157
|
+
return self._call("data_info", source=_source(stream, recording))["info"]
|
|
158
|
+
|
|
159
|
+
def _read(self, selection, *, stream, recording, channels):
|
|
160
|
+
import polars as pl
|
|
161
|
+
command = {"op": "read_data", "query": {"source": _source(stream, recording),
|
|
162
|
+
"selection": selection, "channels": channels}}
|
|
163
|
+
header, payload = self._connection.data_query(json.dumps(command, allow_nan=False))
|
|
164
|
+
metadata = json.loads(header)
|
|
165
|
+
return DataPage(pl.read_ipc_stream(BytesIO(payload)), metadata["cursor"],
|
|
166
|
+
metadata["start"], metadata["stop"], metadata["info"])
|
|
167
|
+
|
|
168
|
+
def tail(self, n, *, stream="fast", recording=None, channels=None):
|
|
169
|
+
_position(n, "n", positive=True)
|
|
170
|
+
return self._read({"kind": "tail", "count": n}, stream=stream,
|
|
171
|
+
recording=recording, channels=channels).data
|
|
172
|
+
|
|
173
|
+
def read_range(self, start, stop, *, stream="fast", recording=None, channels=None):
|
|
174
|
+
_position(start, "start")
|
|
175
|
+
_position(stop, "stop")
|
|
176
|
+
return self._read({"kind": "range", "start": start, "stop": stop}, stream=stream,
|
|
177
|
+
recording=recording, channels=channels).data
|
|
178
|
+
|
|
179
|
+
def read_since(self, cursor=None, *, limit=10_000, stream=None, recording=None, channels=None):
|
|
180
|
+
"""Read a bounded page. Reuse page.cursor to resume without overlap.
|
|
181
|
+
|
|
182
|
+
With no cursor, starts at the earliest currently available sample. Expired
|
|
183
|
+
RAM cursors and cursors from another run or signal mapping raise an error.
|
|
184
|
+
"""
|
|
185
|
+
_position(limit, "limit", positive=True)
|
|
186
|
+
if cursor is not None:
|
|
187
|
+
if not isinstance(cursor, dict):
|
|
188
|
+
raise ValueError("cursor must be the dict returned by read_since")
|
|
189
|
+
stream = stream or cursor.get("stream")
|
|
190
|
+
if recording is None:
|
|
191
|
+
recording = cursor.get("recording")
|
|
192
|
+
return self._read({"kind": "since", "cursor": cursor, "limit": limit},
|
|
193
|
+
stream=stream or "fast", recording=recording, channels=channels)
|
|
194
|
+
def status(self):
|
|
195
|
+
"""Return service status; state.platform_state is the mapped name or None."""
|
|
196
|
+
return self._call("status")
|
|
197
|
+
def stop(self): return self._call("stop")
|
|
198
|
+
def enable_system(self): return self._call("enable_system")
|
|
199
|
+
def enable_control(self): return self._call("enable_control")
|
|
200
|
+
def error_reset(self):
|
|
201
|
+
raise RuntimeError("Error_Reset is a no-op in this firmware; use stop to leave error state")
|
|
202
|
+
def set_variable(self, name, value): return self._call("set_variable", name=name, value=value)
|
|
203
|
+
def set_observable(self, name, channel): return self._call("set_observable", name=name, channel=channel)
|
|
204
|
+
def button(self, number): return self._call("button", number=number)
|
|
205
|
+
def send_ack(self, enabled):
|
|
206
|
+
if not isinstance(enabled, bool):
|
|
207
|
+
raise TypeError("enabled must be bool")
|
|
208
|
+
return self._call("send_ack", enabled=enabled)
|
|
209
|
+
def shutdown(self): return self._call("shutdown")
|
|
210
|
+
|
|
211
|
+
def console_command(line, endpoint="127.0.0.1:19740"):
|
|
212
|
+
"""Run one command in the interactive prompt's syntax against a running service.
|
|
213
|
+
|
|
214
|
+
For example ``console_command("status")`` or ``console_command("set-variable
|
|
215
|
+
send_field_1 2.5")``. Returns the text the CLI would print. Only service
|
|
216
|
+
commands are accepted; local tools (serve, build, flash, generate) raise.
|
|
217
|
+
Help (``--help`` or an empty line) is returned as text.
|
|
218
|
+
"""
|
|
219
|
+
return _console_command(endpoint, line)
|
|
220
|
+
|
|
221
|
+
|
|
222
|
+
__all__ = ["Client", "Acquisition", "Recording", "DataPage", "console_command"]
|
|
Binary file
|
ultrazohm_cli/cli.py
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ultrazohm_cli
|
|
3
|
+
Version: 0.1.1.dev0
|
|
4
|
+
Requires-Dist: polars>=1
|
|
5
|
+
Requires-Dist: polars ; extra == 'examples'
|
|
6
|
+
Requires-Dist: matplotlib ; extra == 'examples'
|
|
7
|
+
Provides-Extra: examples
|
|
8
|
+
Summary: Rust-powered UltraZohm acquisition and control
|
|
9
|
+
License-Expression: Apache-2.0
|
|
10
|
+
Requires-Python: >=3.10
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
ultrazohm_cli/__init__.py,sha256=iWLLGzQLk-AgCgT4RN95q4LsHIlRGFIwEcGw8blJwmU,10278
|
|
2
|
+
ultrazohm_cli/__main__.py,sha256=N5z5SOCgNrPN9R2fgoaePI6AtjmVjF5T8iqpe-Frq7Y,132
|
|
3
|
+
ultrazohm_cli/_native.pyd,sha256=NzV2-iSx8JCs65NXkJ8AtE0Z-dx5Z6K9EHpMCA26Wbo,28220416
|
|
4
|
+
ultrazohm_cli/cli.py,sha256=_HchFYRxg8LH1nbtdkdE8_lT4ojPGQQg7ng5vwjQsdY,171
|
|
5
|
+
ultrazohm_cli-0.1.1.dev0.dist-info/METADATA,sha256=MfO7J7XI__0NVShYdY85FCzCxIP7iIDGa0apnchMPSs,315
|
|
6
|
+
ultrazohm_cli-0.1.1.dev0.dist-info/WHEEL,sha256=TzjyIyBUptJHnlQyOymQYLWjtXe7MGI0m3QvmcG7PpI,96
|
|
7
|
+
ultrazohm_cli-0.1.1.dev0.dist-info/entry_points.txt,sha256=vk3Hj65a98P_jZ4liOJuSjHwouMaagyAwO5-lhcloaE,55
|
|
8
|
+
ultrazohm_cli-0.1.1.dev0.dist-info/sboms/ultrazohm_cli.cyclonedx.json,sha256=80DXpVDy_OltdGEa0NbhIJBudDWnPWrH4q-io1MmhSo,452212
|
|
9
|
+
ultrazohm_cli-0.1.1.dev0.dist-info/RECORD,,
|