labcode 0.3.0__tar.gz → 0.3.1__tar.gz

{labcode-0.3.0 → labcode-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labcode
-Version: 0.3.0
+Version: 0.3.1
 Summary: labcode -- a dialect wrapper over the Object-Flow Programming Language toolchain
 Author-email: Kazunari Kaizu <kwaizu@gmail.com>
 License-Expression: MIT
@@ -21,8 +21,8 @@ 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.4,>=0.3
-Requires-Dist: ofplang-run<0.5,>=0.4
+Requires-Dist: ofplang-schedule<0.6,>=0.5
+Requires-Dist: ofplang-run<0.7,>=0.6
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "test"

{labcode-0.3.0 → labcode-0.3.1}/SPECIFICATIONS.md

@@ -55,7 +55,9 @@ still validates and schedules as plain v0. Only labcode interprets it.
   - `endpoints` (**transport routes only**, optional, default `false`): MUST be a boolean —
     whether this move is also given clients for the devices at either **end** of its route,
     not only its `transporter` (§1.7). A process mode may not declare it: a mode's machines
-    are the ones it lists.
+    are the ones it lists. A `sila2` script on a route with **no transporter** (§1.3) MUST
+    declare it `true`: the ends are then the only machines there are, and a script is never
+    given a machine it did not ask for.
 
 **Unknown keys are an error** — in `x-labcode` at every position, and in the mappings it
 holds. A key this version does not know is either a typo or a feature it does not have;
@@ -124,6 +126,24 @@ output is verified. Success is "it ran without raising"; an exception is a grace
 A route with no `x-labcode.script` runs as a plain timed move — the runner's material
 bookkeeping only, with no device command (a warned no-op for a real move, from != to).
 
+**A route with no transporter.** An environment may declare a route that needs no
+transporter at all, by writing `transporter: null` (ofplang-schedule §4.6 / §5.4) — a
+device shifting material between its own spots, a chute. The plan then reports the move
+with `transporter: null` too, and this dialect matches it like any other: routes are keyed
+by `(transporter, from, to)`, so a null one matches a null one, and the script's
+`transporter` local is `None`.
+
+Such a move is performed by the **devices at either end of the route** — for a move within
+one device, that device. So a `flavor: sila2` script on such a route must declare
+**`endpoints: true`** (§1.6), and at least one of those devices must declare a
+`connection`; either missing is a front-door error. The `endpoints` request is *required*
+rather than inferred: it is the author's statement of which machines the script drives, and
+reading it for them would decide that on exactly the routes where it matters most. A `raw`
+script, or no script at all, is unaffected — neither is handed clients.
+
+`sila2_client` is then the first machine connected to, which is the **source device**: the
+one performing the move, exactly as it is the transporter on a carried route (§1.7).
+
 ### 1.4 `x-labcode` on a replenishment route
 
 An environment `replenishments[]` route may carry an `x-labcode` with a `script`: the
@@ -211,14 +231,18 @@ a script uses it.
 - a mode script with `flavor: sila2` requires **at least one** of that mode's `devices[]`
   to declare a `connection`;
 - a transport script with `flavor: sila2` requires that route's `transporter` to declare
-  one.
+  one — or, on a route with **no transporter** (§1.3), requires `endpoints: true` and at
+  least one of the devices at its ends to declare one, those being the machines that
+  perform such a move.
 
 A transport that declares `endpoints: true` is also handed the clients of the devices at
 either **end** of its route (§1.7), but those are *not* required to declare a `connection`:
 a route through a plain holding location is ordinary, and the end without an address is
 simply not connected to (a **warning** when *neither* end has one, since then the request
-does nothing). The transporter is the one that must be reachable, because it is the machine
-that does the moving — and the one `sila2_client` names. Asking a `raw` script for endpoint
+does nothing — an **error** on a route with no transporter, which has nothing else to
+drive). The transporter is the one that must be reachable, because it is the machine that
+does the moving — and the one `sila2_client` names; where there is none, that is the source
+device, for the same reason. Asking a `raw` script for endpoint
 clients is an **error**: a raw script is handed no clients at all, so the request cannot be
 honoured.
 
@@ -320,8 +344,8 @@ of the input ports of §1.2 (or the transport locals of §1.3), the code sees:
 
 | name | meaning |
 |---|---|
