plesty-lib 0.3.4__tar.gz → 0.3.5.dev2__tar.gz

{plesty_lib-0.3.4 → plesty_lib-0.3.5.dev2}/CHANGELOG.md

@@ -1,5 +1,102 @@
 # Changelog
 
+## 0.3.5.dev2 — 2026-08-17
+
+Development pre-release for field-testing the rig start-up (#36, #37):
+bounded, visible connects, the preflight, and default logging. Same line as
+0.3.5.dev1 — the final release is 0.4.0.
+
+- **A run starts only on a rig that is really there** (pol-pl field
+  finding: a sweep went on with the powermeter server absent).
+  `CompositeDevice.preflight()` checks that every remote sub-device exposes
+  the methods listed under the new `requires` config key and answers
+  `identity()`; `Experiment.setup()` runs it and raises `RigNotReadyError`
+  on any problem. `plesty.lib.experiment.connect_rig(build, optional=…)`
+  is the start-up for every experiment's `__main__`: build, preflight, and
+  on a failure print which device, at which address, from which variable,
+  then ask `[r]etry / [a]bort / [s]kip` (skip only for optional
+  sub-devices, returned as `skipped`); non-interactive processes get the
+  diagnosis logged and `RigNotReadyError`. Text in
+  `experiment/assets/preflight.yaml`.
+- **A composite that is given up closes its clients.** New
+  `CompositeDevice.release()` closes every remote client on its owning
+  thread (server-side disconnect with a 1 s window, linger 0) and stops the
+  threads; `disconnect_all()` does the same for remote clients, and a first
+  connect that fails closes the clients that did connect. A client left to
+  the garbage collector blocked the interpreter in its ZMQ context's
+  `__del__` — seen mid-run after `connect_rig` rebuilt a rig without the
+  powermeter. `connect_rig` releases a rig it gives up.
+- **A first connect to a dead server now returns.** The client's connect
+  failure path closed its DEALER socket with the default infinite LINGER,
+  so `ctx.term()` blocked forever on the undelivered handshake — a rig built
+  against one absent server hung with no output, and no attempt ladder or
+  deadline could bound it. `_DeviceTCPIPClient` now drops undelivered
+  messages (linger 0) when a connect fails and on `close()`.
+  `CompositeDevice` also resolves every address before starting any connect
+  (a half-configured `.env` raises `ValueError` without touching a server)
+  and stops its worker threads when a first connect fails.
+- **`CompositeDevice` signals sub-device connection state and bounds the first
+  connect** (#36). Each sub-device carries a `ConnectionState`
+  (`CONNECTING → CONNECTED → DEGRADED → DISCONNECTED`), read with
+  `status()` / `status(dev)` and observed with `on_status_change(callback)`;
+  every transition is logged (WARNING for `DEGRADED` / `DISCONNECTED`).
+  New config key `connect_deadline_s` (default 10 s): a server that does not
+  answer within it raises `DeviceUnreachableError(dev, address, elapsed_s)`
+  from the constructor instead of running attempts × timeout × backoff
+  (~40 s per dead server before). Under thread affinity the first connects
+  run in parallel on the sub-devices' own threads. `reconnect()` reuses the
+  sub-device's configured `timeout_ms` / `attempts` / `backoff_s` instead of
+  the 50 s defaults; a call timeout marks the sub-device `DEGRADED` before
+  the rebuild. `_DeviceTCPIPClient.set_default_timeout(ms)` added.
+- **Default logging for experiments and composites** (#37): nothing is
+  silent anymore without module code. `Experiment` logs
+  `Run <id>: N step(s) (k already completed), run dir …`, `Setup: …`,
+  `Step i/N <id> (<op>)` / `Step i/N done in x s`, `Teardown: …`, and
+  `Run … completed (N steps) in x s`. `CompositeDevice` logs
+  `Connecting <dev> @ <addr>` / `Connected <dev> @ <addr> in x s`, each failed
+  attempt with the retry delay, `Reconnecting <dev> @ <addr>`, and the timeout
+  a retried call ran under. New `plesty.lib.utils.logger.ensure_logging()`
+  (root level + one console sink, idempotent) is called by both constructors;
+  `setup_logging(app)` builds on it and adds the per-process log file — the
+  first `app` names the file, so a rig built before its experiment no longer
+  steals the file name.
+
+## 0.3.5.dev1 — 2026-08-17
+
+Development pre-release for field-testing the run convention (#34); the
+final release of this line is 0.4.0 — the API diff against 0.3.4 (the
+`pattern=` arguments and `data_dir` attributes of the run sources are
+gone, `Experiment(run_root=)` defaults to the mount) is a minor bump.
+
+- `plesty.lib.monitor.Viz` (#34): the `monitor` / `render` command line over
+  an experiment's panels. The experiment registers one function
+  (`@viz.panels`, `Run` → panels) and calls `viz.main()`; run discovery,
+  `--run-root/--mount/--data-dir/--run`, live vs `--replay`, `--record`,
+  offscreen `render` with self-stop, and the text catalog
+  (`monitor/assets/viz.yaml`) are the lib's. `Run(..., data_dir=)` supplies
+  the host spelling for runs that did not record it.
+- **Run layout: one `records.jsonl` per run instead of one `data/step_NNNN.json`
+  per step** (#34). Each completed step appends one fsynced line (its
+  `ResultDocument` + `index`; blobs still go to `data/`), and readers tail
+  the file by byte offset — writing and following a long run on a network
+  share no longer costs a file open and a directory listing per step. New:
+  `plesty.lib.data.append_record` / `read_records` / `record_value`;
+  `RunSource`/`ReplaySource` lose their `pattern` argument and gain `unread`
+  and `legacy`; the journal's `step_completed` carries `recorded` instead of
+  a `result` path; a resumed run also counts steps with a committed record
+  as done. Runs in the old layout are still read (`RunSource.legacy`).
+- The run convention is spelled out once and exported (#34):
+  `plesty.lib.experiment.runs` — `run_id`/`parse_run_id`, `list_runs`,
+  `latest_run`, and `Run` (plan, config, journal status, records, and
+  `local()` translation of device-written paths onto this machine).
+- One environment convention for the shared disk: `PLESTY_DATA_DIR` (as the
+  acquiring host sees it) and `PLESTY_DATA_MOUNT` (as this machine sees it).
+  `Experiment` reads both (or `data_dir=`/`data_mount=`), defaults
+  `run_root` to the mount when set, exposes `self.run_id`/`self.run_dir`
+  before `setup()` and `self.raw_dir` = `<data_dir>/<run_id>/raw` for the
+  writing devices, and journals all three with `run_started`. `run_root`
+  still defaults to `runs` without a mount.
+
 ## 0.3.4 — 2026-08-14
 
 - The server never cancels a receive (#33): the old

{plesty_lib-0.3.4 → plesty_lib-0.3.5.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plesty-lib
-Version: 0.3.4
+Version: 0.3.5.dev2
 Summary: A library for the Plesty ecosystem.
 Author: Plesty Development Team
 Author-email: Yunshuang Yuan <yunshuang.yuan@fkp.uni-hannover.de>

{plesty_lib-0.3.4 → plesty_lib-0.3.5.dev2}/docs/device/composite_device.md

@@ -60,7 +60,9 @@ composite = CompositeDevice(
 |---|---|
 | `address` | Explicit ZMQ address, skipping the environment |
 | `env` | Environment variable to read, overriding the derived name |
-| `timeout_ms`, `attempts`, `backoff_s` | Forwarded to `connect_client` |
+| `timeout_ms`, `attempts`, `backoff_s` | Forwarded to `connect_client` (first connect and every reconnect) |
+| `connect_deadline_s` | Budget for the *first* connect (default 10 s); past it the constructor raises `DeviceUnreachableError` |
+| `requires` | Remote methods the server must expose; checked by `preflight()` (a wrong address connects fine but is not this device) |
 
 The address comes from `address` if given, else the environment; an unset
 variable raises a `ValueError` naming the variable to set.
@@ -106,10 +108,48 @@ explicitly.
 `connect_client(address)` is the module-level builder used for the rebuilds:
 `build_client` plus a connection-handshake retry with linear backoff, which
 matters when several clients open back-to-back against the same server.
+`reconnect(dev)` rebuilds with the sub-device's own `timeout_ms` /
+`attempts` / `backoff_s`, not the defaults.
 
 Every multi-device composite gets this robustness for free instead of
 re-implementing it per module.
 
+## Connection state and a bounded first connect
+
+The composite is never silent about its servers. Constructing it logs one
+line per sub-device (`Connecting hwp @ tcp://… (timeout 5000 ms) …`,
+`Connected hwp @ tcp://… in 0.4 s`, or `Connect to tcp://… failed, attempt
+1/4: … ; retrying in 2 s`) and a summary (`PolPlRig ready in 1.2 s:
+hwp=tcp://…, spec=tcp://…`) — the console sink is switched on by the
+composite itself (`ensure_logging()`), so this shows even when the composite
+is built before the experiment that would configure logging.
+
+The **first connect is bounded**: each configured sub-device gets
+`connect_deadline_s` (default 10 s); a server that does not answer within it
+raises `DeviceUnreachableError(dev, address, elapsed_s)` from the constructor
+instead of grinding through attempts × timeout × backoff. Under thread
+affinity the first connects run in parallel on the sub-devices' own threads,
+so three dead servers cost one deadline, not three. Reconnects during a run
+keep the attempt ladder — a server busy finishing a long move must be waited
+for, not declared dead.
+
+Each sub-device carries a `ConnectionState` — `CONNECTING → CONNECTED →
+DEGRADED` (a call timed out, the client is being rebuilt) `→ DISCONNECTED`
+(connect/reconnect failed, or `disconnect_all()`):
+
+```python
+composite.status()          # {"hwp": ConnectionState.CONNECTED, "spec": ...}
+composite.status("hwp")     # ConnectionState.CONNECTED
+
+@composite.on_status_change
+def _show(dev, old, new, detail):
+    ui.set_led(dev, new)    # runs on the thread that changed the state
+```
+
+Every transition is logged (INFO, or WARNING for `DEGRADED` /
+`DISCONNECTED`) whether or not anyone subscribes; a subscriber that raises
+is logged and ignored — a broken UI hook must not break the rig.
+
 ## One thread per sub-device
 
 ZMQ sockets are not thread-safe, and even migrating one between threads is
@@ -161,6 +201,16 @@ for a data directory either fails or means nothing:
 composite.set_data_path(frames_dir, devices=["spec"])
 ```
 
+## Preflight
+
+`preflight()` proves each sub-device is the device it is supposed to be and
+answers: a remote sub-device must expose every method in its `requires`
+list and its `identity()` must reply; a local one must have the required
+attributes. It returns `{name: problem}` for the failures (empty when the
+rig is ready) and logs one line per sub-device either way. `Experiment`
+runs it in `setup()`; `plesty.lib.experiment.connect_rig` runs it at
+start-up and asks the operator what to do (see the experiment guide).
+
 ## Interplay with experiments
 
 `Experiment` accepts a `CompositeDevice` at construction; its default

plesty_lib-0.3.5.dev2/docs/experiment.md

@@ -0,0 +1,218 @@
+# Experiment Framework
+
+`plesty.lib.experiment` turns a measurement routine into a **reproducible,
+crash-tolerant run**. The mental model is checkpointed training in deep
+learning: the *plan* is the training schedule, the *journal* is the training
+log, and the completed-step set plus persisted step results form the
+checkpoint.
+
+An `Experiment` orchestrates devices through a
+[`CompositeDevice`](device/composite_device.md) — it receives Device
+instances, never raw hardware.
+
+## The pieces
+
+| Piece | Role |
+|---|---|
+| `Step` | The smallest unit of work: a stable `id`, an operation name `op`, and its `params`. A step either completes (result persisted and journaled) or is re-run on resume. |
+| `Plan` | The frozen, ordered schedule of steps plus the run configuration. Written to disk at run start, never mutated; a SHA-256 `content_hash()` identifies the schedule. |
+| `Journal` | A crash-safe, append-only JSONL event log (`run_started`, `step_started`, `step_completed`, `step_failed`, `run_completed`/`_canceled`/`_aborted`). Replaying it derives the run state and the completed-step set. |
+| `records.jsonl` | One line per completed step: its result document (`plesty.lib.data.append_record` / `read_records`). One file, appended and fsynced per step, tailed by offset — not one small file per step, which is slow to write and slow to follow on a network share. |
+| `Experiment` | The async ABC tying it together: validate → journal → execute with retries → persist results → resume. |
+| `Run` | Read access to a stored run — plan, config, journal status, records, and the translation of device-written paths onto this machine (`plesty.lib.experiment.runs`, which also spells out the naming below and finds runs: `list_runs`, `latest_run`). |
+
+Every run owns a directory:
+
+```text
+<run_root>/<run_id>/            # run_id = <name>_<YYYYmmdd-HHMMSS>
+├── plan.json                   # frozen schedule + config + content hash
+├── journal.jsonl               # append-only event log
+├── records.jsonl               # one line per completed step: its result document
+└── data/                       # blobs the records reference (arrays, images), if any
+    └── step_0003.npy
+```
+
+Each record line is a typed [`ResultDocument`](data_schemas.md) with
+provenance (`step_id`, `op`, `params`) plus the step `index`; a JSON value
+result is inlined, an array or image stays a raw blob in `data/` that the
+line references. The line is the commit — it is appended (and fsynced) only
+after the blob is on disk, and a resumed run treats a committed record as a
+completed step even if the crash came before its journal event. Runs
+written by plesty-lib ≤ 0.3.4 (one `data/step_*.json` per step) are still
+read by `RunSource`, `records()`, and `Run`.
+
+## Writing an experiment
+
+Subclasses override exactly three lifecycle hooks — `build_plan()`
+(required), `setup()`/`teardown()` (optional, extend the defaults which
+connect/disconnect all devices) — plus one public method per step operation:
+
+```python
+import asyncio
+from plesty.lib.data import PlestyArray
+from plesty.lib.experiment import Experiment, Plan, Step
+
+class LineScan(Experiment):
+    def build_plan(self) -> Plan:
+        steps = [
+            Step(id=f"scan[x={x}]", op="scan_point", params={"x": x})
+            for x in range(5)
+        ]
+        return Plan(steps, config={"points": 5})
+
+    def scan_point(self, x: int) -> PlestyArray:
+        # drive devices via self.devices, return the measurement
+        return PlestyArray([float(x)], name="signal", unit="a.u.")
+
+run_id = asyncio.run(LineScan(run_root="runs").run())
+```
+
+Rules that keep runs reproducible:
+
+- **`build_plan()` must be deterministic** for a given configuration —
+  resume compares the regenerated plan against the persisted one by content
+  hash.
+- **Step ids must be stable** (e.g. `"scan[x=3,y=5]"`) — never derived from
+  run time or randomness; resume matches completed steps by id.
+- **Step operations are validated before anything runs**: every `Step.op`
+  must name an existing public method and may not be a reserved lifecycle
+  method (`build_plan`, `run`, `setup`, `teardown`). Violations raise
+  `InvalidOperationError` listing all offending steps — before any device is
+  touched or journal written.
+
+Step methods may be sync or async; results are awaited automatically. Each
+step is retried (`max_retries`, `retry_sleep` constructor arguments) before
+the run aborts.
+
+## Starting on a rig that is really there
+
+An experiment's `__main__` builds the rig with `connect_rig` — the same
+start for every experiment: connect the servers, run the composite's
+`preflight()` (each sub-device exposes the methods its configuration
+`requires` and answers `identity()`), and if anything is missing, tell the
+operator which device, at which address, from which variable — and ask:
+
+```python
+from plesty.lib.experiment import connect_rig
+
+rig, skipped = connect_rig(
+    lambda skip: PolPlRig(with_powermeter="pm" not in skip),
+    optional={"pm"},                       # the experiment can run without it
+)
+```
+
+```text
+The rig is not ready — 1 device(s) failed the preflight:
+  - pm: no answer from tcp://127.0.0.1:5557: TimeoutError('Server did not respond in time')
+      address tcp://127.0.0.1:5557 (from PM_ADDRESS in .env / the environment)
+Check that the pm server(s) are running and that PM_ADDRESS point at them
+(a wrong port connects fine but is not the expected device).
+[r] retry (after fixing .env or starting the server)  [a] abort  [s] continue without pm
+>
+```
+
+`r` rebuilds the rig (an edited `.env` or a freshly started server is picked
+up), `a` raises `RigNotReadyError`, `s` — offered only when every failing
+sub-device is in `optional` — returns the rig without them and names them in
+`skipped`, so the experiment can drop the matching part of its plan. Without
+a terminal on stdin nothing waits: the diagnosis is logged and
+`RigNotReadyError` raised.
+
+The check also runs inside `Experiment.setup()`: a run never starts on a
+composite whose `preflight()` reports a problem, whether or not `connect_rig`
+was used. Declare what each sub-device must be able to do in its
+configuration — that is what turns "the port answers" into "it is the
+stage":
+
+```yaml
+devices:
+  hwp:  {timeout_ms: 5000, requires: [home_stage, move_absolute, get_position]}
+  spec: {timeout_ms: 5000, requires: [acquire, get_recent_file, write, query]}
+  pm:   {timeout_ms: 5000, requires: [measure_power, write]}
+```
+
+## Data on a shared disk
+
+Blobs a device writes itself (spectrometer frames, camera images) never
+cross the network: the acquiring host saves them to a shared disk and the
+step record carries only the path. Two machines spell that share
+differently, so it is named once, by environment:
+
+| Variable | Meaning |
+|---|---|
+| `PLESTY_DATA_DIR` | the share as the acquiring host sees it (e.g. `G:\RAWDATA`) |
+| `PLESTY_DATA_MOUNT` | the same share as this machine sees it (e.g. `/mnt/group/RAWDATA`) |
+
+The experiment reads both (or takes `data_dir=` / `data_mount=` at
+construction). With the mount set, `run_root` defaults to it, so runs land
+on the share as well. Before `setup()` is awaited the run id is known and
+`self.raw_dir` names `<data_dir>/<run_id>/raw` in the host's spelling — one
+folder per run, the same one on resume — which `setup()` routes the writing
+devices to:
+
+```python
+async def setup(self) -> None:
+    await super().setup()
+    if self.raw_dir is not None:
+        self.devices.set_data_path(self.raw_dir, devices=["spec"])
+```
+
+`run_started` journals `data_dir`, `data_mount`, and `raw_dir`, so a reader
+needs at most its own mount:
+
+```python
+from plesty.lib.experiment import Run, latest_run
+
+run = Run(latest_run("/mnt/group/RAWDATA", name="pol_pl"))
+run.config["powermeter"]                 # the frozen configuration
+run.status()["state"]                    # "running", "completed", ...
+for record in run.records():
+    run.local(record["data_file"])       # G:\RAWDATA\... → /mnt/group/RAWDATA/...
+```
+
+`Run.local` uses, in order, an explicit `mount=`, `PLESTY_DATA_MOUNT`, and
+the mount journaled by the machine that ran the experiment (only when that
+directory exists here); with neither a data root nor a mount the path is
+returned as recorded — the case of reading on the acquiring host itself.
+`run.source(mapper)` returns a `RunSource` (live) or, with
+`Run(..., replay_rows=n)`, a `ReplaySource` — see [Monitors](monitor.md).
+
+## Crash, cancel, resume
+
+`run()` returns the run id. If the run is interrupted — `Ctrl-C`, a crash,
+an aborting step — pass the id back to continue:
+
+```python
+run_id = asyncio.run(LineScan(run_root="runs").run())
+# ... interrupted?
+asyncio.run(LineScan(run_root="runs").run(resume=run_id))
+```
+
+On resume the framework:
+
+1. regenerates the plan and **refuses to continue if its content hash
+   differs** from the stored one (`PlanMismatchError`) — a silently changed
+   schedule or configuration cannot corrupt a run;
+2. replays the journal to find completed steps and skips them;
+3. journals the resume (`run_started` with `resumed: true`) and continues.
+
+`teardown()` is always awaited — on completion, failure, and cancellation —
+so devices are released no matter how the run ends.
+
+## Contract tests without hardware
+
+`plesty.lib.test.experiment_pipeline.ExperimentPipeline` verifies the
+plan/checkpoint contract of an experiment module with **no instrument
+attached** (it never calls `run()`). Five gates:
+
+| Gate | Checks |
+|---|---|
+| 1 `test_experiment_subclass` | public `Experiment` subclass, instantiable without devices |
+| 2 `test_plan_deterministic` | `build_plan()` twice → identical `content_hash()` |
+| 3 `test_plan_ops_resolve` | every `Step.op` resolves via the framework's own plan validation |
+| 4 `test_plan_serializable` | `Plan.save`/`load` round-trip preserves the hash |
+| 5 `test_lifecycle_hooks` | `setup`/`teardown` overrides are async |
+
+Experiment HUB modules expose one pytest function per gate (SDK gate E1
+verifies their presence and passage — the experiment-tier mirror of device
+gate d1); see [Test Helpers](device/test_helper.md) for the pattern.

{plesty_lib-0.3.4 → plesty_lib-0.3.5.dev2}/docs/monitor.md

@@ -82,16 +82,19 @@ clock belongs to the caller: a GUI timer, a test loop, a notebook cell.
 
 | Source | Follows | Typical use |
 |---|---|---|
-| `RunSource` | `<run_dir>/data/step_*.json` | any running experiment |
+| `RunSource` | `<run_dir>/records.jsonl`, tailed by offset | any running experiment |
 | `TelemetrySource` | `TelemetryEvent`s of devices | live device readings |
 | `PushSource` | whatever the producer emits | tests, notebooks |
 
 `RunSource` is the generic live view of *any* PLESTY experiment: the
-[experiment framework](experiment.md) writes one result document per
-completed step, and that document is the commit record of the write, so
-following the directory needs no cooperation from the experiment and cannot
-disturb it. It also means a viewer started mid-run still sees every earlier
-row.
+[experiment framework](experiment.md) appends one record line per completed
+step, and that line is the commit record of the write, so following the file
+needs no cooperation from the experiment and cannot disturb it. Each poll
+reads only the bytes appended since the last one, so following a run of
+thousands of steps on a network share stays cheap. It also means a viewer
+started mid-run still sees every earlier row. A `Run` from
+`plesty.lib.experiment` builds the source for you (`run.source(mapper)`),
+live or replayed.
 
 ```python
 from plesty.lib.monitor import RunSource
@@ -137,6 +140,57 @@ infrastructure. Reusable views live in their own package
 (`plesty-common-monitors`); rig-specific ones live next to the experiment
 that needs them.
 
+## Watching a run: `Viz`
+
+Everything about *watching* is the same for every experiment — which run
+(the newest, or `--run`), where the share is mounted, live or replayed, in a
+window or rendered offscreen to a video, recorded or not. `Viz` owns all of
+it; the experiment writes one function that says which record key means
+what, and that is its whole viz module:
+
+```python
+# plesty/pol_pl/viz.py
+import sys
+
+from plesty.common_monitors import SeriesMonitor, SpectrumMonitor, WaterfallMonitor
+from plesty.common_monitors.series import series_mapper
+from plesty.common_monitors.spectrum import spectrum_mapper
+from plesty.lib.monitor import Viz
+from plesty.lib.ui import MonitorPanel
+
+viz = Viz("Polarization PL", experiment="pol_pl")
+
+@viz.panels
+def panels(run):
+    spectra = spectrum_mapper("data_file", locate=run.local, row_key="hwp_deg")
+    yield MonitorPanel(SpectrumMonitor(run.source(spectra), name="spectrum"), weight=3)
+    yield MonitorPanel(WaterfallMonitor(run.source(spectra), name="map", y_label="HWP angle (deg)"), weight=3)
+    if run.config.get("powermeter"):
+        power = run.source(series_mapper("hwp_deg", "power_w", y_scale=1e6))
+        yield MonitorPanel(SeriesMonitor(power, name="power", y_label="Power (uW)"), weight=2)
+
+if __name__ == "__main__":
+    sys.exit(viz.main())
+```
+
+```bash
+python -m plesty.pol_pl.viz monitor                       # follow the newest run live
+python -m plesty.pol_pl.viz monitor --replay 2 --record demo.mp4
+python -m plesty.pol_pl.viz render --run pol_pl_20260805-091909   # <run-id>.mp4, no window
+```
+
+The function receives a [`Run`](experiment.md#data-on-a-shared-disk):
+`run.source(mapper)` is already a `RunSource` or a `ReplaySource` as the
+subcommand decided — call it **once per view**: a source hands each record
+out once, so two views polling one source would split the rows between them
+(a mapper, by contrast, is freely shared); `run.local` translates the acquiring host's paths onto
+this machine, `run.config` is the frozen configuration. Runs are looked for
+under `--run-root` (default `PLESTY_DATA_MOUNT`, else `runs`); `--mount`
+and `--data-dir` override the share's two spellings for runs that did not
+record them. `render` sets Qt's offscreen platform before the toolkit is
+imported and stops by itself once every source is exhausted; neither
+`--help` nor `resolve_run` needs the `gui` extra.
+
 ## Testing a monitor
 
 `NullRenderer` records draw calls instead of drawing them, so the whole path

{plesty_lib-0.3.4 → plesty_lib-0.3.5.dev2}/gl-secret-detection-report.json

@@ -19,19 +19,19 @@
       "version": "8.30.1"
     },
     "type": "secret_detection",
-    "start_time": "2026-08-14T16:45:05",
-    "end_time": "2026-08-14T16:45:05",
+    "start_time": "2026-08-17T15:29:32",
+    "end_time": "2026-08-17T15:29:32",
     "status": "success",
     "observability": {
       "events": [
         {
           "event": "collect_secrets_analyzer_scan_metrics_from_pipeline",
-          "time_s": 0.490144528,
+          "time_s": 0.45769703,
           "exit_code": 0,
           "git_strategy": "FetchShallow",
-          "repo_size_kb": 662,
+          "repo_size_kb": 708,
           "commit_count": 1,
-          "bytes_scanned": 24,
+          "bytes_scanned": 220,
           "pipeline_type": "Tag"
         },
         {

{plesty_lib-0.3.4 → plesty_lib-0.3.5.dev2}/plesty/lib/data/__init__.py

@@ -15,7 +15,16 @@ from .types import (
     cast_basic_type,
 )
 from .table import TableHeader, PlestyTable2D, PlestyTable3D
-from .io import ResultDocument, save_result, load_result, load_document, convert_to_hdf5
+from .io import (
+    ResultDocument,
+    append_record,
+    convert_to_hdf5,
+    load_document,
+    load_result,
+    read_records,
+    record_value,
+    save_result,
+)
 
 __all__ = [
     "PlestyArray",
@@ -24,6 +33,9 @@ __all__ = [
     "load_result",
     "load_document",
     "convert_to_hdf5",
+    "append_record",
+    "read_records",
+    "record_value",
     "Units",
     "TableHeader",
     "PlestyTable2D",