labcode 0.8.0__tar.gz → 0.10.0__tar.gz

{labcode-0.8.0 → labcode-0.10.0}/.github/workflows/ci.yml

@@ -22,6 +22,21 @@ jobs:
       - run: pip install -e ".[test]"
       - run: pytest
 
+  test-export:
+    # `lc export` is the optional extra `labcode[export]`, so the matrix above runs
+    # without it and tests the "not installed" answer. This installs it the way a
+    # user would -- through the extra -- and tests that `lc export` reaches it.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[test,export]"
+      - run: python -c "import ofplang.export"
+      - run: pytest tests/test_cli.py
+
   lint:
     runs-on: ubuntu-latest
     steps:

labcode-0.10.0/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+What changed in each release of labcode, for someone deciding whether to upgrade. The
+specification the section numbers refer to is [`docs/SPECIFICATIONS.md`](docs/SPECIFICATIONS.md).
+
+Releases before 0.9.0 are described in the messages of their `Release vX.Y.Z` commits
+(`git log --grep '^Release v'`).
+
+## 0.10.0 — 2026-10-05
+
+labcode runs a protocol repeated over every plate (`map` / `fold`), and stops making up
+a value a script did not compute.
+
+### Added
+
+- **`map` and `fold`** run, as ofplang-schedule 0.13 expands them and ofplang-run 0.13
+  executes the expansion. An **Array of Objects** at the run boundary is one Object per
+  element: its `view` is a list of views, one per spot, and each element gets its own
+  `_id`, keyed by the element (`plates[1]`, §4.3). An invocation's node path carries its
+  iteration index, and so do the keys of what it creates.
+- **What a run made up, it says** (`lc run` prints each as `lc run: warning: ...`):
+  - `entry_input_defaulted` — a boundary view written in part, or not at all: the
+    declared fields it left out run on their type's default (§4.2). Once per Object.
+  - `output_view_defaulted` — a script that did not return an Object it created: the
+    view runs on its type's default (§1.2). Once per process and port.
+  - `_id` is never reported; minting it is labcode's identity, not a default.
+
+### Changed — may need your attention
+
+- **A script must return every Pure Data output it declares** (§1.2). Until now one left
+  out took its type's default — `return {}` from a `read` gave `od: 0.0`, a reading
+  nothing took. It now fails the operation (`script_output_names`), as v0 §22.2 does. An
+  Object output may still be left out: a mapped one is carried, a created one gets its
+  default view (reported).
+- **A process with no script anywhere that declares a Pure Data output is refused** by
+  `lc run` before anything runs (§2): a no-op can compute nothing, so every run of it
+  would fail. One with only Object outputs still runs as a no-op, with the warning it
+  always had. A process with a script on some modes only fails if a mode without one is
+  chosen.
+- **A boundary view that is not a mapping** (or, for an Array, not a list of them) is
+  refused. It used to be replaced by an empty view without a word.
+- **An Object mapped from an input with no `_id`** fails the operation
+  (`missing_object_id`). No run can reach this; it is there to catch a broken invariant
+  early.
+- A v0 §22 workflow script in a language other than Python fails the operation
+  (`script_language`) instead of running as a no-op.
+- Requires ofplang-validate 0.3, ofplang-schedule 0.13 and ofplang-run 0.13
+  (specification revision 0.4).
+
+`lc export` is unchanged; drawing a run that has `map` / `fold` invocations in it is not
+yet supported there.
+
+## 0.9.0 — 2026-09-28
+
+labcode can now drive a lab over **LADS OPC UA** as well as SiLA2, and gains `lc export`.
+Both are optional extras; nothing changes for an environment that uses neither.
+
+### Added
+
+- **`flavor: lads`** — a script that is the commands alone, handed its LADS OPC UA clients
+  as a `sila2` script is handed SiLA2 ones (§1.10).
+  - A connection may say `kind: lads`, and may name the `device` and functional `unit` on the
+    server; left out, each is the only one there is (§1.5).
+  - The script sees `lads_clients` / `lads_client`: one functional unit per machine, with the
+    program runs, state-machine methods, cover movements and set-points LADS defines, each
+    waiting for what it starts, and `.raw` for the asyncua client itself.
+  - `labcode.lads_commands` holds the waits: a program run to its result, a state machine to
+    settle (§1.10.1). A timeout fails the operation and aborts nothing, as SiLA2's does.
+  - A script speaks one protocol. An operation may hold machines of both kinds, but a script
+    commands only its own flavor's; reaching for the other kind says why
+    (`lads_other_protocol` / `sila2_other_protocol`).
+  - The client library is the `lads` extra (`asyncua`). labcode imports it only when a `lads`
+    script connects.
+- **`lc export`** — forwards to [ofplang-export](https://github.com/ofplang/export)'s CLI
+  unchanged, as `lc validate` and `lc schedule` do. `lc export view plan.yaml -o plan.html`
+  writes the workflow and its plan as one self-contained HTML file. It is the `export` extra;
+  without it `lc export` names the extra and exits 2.
+- **LADS examples** — `lads_seal.env.yaml` and `lads_plate_cycle.env.yaml` run the
+  `sila2_seal` and `sila2_plate_cycle` workflows unchanged, with every machine reached over
+  LADS. `run_all_lads_examples.py` runs both against the reference lab,
+  [ofplang/mocklab](https://github.com/ofplang/mocklab).
+
+### Changed
+
+- `SPECIFICATIONS.md` moved to `docs/SPECIFICATIONS.md`.
+- The `ofplang-schedule` cap is `<0.13`, admitting schedule 0.12. The floor is unchanged.
+- The front door checks a connecting script's connection **per kind**. A `sila2` or `lads`
+  script needs a machine of its own kind. An endpoint of the other kind draws a warning, as
+  an endpoint with no connection does. Messages that named only `sila2` now name the flavor.
+- What a connecting flavor needs (planning the clients, holding them for one operation,
+  generating the wrapper) moved from `labcode.sila2` into `labcode.connections`. The `sila2`
+  flavor's behaviour, messages and reason codes are unchanged.
+
+### Fixed
+
+- `examples/preflight_sila2_env.py` treated every declared connection as SiLA2. An
+  environment with a LADS machine would have reported it as a failing SiLA2 server. It now
+  checks SiLA2 machines only and lists the others as not checked.
+
+### Documentation
+
+- The reference lab is named by its current name, ofplang/mocklab (formerly
+  ofplang-sila2-backend), and the examples record the commit they were last verified against.
+- Section references written before probing took §1.6 pointed at the wrong sections and are
+  corrected. The `labcode.sila2_commands` section is numbered §1.7.1.
+- The README lists the optional extras, lists every example, and links by absolute URL, so the
+  links also work on PyPI.

{labcode-0.8.0 → labcode-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labcode
-Version: 0.8.0
+Version: 0.10.0
 Summary: labcode -- a dialect wrapper over the Object-Flow Programming Language toolchain
 Author-email: Kazunari Kaizu <kwaizu@gmail.com>
 License-Expression: MIT
@@ -20,21 +20,27 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: ofplang-validate<0.3,>=0.2
-Requires-Dist: ofplang-schedule<0.12,>=0.9
-Requires-Dist: ofplang-run<0.13,>=0.11
+Requires-Dist: ofplang-validate<0.4,>=0.3
+Requires-Dist: ofplang-schedule<0.14,>=0.13
+Requires-Dist: ofplang-run<0.14,>=0.13
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "test"
 Requires-Dist: opentelemetry-instrumentation-grpc[instruments]>=0.41b0; extra == "test"
+Requires-Dist: asyncua>=2.0; extra == "test"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: ruff>=0.16; extra == "dev"
 Requires-Dist: mypy>=1.11; extra == "dev"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "dev"
 Requires-Dist: opentelemetry-instrumentation-grpc[instruments]>=0.41b0; extra == "dev"
+Requires-Dist: asyncua>=2.0; extra == "dev"
 Provides-Extra: sila2
 Requires-Dist: sila2>=0.14; extra == "sila2"
+Provides-Extra: lads
+Requires-Dist: asyncua>=2.0; extra == "lads"
+Provides-Extra: export
+Requires-Dist: ofplang-export<0.2,>=0.1; extra == "export"
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
@@ -55,6 +61,7 @@ ofplang toolchain and exposes it under a single command:
 lc validate ...   # check a workflow is well-formed portable v0
 lc schedule ...   # compute a schedule for a workflow
 lc run ...        # execute a workflow on the labcode backend
+lc export ...     # write documents out for people to read (optional: labcode[export])
 ```
 
 labcode is where a site-specific dialect and a custom runner (real lab hardware)
@@ -63,7 +70,7 @@ forward to the ofplang siblings unchanged; **`lc run` is the labcode dialect's o
 runner**: it drives the workflow on the labcode backend, running each device
 operation's script — supplied in the environment as an `x-labcode.script` extension
 on a process mode — out-of-process on a wall clock, so a long-running real operation
-never blocks the replan loop. See [`SPECIFICATIONS.md`](SPECIFICATIONS.md) for the
+never blocks the replan loop. See [`docs/SPECIFICATIONS.md`](https://github.com/ofplang/labcode/blob/main/docs/SPECIFICATIONS.md) for the
 `x-labcode` extension.
 
 ```yaml
@@ -94,7 +101,25 @@ sibling packages unchanged; `lc run` is this package's own runner, built on them
 - [`ofplang-run`](https://github.com/ofplang/run) — the runner / simulator
 
 The language is defined in the [ofplang/spec](https://github.com/ofplang/spec)
-repository, and what labcode adds to it in [`SPECIFICATIONS.md`](SPECIFICATIONS.md).
+repository, and what labcode adds to it in [`docs/SPECIFICATIONS.md`](https://github.com/ofplang/labcode/blob/main/docs/SPECIFICATIONS.md).
+
+Talking to instruments, recording a run and exporting documents are optional, each an extra
+installed into the interpreter that runs `lc` (labcode runs every script with that same
+interpreter):
+
+| extra | brings | needed for |
+|---|---|---|
+| `sila2` | the `sila2` client library | `flavor: sila2` scripts (§1.7) |
+| `lads` | `asyncua`, an OPC UA client | `flavor: lads` scripts (§1.10) |
+| `otel` | the OpenTelemetry SDK and exporter | `lc run --trace` |
+| `export` | [`ofplang-export`](https://github.com/ofplang/export) | `lc export view` — the workflow and its plan as one self-contained HTML file |
+
+```sh
+pip install 'labcode[sila2,lads]'
+```
+
+Without an extra, labcode still runs; only what needs it — a script of that flavor,
+`--trace`, or `lc export` — fails, with a message naming the extra to install.
 
 What `lc run` brings of its own, beyond dispatching:
 
@@ -114,12 +139,18 @@ What `lc run` brings of its own, beyond dispatching:
 - **object identity** — the reserved `_id` view key is declared on Object types and minted
   per object, so a physical thing can be followed through a run (§4).
 - **`flavor: sila2`** — a script that speaks SiLA2 gets its clients opened around it
-  (§1.7). The client library itself is the `sila2` extra: `pip install labcode[sila2]`,
-  installed into whichever interpreter runs the scripts.
+  (§1.7). The client library is the `sila2` extra.
+- **`flavor: lads`** — the same for LADS OPC UA: a script is handed one LADS functional
+  unit per machine, already connected, with the program runs, state-machine methods and
+  cover movements LADS defines and the waits each needs (§1.10). A connection may name the
+  `device` and `unit` on the server, or leave them to be found. A script speaks one protocol;
+  an operation holding machines of both kinds commands only its own flavor's. The client
+  library is the `lads` extra.
 - **recording a run** — with `--trace`, what the run did is recorded as OpenTelemetry
   traces: one trace per run, a span per operation, and — measured inside the process that
   issued them — a span per SiLA2 connection, per command, and per gRPC call each of those
-  made. Off by default; the extra is `pip install labcode[otel]`.
+  made. Off by default; it needs the `otel` extra. A `lads` operation is
+  recorded as its span alone for now.
 
 ## Usage
 
@@ -133,9 +164,11 @@ lc --version
 
 `lc` can also be run as a module: `python -m labcode <command> ...`.
 
-`lc validate` and `lc schedule` are the ofplang siblings' own CLIs unchanged, so their
-options are documented in those repositories. `lc run` is this package's own, and is
-described below.
+`lc validate`, `lc schedule` and `lc export` are the ofplang siblings' own CLIs unchanged,
+so their options are documented in those repositories — `lc export view plan.yaml -o
+plan.html`, for one, writes the workflow and its plan as a single HTML file
+([ofplang/export](https://github.com/ofplang/export); needs `labcode[export]`). `lc run` is
+this package's own, and is described below.
 
 ### `lc run`
 
@@ -267,9 +300,10 @@ duration and nothing is commanded. That is a real thing to write (an operator to
 stock up while the schedule waits for them) and an easy one to write by accident, so it is
 warned about.
 
-`flavor: sila2` is **refused on a refill route** for now: a sila2 script is handed clients,
-and which machine's clients a refill should receive — the replenisher's, or both ends' as a
-transport may ask for — is not settled. Use `python`.
+`flavor: sila2` and `flavor: lads` are **refused on a refill route** for now: such a script
+is handed clients, and which machine's clients a refill should receive — the replenisher's,
+or both ends' as a transport may ask for — is not settled. Use `raw` (the default), which may
+connect for itself.
 
 A refill holds the device it fills *and* the replenisher filling it, so it never overlaps
 the work it feeds. It is recorded (`--trace`) as a `replenishment` span naming both
@@ -332,11 +366,22 @@ OpenTelemetry's own export timeout allows: labcode sets no timeout of its own, s
 
 ## Examples
 
-[`examples/`](examples/README.md) holds three worked runs: `plate_line`, an
-Object-bearing line driven entirely by environment scripts and runnable with no
-hardware, and `sila2_seal` and `sila2_plate_cycle`, which drive the reference lab's
-SiLA2 servers for real. `sila2_seal` also walks through what a run does when a
-machine stops answering — before an operation, and in the middle of one.
+[`examples/`](https://github.com/ofplang/labcode/blob/main/examples/README.md) holds worked runs of two kinds.
+
+- **Runnable with nothing but Python** — `plate_line`, an Object-bearing line driven entirely
+  by environment scripts, and `shared_bench`, two jobs sharing one laboratory (`--jobs`).
+- **Against real instrument servers** — `sila2_seal` (one instrument), `sila2_plate_cycle` (a
+  circuit through four instruments and an arm) and `sila2_plate_cycle_no_atc` (the same
+  circuit on a bench without a thermal cycler), over SiLA2; and `lads_seal` and
+  `lads_plate_cycle`, the first two workflows unchanged with every machine reached over LADS
+  OPC UA instead. `sila2_seal` also walks through what a run does when a machine stops
+  answering — before an operation, and in the middle of one.
+
+The servers they are verified against are the reference lab,
+[ofplang/mocklab](https://github.com/ofplang/mocklab): mock instruments serving SiLA2 or LADS
+OPC UA by Docker Compose profile, over one simulated world. It is a reference, not a
+requirement — the environments speak plain SiLA2 and LADS, so a bench is a change of hosts and
+ports. `run_all_sila2_examples.py` and `run_all_lads_examples.py` run each set as a check.
 
 ## License
 

{labcode-0.8.0 → labcode-0.10.0}/README.md

@@ -11,6 +11,7 @@ ofplang toolchain and exposes it under a single command:
 lc validate ...   # check a workflow is well-formed portable v0
 lc schedule ...   # compute a schedule for a workflow
 lc run ...        # execute a workflow on the labcode backend
+lc export ...     # write documents out for people to read (optional: labcode[export])
 ```
 
 labcode is where a site-specific dialect and a custom runner (real lab hardware)
@@ -19,7 +20,7 @@ forward to the ofplang siblings unchanged; **`lc run` is the labcode dialect's o
 runner**: it drives the workflow on the labcode backend, running each device
 operation's script — supplied in the environment as an `x-labcode.script` extension
 on a process mode — out-of-process on a wall clock, so a long-running real operation
-never blocks the replan loop. See [`SPECIFICATIONS.md`](SPECIFICATIONS.md) for the
+never blocks the replan loop. See [`docs/SPECIFICATIONS.md`](https://github.com/ofplang/labcode/blob/main/docs/SPECIFICATIONS.md) for the
 `x-labcode` extension.
 
 ```yaml
@@ -50,7 +51,25 @@ sibling packages unchanged; `lc run` is this package's own runner, built on them
 - [`ofplang-run`](https://github.com/ofplang/run) — the runner / simulator
 
 The language is defined in the [ofplang/spec](https://github.com/ofplang/spec)
-repository, and what labcode adds to it in [`SPECIFICATIONS.md`](SPECIFICATIONS.md).
+repository, and what labcode adds to it in [`docs/SPECIFICATIONS.md`](https://github.com/ofplang/labcode/blob/main/docs/SPECIFICATIONS.md).
+
+Talking to instruments, recording a run and exporting documents are optional, each an extra
+installed into the interpreter that runs `lc` (labcode runs every script with that same
+interpreter):
+
+| extra | brings | needed for |
+|---|---|---|
+| `sila2` | the `sila2` client library | `flavor: sila2` scripts (§1.7) |
+| `lads` | `asyncua`, an OPC UA client | `flavor: lads` scripts (§1.10) |
+| `otel` | the OpenTelemetry SDK and exporter | `lc run --trace` |
+| `export` | [`ofplang-export`](https://github.com/ofplang/export) | `lc export view` — the workflow and its plan as one self-contained HTML file |
+
+```sh
+pip install 'labcode[sila2,lads]'
+```
+
+Without an extra, labcode still runs; only what needs it — a script of that flavor,
+`--trace`, or `lc export` — fails, with a message naming the extra to install.
 
 What `lc run` brings of its own, beyond dispatching:
 
@@ -70,12 +89,18 @@ What `lc run` brings of its own, beyond dispatching:
 - **object identity** — the reserved `_id` view key is declared on Object types and minted
   per object, so a physical thing can be followed through a run (§4).
 - **`flavor: sila2`** — a script that speaks SiLA2 gets its clients opened around it
-  (§1.7). The client library itself is the `sila2` extra: `pip install labcode[sila2]`,
-  installed into whichever interpreter runs the scripts.
+  (§1.7). The client library is the `sila2` extra.
+- **`flavor: lads`** — the same for LADS OPC UA: a script is handed one LADS functional
+  unit per machine, already connected, with the program runs, state-machine methods and
+  cover movements LADS defines and the waits each needs (§1.10). A connection may name the
+  `device` and `unit` on the server, or leave them to be found. A script speaks one protocol;
+  an operation holding machines of both kinds commands only its own flavor's. The client
+  library is the `lads` extra.
 - **recording a run** — with `--trace`, what the run did is recorded as OpenTelemetry
   traces: one trace per run, a span per operation, and — measured inside the process that
   issued them — a span per SiLA2 connection, per command, and per gRPC call each of those
-  made. Off by default; the extra is `pip install labcode[otel]`.
+  made. Off by default; it needs the `otel` extra. A `lads` operation is
+  recorded as its span alone for now.
 
 ## Usage
 
@@ -89,9 +114,11 @@ lc --version
 
 `lc` can also be run as a module: `python -m labcode <command> ...`.
 
-`lc validate` and `lc schedule` are the ofplang siblings' own CLIs unchanged, so their
-options are documented in those repositories. `lc run` is this package's own, and is
-described below.
+`lc validate`, `lc schedule` and `lc export` are the ofplang siblings' own CLIs unchanged,
+so their options are documented in those repositories — `lc export view plan.yaml -o
+plan.html`, for one, writes the workflow and its plan as a single HTML file
+([ofplang/export](https://github.com/ofplang/export); needs `labcode[export]`). `lc run` is
+this package's own, and is described below.
 
 ### `lc run`
 
@@ -223,9 +250,10 @@ duration and nothing is commanded. That is a real thing to write (an operator to
 stock up while the schedule waits for them) and an easy one to write by accident, so it is
 warned about.
 
-`flavor: sila2` is **refused on a refill route** for now: a sila2 script is handed clients,
-and which machine's clients a refill should receive — the replenisher's, or both ends' as a
-transport may ask for — is not settled. Use `python`.
+`flavor: sila2` and `flavor: lads` are **refused on a refill route** for now: such a script
+is handed clients, and which machine's clients a refill should receive — the replenisher's,
+or both ends' as a transport may ask for — is not settled. Use `raw` (the default), which may
+connect for itself.
 
 A refill holds the device it fills *and* the replenisher filling it, so it never overlaps
 the work it feeds. It is recorded (`--trace`) as a `replenishment` span naming both
@@ -288,11 +316,22 @@ OpenTelemetry's own export timeout allows: labcode sets no timeout of its own, s
 
 ## Examples
 
-[`examples/`](examples/README.md) holds three worked runs: `plate_line`, an
-Object-bearing line driven entirely by environment scripts and runnable with no
-hardware, and `sila2_seal` and `sila2_plate_cycle`, which drive the reference lab's
-SiLA2 servers for real. `sila2_seal` also walks through what a run does when a
-machine stops answering — before an operation, and in the middle of one.
+[`examples/`](https://github.com/ofplang/labcode/blob/main/examples/README.md) holds worked runs of two kinds.
+
+- **Runnable with nothing but Python** — `plate_line`, an Object-bearing line driven entirely
+  by environment scripts, and `shared_bench`, two jobs sharing one laboratory (`--jobs`).
+- **Against real instrument servers** — `sila2_seal` (one instrument), `sila2_plate_cycle` (a
+  circuit through four instruments and an arm) and `sila2_plate_cycle_no_atc` (the same
+  circuit on a bench without a thermal cycler), over SiLA2; and `lads_seal` and
+  `lads_plate_cycle`, the first two workflows unchanged with every machine reached over LADS
+  OPC UA instead. `sila2_seal` also walks through what a run does when a machine stops
+  answering — before an operation, and in the middle of one.
+
+The servers they are verified against are the reference lab,
+[ofplang/mocklab](https://github.com/ofplang/mocklab): mock instruments serving SiLA2 or LADS
+OPC UA by Docker Compose profile, over one simulated world. It is a reference, not a
+requirement — the environments speak plain SiLA2 and LADS, so a bench is a change of hosts and
+ports. `run_all_sila2_examples.py` and `run_all_lads_examples.py` run each set as a check.
 
 ## License