-| `sila2_clients` | the clients by **machine id**, in the order the operation names its machines: a mode's `devices[]` order, or — for a transport — its `transporter`, followed by the devices at either **end of the route** when it declares `endpoints: true`. Named, not held: a mode declaring `device_access: false` (ofplang-schedule §4.4.2) rests on its devices rather than occupying them, and its script is still handed their clients |
-| `sila2_client` | the first of them — for a transport always its `transporter`; the one name a single-machine operation needs |
+| `sila2_clients` | the clients by **machine id**, in the order the operation names its machines: a mode's `devices[]` order, or — for a transport — its `transporter` (absent on a route that has none, §1.3), followed by the devices at either **end of the route** when it declares `endpoints: true`. Named, not held: a mode declaring `device_access: false` (ofplang-schedule §4.4.2) rests on its devices rather than occupying them, and its script is still handed their clients |
+| `sila2_client` | the first of them — for a transport its `transporter`, or the **source device** on a route with none (§1.3); the one name a single-machine operation needs |
 
 ```yaml
 x-labcode:
@@ -350,6 +374,12 @@ x-labcode:
   property of the move, not of the lab. A route that does not ask still *holds* both ends, so
   reaching for one is answered with what to add rather than with silence.
 
+  On a route with **no transporter** (§1.3) a `sila2` script must ask: the ends are the only
+  machines there are, so not asking leaves nothing to open, and the front door says so rather
+  than letting the move fail when it runs. It is still asked for, not assumed — which
+  machines a script drives is the author's to state, and nowhere more so than where the
+  machine doing the moving is also the one holding the material.
+
   ```yaml
   transports:
     - transporter: arm

{labcode-0.3.0 → labcode-0.3.1}/labcode/backend.py

@@ -57,6 +57,7 @@ from labcode.extension import (
     script_endpoints,
     script_flavor,
     spot_device,
+    transport_label,
     transporter_connections,
 )
 from labcode.idgen import DEFAULT_ID_GENERATOR, IdGenerator
@@ -245,8 +246,7 @@ def make_transport_resolver(environment: dict) -> Callable:
             code = _flavored(
                 code, script,
                 _transport_machines(transport, transporters, devices, script),
-                f"transport {transporter!r} "
-                f"{transport.get('from')} -> {transport.get('to')}",
+                transport_label(transport),
             )
         routes[key] = code
 

{labcode-0.3.0 → labcode-0.3.1}/labcode/dialect.py

@@ -59,8 +59,11 @@ from labcode.extension import (
     parse_connection,
     parse_op_timeout,
     parse_probe,
+    route_transporter,
+    script_endpoints,
     script_flavor,
     spot_device,
+    transport_label,
     unknown_key_messages,
 )
 from labcode.objectid import RESERVED_ID, reserved_collisions
@@ -464,11 +467,8 @@ def _validate_replenishments(environment: dict, errors: list, warnings: list) ->
             )
 
 
