plesty-sdk 0.3.3__tar.gz → 0.3.5.dev1__tar.gz

{plesty_sdk-0.3.3 → plesty_sdk-0.3.5.dev1}/CHANGELOG.md

@@ -2,6 +2,100 @@
 
 The format is based on [Keep a Changelog](https://keepachangelog.com).
 
+## [0.3.5.dev1] — 2026-08-21
+
+Development pre-release: the tutorial needs the pin option before 0.3.5 is
+ready to be called finished.
+
+### Added
+- `plesty init --lib-version VERSION` pins `plesty-lib` to what the caller
+  names instead of to the newest release on PyPI, and skips the lookup. A bare
+  version becomes a lower bound (`0.3.5.dev3` → `>=0.3.5.dev3`); a complete
+  specifier is written as given (`==0.4.0`, `>=0.3.5.dev3,<0.4`). One that PEP
+  440 cannot read is refused at the command line, before a directory is
+  created. For the tutorial: a lesson quoting a `pyproject.toml` and the file
+  its reader ends up with have to keep saying the same thing however far the
+  library has moved since the page was written — and a scaffold on an
+  air-gapped machine now pins what was asked for rather than a fallback.
+
+## [0.3.4] — 2026-08-21
+
+### Changed
+- The scaffold is generated against the **newest published `plesty-lib`**, not
+  the one that existed when the SDK was released: `plesty init` reads the
+  version list from PyPI (pre-releases included — the development line is where
+  the features the templates use land first) and pins `plesty-lib>=<newest>`.
+  The lookup has a 3 s budget and every way it can fail — no route, a proxy, a
+  body that is not the expected JSON, a fully yanked release — falls back to
+  `PLESTY_LIB_VERSION` (currently 0.3.5.dev3), the library the templates are
+  written against; the pin is never lower than that floor. The dev group pins
+  `plesty-sdk>=0.3.4` — this release, the one the scaffold is written against —
+  instead of `>=0.2.0`.
+- The experiment scaffold starts its rig the way plesty-lib 0.3.5.dev2 asks it
+  to. `__main__.py` declares a `RIG` — one sub-device per instrument, naming
+  the operations the experiment calls on its server — and hands it to
+  `connect_rig()`, which builds the composite, preflights it, and on a failure
+  names the sub-device, its address and the variable that set it before
+  offering retry / abort / skip. Addresses are resolved from `<NAME>_ADDRESS`
+  by the composite itself, so `build_client` is gone; the rig is `release()`d
+  after the run, `--run-root` defaults to `PLESTY_DATA_MOUNT` (the run lands on
+  the share), and `.env.example` carries `PLESTY_DATA_DIR`/`PLESTY_DATA_MOUNT`.
+  The run config is read with `plesty.lib.utils.config.load_yaml` instead of a
+  hand-written `yaml.safe_load` — the last copy of a loader the library owns.
+- The device scaffold exposes its example operation with `@expose_to_api` and
+  shows how an operation that acts on the world declares what it does
+  (`kind="motion"`, `position_key`, `step`, `kind="lifecycle"`) — what the
+  field-test interview and `FieldTestPipeline` now drive operations by.
+  `base_device.py` re-exports `expose_to_api`, as the hub modules do.
+
+### Added
+- `plesty init field-test` reads the kind each operation declares
+  (plesty-lib#39: `@expose_to_api(kind=…)` / a schema `kind` block) and
+  asks only what it leaves open. A declared kind is shown as `[motion]`,
+  `[lifecycle]`, `[control]` beside the operation and pre-fills the
+  "acts on the world" question, which is asked only for undeclared
+  operations; a `configure` operation is not offered and is recorded as
+  excluded (the round-trip gate covers settings). For an allow-listed
+  motion the interview confirms `step` (the declared value is the default)
+  and asks `position_key` from the readable parameters when the module did
+  not declare it; a motion left without either is dropped, not guessed. A
+  motion slow-op skips the argument chooser and asks how far — a distance
+  the pipeline drives from wherever the part is and undoes. Both generated
+  files carry `OP_KINDS` and pass it to the host and client tiers.
+
+### Fixed
+- Generated `tests/field_test_client.py` imported the device class at the
+  top and, for a module with no hardware-free construction, left it unused
+  — failing the module's own lint gate. The import now lives with the
+  `SPAWN_FACTORY` that needs it.
+- `plesty init field-test`: an arrow key no longer answers the question
+  (#32). The key reader took the first byte of `ESC [ B` through
+  `sys.stdin`, whose buffer swallowed the rest, so the descriptor looked
+  idle and the press was read as a lone Escape — which confirmed the
+  question empty and moved on; three presses skipped three questions.
+  Keys are read from the descriptor itself, control sequences are consumed
+  whole, and Escape no longer counts as an answer.
+- `plesty init field-test`: a list longer than ten entries is shown but not
+  asked (#32). Drawn as a checkable list, a spectrometer's 262 parameters
+  were 500 lines per redraw — taller than any terminal, so nothing could be
+  erased and every keypress appended the list again. The interview now says
+  so first, keeps whatever `.plesty/field-test.json` already holds for the
+  question (an empty list on a first run), names the entry to edit, lists
+  the first ten with `… and N more`, and waits for Enter — otherwise two
+  such questions scroll past together.
+- A confirmed selection leaves a one-line record above the next question;
+  the list itself is erased on Enter and the transcript used to show every
+  question and none of the answers.
+- `answered` in `.plesty/field-test.json` records each question once
+  instead of growing on every interrupted run.
+- The generated docs-build Pages job gates on `html/latest/index.html`
+  instead of the directory path `"html/latest/"`: `rules.exists` matches
+  file globs, and the directory form stopped matching on gitlab.com
+  between 2026-07-21 and 2026-08-10 — every docs-build pipeline failed
+  with "no jobs" and the Pages sites froze while the deploys kept
+  succeeding. Existing repos pick the fix up on their next docs deploy
+  (the deploy rewrites the branch's `.gitlab-ci.yml` from this asset).
+
 ## [0.3.3] — 2026-08-14
 
 ### Changed

{plesty_sdk-0.3.3 → plesty_sdk-0.3.5.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plesty-sdk
-Version: 0.3.3
+Version: 0.3.5.dev1
 Summary: Command-line application for developing Python modules compliant with the Plesty standard.
 Author: Plesty Development Team, Yunshuang Yuan, Christopher Borchers, fvrehlinger, Maximilian Heller, Michael Zopf
 License-Expression: LGPL-3.0-or-later

{plesty_sdk-0.3.3 → plesty_sdk-0.3.5.dev1}/docs/commands/init.md

@@ -41,6 +41,7 @@ name, so `plesty-foo-bar` → `foo_bar` without needing `--name`.
 | `--author` | `John Doe` | Author name written into `pyproject.toml` and `REUSE.toml` |
 | `--email` | `john.doe@example.com` | Author email written into `pyproject.toml` |
 | `--standard` | `pixel` | Compliance standard for the generated CI pipeline: `pixel`, `nebula`, or `quantum`. A fresh scaffold is a prototype, so CI starts at `pixel`; bump it alongside your releases. |
+| `--lib-version` | newest on PyPI | Pin `plesty-lib` to this version instead of looking it up. A bare version becomes a lower bound (`0.3.5.dev3` → `>=0.3.5.dev3`); a complete specifier is written as given (`==0.4.0`, `'>=0.3.5.dev3,<0.4'`). PyPI is not consulted, so the scaffold is reproducible. |
 | `--no-ci` | off | Skip generating `.gitlab-ci.yml` entirely. |
 
 ## Directory rules
@@ -120,7 +121,23 @@ The `pyproject.toml` is pre-configured with:
 - The PyPI distribution name `plesty-foo-bar` (kebab-case)
 - `packages = ["plesty"]` so the module installs under the `plesty` namespace (`import plesty.foo_bar`)
 - Dynamic versioning via `versioningit`
-- `plesty-lib` as a runtime dependency
+- `plesty-lib` as a runtime dependency, pinned to the **newest version published
+  on PyPI** when the project is scaffolded (pre-releases included — that is where
+  the features the templates use land first). The lookup has a 3 s budget; with
+  no route to PyPI the pin falls back to `PLESTY_LIB_VERSION` in
+  `plesty/sdk/commands/init.py`, the library the templates are written against.
+  The pin is never lower than that floor: the scaffold uses that library's
+  operation kinds and rig start-up, and an older one would not run it.
+  `--lib-version` overrides all of that and skips the lookup — for a tutorial,
+  whose lesson text and reader's `pyproject.toml` have to keep agreeing however
+  far the library has moved since the page was written:
+
+  ```bash
+  plesty init experiment --name scan_exp --lib-version 0.3.5.dev3
+  #   → "plesty-lib>=0.3.5.dev3"
+  plesty init experiment --name scan_exp --lib-version '>=0.3.5.dev3,<0.4'
+  #   → "plesty-lib>=0.3.5.dev3,<0.4"
+  ```
 - `pytest`, `pytest-cov`, `mypy`, and `plesty-sdk` under `[dependency-groups] dev`
   (included automatically by `uv run` — no `--extra dev` needed)
 - Sphinx docs settings under `[tool.plesty.docs]`
@@ -167,6 +184,40 @@ python -m plesty.foo_bar --host 10.0.0.5 --tcp-port 6000   # CLI overrides env
 variables, so one `.env` drives both the server and the tests. It is skipped unless
 `DEVICE_HOST` is set.
 
+## Rig start-up and the shared disk (experiment only)
+
+The generated `__main__.py` does not open device clients itself. It declares
+the rig — one entry per sub-device, naming the operations the experiment calls
+on that server — and hands it to
+[`plesty.lib.experiment.connect_rig`](https://gitlab.com/plesty/core/plesty-lib):
+
+```python
+RIG = {"device": ["identity"]}
+OPTIONAL: frozenset[str] = frozenset()
+```
+
+`connect_rig` builds the composite, preflights it (every listed operation must
+be exposed and `identity()` must answer), and on a failure prints which
+sub-device, at which address, from which variable, then offers
+**retry / abort / skip** — skip only for the names in `OPTIONAL`. A retry calls
+the builder again, so a `.env` corrected or a server started in the meantime is
+picked up. Non-interactive processes get the diagnosis logged and
+`RigNotReadyError`; nothing is measured on a rig that is not what the plan
+assumes.
+
+Addresses are never written into the module: each sub-device reads
+`<NAME>_ADDRESS` from the environment (`device` → `DEVICE_ADDRESS`), overridable
+with `--device-address`.
+
+| Variable | Meaning |
+|---|---|
+| `<NAME>_ADDRESS` | ZMQ address of one sub-device's server |
+| `PLESTY_DATA_DIR` | Shared disk as the acquiring host writes it — devices write frames to `<PLESTY_DATA_DIR>/<run_id>/raw` and return only paths |
+| `PLESTY_DATA_MOUNT` | The same disk as this machine reads it; also the default `run_root`, so runs land on the share |
+
+Both data variables are optional: without them runs go to `./runs` and no
+device writes blobs. `--run-root` overrides the default per call.
+
 ## Next steps after scaffolding
 
 `plesty init` ends with a numbered, project-type-specific **Next steps** list —
@@ -312,6 +363,22 @@ in neither list: it is never called, and the gate that would have called it
 skips saying so. A generated allow-list that quietly included a motion command
 would be worse than no generator at all.
 
+**What the module declares is not asked again.** An operation exposed with a
+kind — `@expose_to_api(kind="motion", position_key="MO.Position", step=1.0)`,
+`kind="lifecycle"`, `kind="control"`, or a `"kind"` block in
+`schema_func.json` (plesty-lib#39) — is shown as `[motion]`, `[lifecycle]`,
+`[control]` in the chooser, and the "acts on the world" question is asked only
+about operations that declared nothing. A `configure` operation is not offered
+at all: it is recorded as excluded, because a setting that outlives the call is
+verified by the round-trip gate. For an allow-listed motion the interview
+confirms how far the test may move it (`step`; the declared value is the
+default) and, if the module left it open, which parameter reports the position
+— a motion with neither is dropped, since the pipeline drives a motion one step
+out from that parameter and back and will not guess how far. A motion chosen as
+the slow operation is asked only how far the long move goes: the pipeline
+starts it from wherever the part is and moves it back afterwards. Both
+generated files carry the result as `OP_KINDS`.
+
 The result is `tests/field_test.py`: hardware-gated (it defines no pytest test
 functions, so CI collects nothing), wired to publish
 `reports/<instrument>/field-test.json`, and runnable against the simulator

{plesty_sdk-0.3.3 → plesty_sdk-0.3.5.dev1}/gl-secret-detection-report.json

@@ -19,19 +19,19 @@
       "version": "8.30.1"
     },
     "type": "secret_detection",
-    "start_time": "2026-08-14T11:38:56",
-    "end_time": "2026-08-14T11:38:56",
+    "start_time": "2026-08-21T18:31:49",
+    "end_time": "2026-08-21T18:31:49",
     "status": "success",
     "observability": {
       "events": [
         {
           "event": "collect_secrets_analyzer_scan_metrics_from_pipeline",
-          "time_s": 0.271382223,
+          "time_s": 0.480570925,
           "exit_code": 0,
           "git_strategy": "FetchShallow",
-          "repo_size_kb": 492,
+          "repo_size_kb": 468,
           "commit_count": 1,
-          "bytes_scanned": 1664,
+          "bytes_scanned": 136,
           "pipeline_type": "Tag"
         },
         {

plesty_sdk-0.3.5.dev1/plesty/sdk/assets/docs-build-gitlab-ci.yml

@@ -0,0 +1,17 @@
+stages: [deploy]
+
+pages:
+  stage: deploy
+  rules:
+    # The gate for creating the job, not a selector of what is published —
+    # `publish: html/latest` below uploads the whole directory. exists
+    # matches FILE globs: the bare directory path "html/latest/" stopped
+    # matching on gitlab.com between 2026-07-21 and 2026-08-10, every
+    # docs-build pipeline failed with "no jobs", and Pages froze while the
+    # deploys kept succeeding. Name a file Sphinx always emits.
+    - exists:
+      - "html/latest/index.html"
+  script:
+    - echo "Serving documentation on GitLab pages..."
+  pages:
+    publish: html/latest

{plesty_sdk-0.3.3 → plesty_sdk-0.3.5.dev1}/plesty/sdk/assets/init/client-field-test.py.template

@@ -57,8 +57,6 @@ from plesty.lib.test.client_field_test import ClientFieldTest
 from plesty.lib.test.report_artifact import Instrument
 from plesty.lib.utils.settings import EnvSettings
 
-from {{DEVICE_IMPORT}} import {{DEVICE_CLASS}}
-
 #: The instrument address comes from ``.env`` — the same file the device
 #: server reads. Never written here: an address carries a serial number and
 #: this file is committed.
@@ -83,6 +81,7 @@ BASELINE = PROJECT_ROOT / "reports" / "{{INSTRUMENT_SLUG}}" / "field-test.json"
 {{TYPES_BLOCK}}
 {{RESOURCES_BLOCK}}
 {{SAFE_OPS_BLOCK}}
+{{OP_KINDS_BLOCK}}
 {{SPAWN_BLOCK}}
 
 def build(address: str | None, spawn: bool) -> ClientFieldTest:
@@ -100,6 +99,9 @@ def build(address: str | None, spawn: bool) -> ClientFieldTest:
         expected_types=EXPECTED_TYPES,
         resources=RESOURCES,
         safe_ops=SAFE_OPS,
+        # How each of them is driven — the host tier's kinds, handed over
+        # because describe() cannot say which method moves a stage.
+        op_kinds=OP_KINDS,
         # The host tier's report decides what this tier touches. Its coverage
         # block records what that run actually reached on this instrument,
         # already filtered by what the fitted sensor supports — so the two

{plesty_sdk-0.3.3 → plesty_sdk-0.3.5.dev1}/plesty/sdk/assets/init/field-test-questions.yaml

@@ -34,6 +34,17 @@ intro: |
 
   Ctrl-C stops without writing anything.
 
+# Shown instead of a choice when a list is longer than the interview offers
+# at the terminal (sdk#32). {count} items, {shown} listed, {key} is the entry
+# in the answers file at {answers}, {state} says what is written for it now.
+too_long: |
+  {count} entries — more than the {shown} this interview can offer at once.
+
+  The answer is written {state}: "{key}" in {answers}.
+  To choose, put the entries you want in that list and run this command
+  again; the list is then taken as the answer. The first {shown} of the
+  {count} follow, for orientation.
+
 questions:
   safe_ops:
     when_empty: "nothing selected — no operation will be called or timed"
@@ -62,6 +73,12 @@ questions:
         · changes a setting or calibration that outlives the call
         · takes a long time, or writes files
         · needs arguments you would have to invent
+
+      An operation shown as [motion], [lifecycle], [control] or [acquire]
+      was declared so by the module, and the test already knows how to
+      drive it: a motion one step out from its position parameter and back,
+      a lifecycle op once, a control op once after the motions. Pick those
+      when the bench allows it — the two questions above still apply.
     reason_prompt: "Why is '{item}' safe to run 20 times unsupervised?"
     after: >-
       Nothing selected. The test will not call any operation, and will say so
@@ -85,6 +102,41 @@ questions:
     reason_prompt: "Which safeguard makes '{item}' safe to repeat?"
     after: "nothing selected — taken as: all of these only read"
 
+  motion_position_key:
+    when_empty: "nothing selected — the motion is dropped from the allow-list"
+    prompt: "Which parameter reports where '{item}' moves the part to?"
+    why: >-
+      A motion is driven from where the part is: the test reads its position,
+      moves it one step out, moves it back and checks the position returned.
+      The module did not say which parameter that is, so it is asked here.
+    decide: |
+      Pick the parameter that reports the moving part's position in the same
+      units the operation takes — a stage angle in degrees against a move in
+      degrees, a piezo position in µm against a step in µm.
+
+      Pick nothing if no parameter reports it: the motion is then left out,
+      because the test will not move a part it cannot place.
+    after: >-
+      No position parameter named. The operation is left out of the
+      allow-list; declare position_key in the module and re-run.
+
+  motion_step:
+    prompt: "How far may the test move '{item}'?"
+    why: >-
+      Every repetition moves the part this far out and straight back, twenty
+      times in a row with nobody watching. The size is the safeguard: small
+      enough to be harmless whatever is mounted, large enough to be a real
+      move rather than a no-op below the stage's resolution.
+    decide: |
+      Give a distance in the position parameter's units. A stage that resolves
+      26 µdeg is fine with 1 deg; a piezo with a 100 µm range with 1 µm.
+      Press Enter to accept the value the module declared, if it did.
+
+      Give nothing (or 0) if no distance is harmless: the motion is then left
+      out of the allow-list.
+    value_prompt: "Step for '{item}', in the units of {position_key}"
+    after: "no step given — the motion is dropped from the allow-list"
+
   only_keys:
     when_empty: "nothing selected — EVERY setting will be written back"
     prompt: "Which settings can be safely written back their own value?"
@@ -168,6 +220,13 @@ questions:
       Pick nothing if none of them work that way — a mode or a unit does not
       make a call slower, and the check is better skipped than fooled.
     value_prompt: "What value of '{item}' makes the call take longer than a tenth of a second?"
+    motion_value_prompt: >-
+      How far should the slow move of '{item}' go — a distance from wherever
+      the part is, in the units of {position_key} — to take longer than a
+      tenth of a second?
+    motion_restored: >-
+      '{item}' is a motion: the test moves the part that far from where it is,
+      interrupts the call, and afterwards moves it back to where it started.
     after: >-
       No argument chosen. The recovery check will be skipped: it can name the
       call but not make it slow enough to interrupt.

{plesty_sdk-0.3.3 → plesty_sdk-0.3.5.dev1}/plesty/sdk/assets/init/field-test.py.template

@@ -74,6 +74,7 @@ INSTRUMENT = Instrument(model="{{INSTRUMENT_MODEL}}", sensor={{INSTRUMENT_SENSOR
 
 {{SAFE_OPS_BLOCK}}
 {{UNSAFE_OPS_BLOCK}}
+{{OP_KINDS_BLOCK}}
 {{ONLY_KEYS_BLOCK}}
 {{DRAIN_PROBE_BLOCK}}
 {{SLOW_OP_BLOCK}}
@@ -104,6 +105,7 @@ def build_pipeline(
         "report_path": report_path,
         "safe_ops": SAFE_OPS,
         "unsafe_ops": UNSAFE_OPS,
+        "op_kinds": OP_KINDS,
         "only_keys": ONLY_KEYS,
         "drain_probe": DRAIN_PROBE,
         "slow_op": SLOW_OP,

{plesty_sdk-0.3.3 → plesty_sdk-0.3.5.dev1}/plesty/sdk/assets/init/next-steps.yaml

@@ -10,6 +10,7 @@ default:
 device:
   - "Define the device schema and wire it into plesty/{module_name}/base_device.py."
   - "Implement the vendor communication in plesty/{module_name}/device.py."
+  - "Expose your custom operations with @expose_to_api and declare what each one does (kind=motion/acquire/lifecycle/control/configure) — the field test drives them by kind instead of asking you about every call."
   - "Copy .env.example to .env and set DEVICE_HOST/DEVICE_PORT (never commit .env)."
   - "Try it live: uv run python -m plesty.{module_name} --tcp-port 5555."
 
@@ -20,7 +21,8 @@ analyzer:
 
 experiment:
   - "Implement build_plan() and the step methods in plesty/{module_name}/experiment.py."
-  - "Copy .env.example to .env and set your device endpoints; tune config/default.yaml."
+  - "Name your rig in the RIG of plesty/{module_name}/__main__.py: one sub-device per instrument, listing the operations you call on it — the preflight checks them before the first step."
+  - "Copy .env.example to .env and set one <NAME>_ADDRESS per sub-device (plus PLESTY_DATA_DIR/PLESTY_DATA_MOUNT if runs go to the shared disk); tune config/default.yaml."
   - "Preview the plan without hardware: uv run python -m plesty.{module_name} --dry-run."
 
 verify:

{plesty_sdk-0.3.3 → plesty_sdk-0.3.5.dev1}/plesty/sdk/assets/templates/extras/device/base_device.py

@@ -5,7 +5,10 @@
 
 """Base device implementation template."""
 
-from plesty.lib.device.base_device_sync import BaseDeviceSyncModel
+from plesty.lib.device.base_device_sync import BaseDeviceSyncModel, expose_to_api
+
+# Re-exported so device.py imports both from here, as the hub modules do.
+__all__ = ["BaseDevice", "expose_to_api"]
 
 
 class BaseDevice(BaseDeviceSyncModel):

plesty_sdk-0.3.5.dev1/plesty/sdk/assets/templates/extras/device/device.py

@@ -0,0 +1,60 @@
+# SPDX-FileCopyrightText: 2025-2026 Plesty Development Team
+# SPDX-FileContributor: Yunshuang Yuan
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+"""Concrete device implementation."""
+
+from .base_device import BaseDevice, expose_to_api
+
+
+class Device(BaseDevice):
+    """Concrete device class extending BaseDevice with custom functionality."""
+
+    def __init__(
+        self,
+        id: str,
+        host: str | None = None,
+        port: int | None = None,
+        param_schema=None,
+        op_schema=None,
+    ) -> None:
+        """Initialize the device with an id, connection info, and optional schemas."""
+        super().__init__(id, op_schema=op_schema, param_schema=param_schema)
+        ## Connection credentials (from the environment via EnvSettings); use them
+        ## in `connect()` to reach the hardware.
+        self.host = host
+        self.port = port
+        ## Device-specific initialization can be added here
+
+    @expose_to_api
+    def custom_method(self) -> dict:
+        """Implement a custom device-specific operation.
+
+        Custom methods are not required by the base model; they add workflows
+        on top of the registered configuration parameters and schema
+        operations. `@expose_to_api` is what puts one on the describe
+        endpoint, so a remote client and the field test can call it. Bare, it
+        declares a `read`: the operation answers and changes nothing.
+
+        Returns:
+            Whatever the operation reports; a mapping keeps the reply
+            self-describing over the wire.
+        """
+        ## Device-specific logic can be added here
+        return {}
+
+    ## An operation that acts on the world declares what it does, so the field
+    ## test (`plesty init field-test`) can drive it unattended instead of
+    ## asking about every call:
+    ##
+    ##     @expose_to_api(kind="motion", position_key="position", step=1.0)
+    ##     def move_absolute(self, position: float) -> float: ...
+    ##
+    ##     @expose_to_api(kind="lifecycle")
+    ##     def home(self) -> bool: ...
+    ##
+    ## Kinds are read | motion | acquire | lifecycle | control | configure. A
+    ## motion is driven one `step` out from what `position_key` reports and put
+    ## back, a lifecycle operation runs once, a control operation once at rest
+    ## after the motions, and a configure operation is never called.

{plesty_sdk-0.3.3 → plesty_sdk-0.3.5.dev1}/plesty/sdk/assets/templates/extras/experiment/experiment.py

@@ -1,9 +1,20 @@
+# SPDX-FileCopyrightText: 2026 Plesty Development Team
+# SPDX-FileContributor: Yunshuang Yuan
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
 """Experiment implementation.
 
 Replace the example step operation with real measurement logic. The plan/
 journal/resume lifecycle is inherited from ``plesty.lib.experiment`` — keep
 ``build_plan()`` deterministic and device-free so interrupted runs can be
 resumed with ``run(resume=<run_id>)``.
+
+Each run owns a directory under ``run_root`` holding ``plan.json``,
+``journal.jsonl``, one ``records.jsonl`` line per completed step, and the
+blobs those records reference. Live views over the same records are written
+against ``plesty.lib.monitor`` (``Viz``), so watching a run needs nothing
+from this file.
 """
 
 from pathlib import Path
@@ -27,7 +38,7 @@ class Experiment(BaseExperiment):
         self,
         devices: Optional[CompositeDevice] = None,
         config: Optional[dict[str, Any]] = None,
-        run_root: str | Path = "runs",
+        run_root: str | Path | None = None,
         **kwargs: Any,
     ) -> None:
         """Initialize the experiment.
@@ -39,9 +50,12 @@ class Experiment(BaseExperiment):
             config:   Measurement configuration (tuning values, no
                       credentials); recorded in the plan.
             run_root: Directory under which each run creates its checkpoint
-                      directory.
+                      directory. ``None`` takes ``PLESTY_DATA_MOUNT`` from the
+                      environment — runs land on the shared disk — and falls
+                      back to ``runs`` when no share is configured.
             **kwargs: Forwarded to the base ``Experiment`` (``name``,
-                      ``max_retries``, ``retry_sleep``).
+                      ``max_retries``, ``retry_sleep``, ``data_dir``,
+                      ``data_mount``).
         """
         super().__init__(devices=devices, run_root=run_root, **kwargs)
         self.config: dict[str, Any] = dict(config or {})
@@ -62,15 +76,25 @@ class Experiment(BaseExperiment):
         """Example step operation — replace with a real measurement.
 
         Access instruments through ``self.devices``. Return a result (e.g. a
-        ``plesty.lib.data.PlestyArray``) to have it persisted to the run's
-        ``data/`` directory; returning ``None`` skips persistence.
+        ``plesty.lib.data.PlestyArray``) to have it appended to the run's
+        ``records.jsonl`` (large arrays land beside it under ``data/``);
+        returning ``None`` records nothing for the step. A device that writes
+        its own files writes them to ``self.raw_dir`` on the shared disk —
+        never back over the network.
 
         Args:
             x: Example sweep position taken from the step params.
         """
 
     async def setup(self) -> None:
-        """Prepare instruments before the first step; extend as needed."""
+        """Prepare instruments before the first step; extend as needed.
+
+        The inherited setup connects the composite and preflights it — every
+        remote sub-device must expose the methods its ``requires`` names and
+        answer ``identity()``, or ``RigNotReadyError`` stops the run before
+        anything is measured. Route the writing devices here, e.g.
+        ``self.devices.set_data_path(self.raw_dir, devices=["cam"])``.
+        """
         await super().setup()
 
     async def teardown(self) -> None: