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.
@@ -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"]
@@ -0,0 +1,4 @@
1
+ """Allow `python -m ultrazohm_cli` as well as the installed console command."""
2
+ from .cli import main
3
+
4
+ raise SystemExit(main())
Binary file
ultrazohm_cli/cli.py ADDED
@@ -0,0 +1,8 @@
1
+ """Console entry point; all parsing, control and acquisition run in Rust."""
2
+ import sys
3
+
4
+ from ._native import cli_main
5
+
6
+
7
+ def main():
8
+ return cli_main(sys.argv)
@@ -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,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: maturin (1.16.0)
3
+ Root-Is-Purelib: false
4
+ Tag: cp310-abi3-win_amd64
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ ultrazohm_cli=ultrazohm_cli.cli:main