-def _transport_label(transport: dict) -> str:
-    return (
-        f"transport {transport.get('transporter')!r} "
-        f"{transport.get('from')} -> {transport.get('to')}"
-    )
+# `transport_label` (extension.py) is shared with the backend, so the same route is named
+# the same way in a front-door diagnostic and in a failing operation.
 
 
 def _validate_transports(
@@ -485,7 +485,7 @@ def _validate_transports(
     for transport in environment.get("transports") or []:
         if not isinstance(transport, dict):
             continue
-        label = _transport_label(transport)
+        label = transport_label(transport)
         extension = transport.get(EXTENSION_KEY)
         if extension is None:
             if transport.get("from") != transport.get("to"):  # a real move
@@ -505,7 +505,9 @@ def _validate_transports(
             continue
         _check_transport_endpoints(transport, script, label, devices, errors, warnings)
         if script_flavor(script) == FLAVOR_SILA2:
-            _check_transport_connection(transport, label, transporters, errors)
+            _check_transport_connection(
+                transport, script, label, transporters, devices, errors
+            )
 
 
 def _check_transport_endpoints(
@@ -519,7 +521,12 @@ def _check_transport_endpoints(
     clients at all (§1.6), so the request cannot be honoured and the author expects
     something that will not happen. Asking when neither end has an address is a **warning**
     -- the route still works through its transporter, and an environment written before its
-    instruments have addresses is a legitimate intermediate state (as with `probe`)."""
+    instruments have addresses is a legitimate intermediate state (as with `probe`).
+
+    That last one holds only for a route that *has* a transporter to fall back on. A route
+    with no transporter (§4.6/§5.4) has nothing else to drive, so the same situation is an
+    error there -- reported by `_check_transport_connection`, which is where the rest of
+    that route's connection requirement lives, so that one problem yields one message."""
     endpoints = script.get("endpoints")
     prefix = f"{label}: x-labcode.script.endpoints"
     if endpoints is None:
@@ -535,8 +542,9 @@ def _check_transport_endpoints(
             f"{script_flavor(script)!r}: only a 'sila2' script is handed clients (§1.6)"
         )
         return
-    ends = [spot_device(transport.get(end)) for end in ("from", "to")]
-    named = [device for device in ends if device is not None]
+    if route_transporter(transport) is None:
+        return  # nothing to fall back on; _check_transport_connection reports it as an error
+    named = _route_ends(transport)
     if not any(device in devices.with_connection for device in named):
         warnings.append(
             f"{prefix} is true, but neither end of the route ({', '.join(named)}) declares "
@@ -544,16 +552,54 @@ def _check_transport_endpoints(
         )
 
 
+def _route_ends(transport: dict) -> list[str]:
+    """The devices at either end of a route, named and deduplicated in route order.
+
+    A move within one device names it once: it is one machine, and one client."""
+    ends = [spot_device(transport.get(end)) for end in ("from", "to")]
+    return list(dict.fromkeys(device for device in ends if device is not None))
+
+
 def _check_transport_connection(
-    transport: dict, label: str, transporters: _NodeIndex, errors: list
+    transport: dict,
+    script: dict,
+    label: str,
+    transporters: _NodeIndex,
+    devices: _NodeIndex,
+    errors: list,
 ) -> None:
-    """A `sila2` transport script drives one machine -- the transporter that carries the
-    move -- so that is where its connection has to be."""
-    identifier = transport.get("transporter")
+    """Where a `sila2` transport script's connection has to be.
+
+    Normally the transporter: it is the machine that carries the move, and the one
+    `sila2_client` names.
+
+    A route with **no transporter** (`transporter: null`, ofplang-schedule §4.6/§5.4) is
+    performed by the devices at its ends -- a cycler loading its own block -- so those are
+    what the script must be able to reach. It receives them only if it asks (`endpoints`,
+    §1.6), and it is made to ask rather than being read as asking: `endpoints` is the
+    author's statement of which machines the script drives, and inferring it here would take
+    that statement away from them for exactly the routes where it matters most. The cost of
+    requiring it is one line in the environment; the cost of assuming it is a script handed
+    clients its author never asked for."""
     prefix = f"{label}: x-labcode.script.flavor 'sila2' but"
-    if not isinstance(identifier, str) or not identifier:
-        errors.append(f"{prefix} the route names no transporter")
-    elif identifier not in transporters.declared:
-        errors.append(f"{prefix} transporter {identifier!r} is not declared in transporters[]")
-    elif identifier not in transporters.with_connection:
-        errors.append(f"{prefix} transporter {identifier!r} declares no x-labcode.connection")
+    identifier = route_transporter(transport)
+    if identifier is not None:
+        if identifier not in transporters.declared:
+            errors.append(f"{prefix} transporter {identifier!r} is not declared in transporters[]")
+        elif identifier not in transporters.with_connection:
+            errors.append(f"{prefix} transporter {identifier!r} declares no x-labcode.connection")
+        return
+    if not script_endpoints(script):
+        errors.append(
+            f"{prefix} the route names no transporter and the script does not ask for its "
+            f"endpoint clients; add `endpoints: true` so it is handed the devices at either "
+            f"end of the route, which are what performs a move nothing carries"
+        )
+        return
+    named = _route_ends(transport)
+    if not any(device in devices.with_connection for device in named):
+        errors.append(
+            f"{prefix} the route names no transporter and neither end "
+            f"({', '.join(named)}) declares an x-labcode.connection; there is no machine "
+            f"left for the script to drive"
+        )

{labcode-0.3.0 → labcode-0.3.1}/labcode/extension.py

@@ -315,6 +315,38 @@ def declared_probe(extension: Any) -> dict[str, Any]:
     return declared
 
 
+def route_transporter(transport: Any) -> str | None:
+    """The transporter carrying a transport route, or None when the route names none.
+
+    A route may declare ``transporter: null`` (ofplang-schedule SPECIFICATIONS §4.6/§5.4):
+    the move needs no transporter at all -- a device shifting material between its own
+    spots, a chute -- and is performed by the devices at its ends instead.
+
+    Anything that is not a non-empty string reads as "none" here. A malformed value is the
+    schedule environment validator's to reject, and this must not hold a second opinion
+    about it; what matters at this layer is only whether there is a transporter to drive.
+    """
+    if not isinstance(transport, dict):
+        return None
+    identifier = transport.get("transporter")
+    return identifier if isinstance(identifier, str) and identifier else None
+
+
+def transport_label(transport: Any) -> str:
+    """How a transport route is named in a message: its carrier, then its ends.
+
+    A route with no transporter says so in words. Rendering the absent id would print
+    ``transport None a -> b``, which reads as a defect in the message rather than as a fact
+    about the route -- and this label reaches the user in both a front-door diagnostic and a
+    failing operation, so it is written once and shared.
+    """
+    if not isinstance(transport, dict):
+        transport = {}
+    identifier = route_transporter(transport)
+    who = repr(identifier) if identifier is not None else "(no transporter)"
+    return f"transport {who} {transport.get('from')} -> {transport.get('to')}"
+
+
 def spot_device(spot: Any) -> str | None:
     """The device a qualified spot (``<device>.<spot>``, schedule SPECIFICATIONS §8.2)
     belongs to, or None when there is no name to take.

{labcode-0.3.0 → labcode-0.3.1}/labcode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labcode
-Version: 0.3.0
+Version: 0.3.1
 Summary: labcode -- a dialect wrapper over the Object-Flow Programming Language toolchain
 Author-email: Kazunari Kaizu <kwaizu@gmail.com>
 License-Expression: MIT
@@ -21,8 +21,8 @@ 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.4,>=0.3
-Requires-Dist: ofplang-run<0.5,>=0.4
+Requires-Dist: ofplang-schedule<0.6,>=0.5
+Requires-Dist: ofplang-run<0.7,>=0.6
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "test"

{labcode-0.3.0 → labcode-0.3.1}/labcode.egg-info/requires.txt

@@ -1,6 +1,6 @@
 ofplang-validate<0.3,>=0.2
-ofplang-schedule<0.4,>=0.3
-ofplang-run<0.5,>=0.4
+ofplang-schedule<0.6,>=0.5
+ofplang-run<0.7,>=0.6
 
 [dev]
 pytest>=7.0

labcode-0.3.1/labcode.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.3.1",
+  "distance": 0,
+  "node": "g8ed9be19f0560168d506f98a6e9f54b3e7085aa0",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-09-06"
+}

{labcode-0.3.0 → labcode-0.3.1}/pyproject.toml

@@ -41,9 +41,15 @@ classifiers = [
 # `dispatch_replenishment` seam and the `kind: replenishment` the child harness has to
 # recognise as side-effect only.
 #
-# `ofplang-schedule>=0.2.3` says what this package is tested against rather than what its
-# own code calls -- nothing here calls a scheduler API newer than the in-memory workflow
-# acceptance of 0.1.3. CI resolves the siblings from PyPI, so every run of this suite and
+# `ofplang-schedule>=0.5` is required, not merely tested against: an environment may
+# declare a route that needs no transporter (`transporter: null`, schedule §4.6/§5.4) and
+# this dialect accepts a `sila2` script on one, but an older scheduler refuses the
+# environment with `wrong_type` before there is a plan to run -- and `ofplang-run>=0.6` is
+# where such a move is dispatched rather than rejected.
+#
+# The `>=0.2.3` floor it replaces said what this package was tested against rather than what
+# its own code called -- nothing then called a scheduler API newer than the in-memory
+# workflow acceptance of 0.1.3. CI resolves the siblings from PyPI, so every run of this suite and
 # every real-lab example already happens on it, and run's own floor requires it anyway
 # (an older scheduler reports a running refill free before it is).
 dependencies = [
@@ -55,8 +61,8 @@ dependencies = [
 # bounds cannot protect what is already on PyPI without one, which is why they go
 # in now rather than at the first breakage.
     "ofplang-validate>=0.2,<0.3",
-    "ofplang-schedule>=0.3,<0.4",
-    "ofplang-run>=0.4,<0.5",
+    "ofplang-schedule>=0.5,<0.6",
+    "ofplang-run>=0.6,<0.7",
 ]
 
 [project.urls]

{labcode-0.3.0 → labcode-0.3.1}/tests/test_backend.py

@@ -288,6 +288,40 @@ def test_a_route_within_one_device_connects_to_it_once():
     assert code.count("('cycler',") == 1
 
 
+def _internal_transport_env(**script) -> dict:
+    """A route with no transporter: the cycler shifts the plate between its own spots."""
+    env = _sila2_transport_env("cycler.door", "cycler.block", **script)
+    for entry in env["devices"]:
+        if entry["id"] == "cycler":
+            entry["spots"] = ["door", "block"]
+    env["transports"][0]["transporter"] = None
+    return env
+
+
+def test_a_transporter_less_route_drives_the_devices_at_its_ends():
+    # Nothing carries this move, so `sila2_client` -- "the first of them" -- is the source
+    # device, which is the machine that performs it. Both ends are the same device here, so
+    # it is connected to once.
+    code = make_transport_resolver(_internal_transport_env(endpoints=True))(
+        None, "cycler.door", "cycler.block"
+    )
+    assert code is not None
+    assert "('cycler', '127.0.0.1', 50055, True)" in code
+    assert "('arm'," not in code  # the arm is not on this route and is left alone
+    assert code.count("('cycler',") == 1
+
+
+def test_a_transporter_less_route_is_named_in_words_when_it_fails():
+    # The label reaches the user in a failing operation as well as a diagnostic;
+    # `transporter!r` would render it `transport None a -> b`.
+    env = _internal_transport_env(endpoints=True)
+    for entry in env["devices"]:  # nothing left with an address
+        entry.pop("x-labcode", None)
+    code = make_transport_resolver(env)(None, "cycler.door", "cycler.block")
+    assert code is not None
+    assert "transport (no transporter) cycler.door -> cycler.block" in code
+
+
 TRANSPORT_ENV = {
     "time": {"unit": "second"},
     "devices": [{"id": "s0", "spots": ["core"]}, {"id": "s1", "spots": ["core"]}],

{labcode-0.3.0 → labcode-0.3.1}/tests/test_dialect.py

@@ -700,3 +700,85 @@ def test_an_x_labcode_somewhere_nothing_reads_still_says_where_it_belongs():
     result = validate_dialect({"processes": {}}, env)
     assert not result.ok
     assert any("replenishments[]" in e for e in result.errors)
+
+
+# -- a route with no transporter (ofplang-schedule §4.6/§5.4) -------------------------
+
+
+def _internal_env(script: dict | None = None, *, connected: bool = True) -> dict:
+    """A cycler that shifts the plate between its own two spots: `transporter: null`."""
+    route = {"transporter": None, "from": "cycler.door", "to": "cycler.block"}
+    if script is not None:
+        route["x-labcode"] = {"script": script}
+    env = _transport_env(route)
+    cycler = {"x-labcode": {"connection": CONNECTION}} if connected else {}
+    env["devices"] = [{"id": "cycler", "spots": ["door", "block"], **cycler}]
+    return env
+
+
+def test_a_transporter_less_route_needs_no_script():
+    result = validate_dialect({}, _internal_env())
+    assert result.ok, result.errors
+    assert any("no-op move" in w for w in result.warnings)
+
+
+def test_a_transporter_less_route_takes_a_raw_script():
+    result = validate_dialect(
+        {}, _internal_env({"language": "python", "code": "load_block()"})
+    )
+    assert result.ok, result.errors
+    assert not result.warnings
+
+
+def test_a_transporter_less_sila2_script_must_ask_for_its_endpoints():
+    """There is no transporter to connect to, and `endpoints` is what asks for the ends.
+
+    Read as implicitly asked, the author would be handed clients they never requested for
+    exactly the routes where which machine is driven matters most.
+    """
+    for endpoints in (None, False):
+        script = {"language": "python", "code": "load_block()", "flavor": "sila2"}
+        if endpoints is not None:
+            script["endpoints"] = endpoints
+        result = validate_dialect({}, _internal_env(script))
+        assert not result.ok
+        assert any("add `endpoints: true`" in e for e in result.errors), result.errors
+
+
+def test_a_transporter_less_sila2_script_passes_when_it_asks():
+    result = validate_dialect(
+        {},
+        _internal_env(
+            {"language": "python", "code": "load_block()", "flavor": "sila2",
+             "endpoints": True}
+        ),
+    )
+    assert result.ok, result.errors
+    assert not result.warnings
+
+
+def test_a_transporter_less_route_with_no_reachable_end_is_an_error():
+    """A carried route only *warns* here -- it still works through its transporter.
+
+    This one has no transporter to fall back on, so there is no machine left to drive, and
+    exactly one message says so (not the warning as well).
+    """
+    result = validate_dialect(
+        {},
+        _internal_env(
+            {"language": "python", "code": "load_block()", "flavor": "sila2",
+             "endpoints": True},
+            connected=False,
+        ),
+    )
+    assert not result.ok
+    assert len(result.errors) == 1
+    assert "no machine left for the script to drive" in result.errors[0]
+    assert not result.warnings
+
+
+def test_a_transporter_less_route_is_named_in_words():
+    """`transporter!r` would print `transport None a -> b`, which reads as a broken message."""
+    result = validate_dialect({}, _internal_env())
+    assert any("transport (no transporter) cycler.door -> cycler.block" in w
+               for w in result.warnings), result.warnings

labcode-0.3.0/labcode.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.3.0",
-  "distance": 0,
-  "node": "g0952ede2cf679e2dcbd548d43ed8bd75e6acba0e",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-09-01"
-}