labcode 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

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/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/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/run_cli.py

@@ -65,6 +65,13 @@ def _build_parser() -> argparse.ArgumentParser:
         "--margin", type=int, default=None, metavar="M",
         help="running-task margin for replans (default: the poll interval)",
     )
+    p.add_argument(
+        "--max-transport-legs", type=int, default=1, metavar="N",
+        help="how many transport activities one Object-bearing arc may be carried in "
+             "(default 1: the single hop), joined by relays -- raise it for an "
+             "instrument the transporter reaches at one position only, or a plate "
+             "that has to cross a hand-off station",
+    )
     p.add_argument(
         "--poll-interval", type=int, default=1, metavar="D",
         help="poll every D time units (default 1)",
@@ -329,6 +336,11 @@ def main(argv: Sequence[str] | None = None) -> int:
             running_task_margin=args.margin,
             random_seed=args.seed,
             poll_interval=args.poll_interval,
+            # How many moves one arc may be carried in (schedule SPEC §6.4.1). Passed
+            # through rather than decided here: it is the scheduler's offer, and a real
+            # laboratory is exactly where an instrument reachable from one position
+            # only makes the single hop insufficient.
+            max_transport_legs=args.max_transport_legs,
             # 0 is "no limit" here as it is upstream; the runner spells that None.
             max_ticks=args.max_ticks or None,
             seconds_per_tick=args.seconds_per_tick,

{labcode-0.3.0.dist-info → labcode-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labcode
-Version: 0.3.0
+Version: 0.4.0
 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.9,>=0.8
+Requires-Dist: ofplang-run<0.8,>=0.7
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "test"
@@ -143,7 +143,8 @@ described below.
 lc run <workflow> --env <env>
     [--boundary DOC] [-o OUT] [--boundary-out FILE] [--observation-out FILE]
     [--seconds-per-tick S] [--op-timeout S | --no-op-timeout] [--no-probe]
-    [--ignore-resources] [--trace] [--mission-id ID] [--object-ids seeded|real]
+    [--max-transport-legs N] [--ignore-resources] [--trace] [--mission-id ID]
+    [--object-ids seeded|real]
 ```
 
 - `<workflow>` — the portable v0 workflow: *what* happens.
@@ -176,6 +177,15 @@ lc run <workflow> --env <env>
   else 7200 real seconds. The two forms exclude each other.
 - `--no-probe` — ignore the environment's `x-labcode.probe` policies and treat every
   machine as reachable (§1.6). The documents are still validated.
+- `--max-transport-legs N` — how many transport activities one Object-bearing arc may
+  be carried in (schedule spec §6.4.1), joined by **relay** activities. It is 1 by
+  default: the single hop. Raise it where the transporter cannot reach an instrument
+  from where the plate is — a bench it serves from one position only, or a hand-off
+  station a plate has to cross — and the move is planned as the shortest chain between
+  the two spots instead of being reported unreachable. Only the fewest possible moves
+  are offered, so a plate one move away is never sent round by way of somewhere else.
+  This describes the laboratory's reach rather than tuning the loop, which is why it is
+  here and not among the replan knobs below.
 - `--ignore-resources` — switch the consumable model off. The environment's resource
   declarations are still checked for shape but none is applied, so a bench whose devices
   declare stocks nobody is tracking runs without the boundary saying what they held.

{labcode-0.3.0.dist-info → labcode-0.4.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
 labcode/__init__.py,sha256=jS_lhcLqdu2BfOAq6j5jPTvGNY5M3_1RMJtNRr3ABp4,79
 labcode/__main__.py,sha256=T5DM7E3tdcuKP4oQ7JacBP4Mi-VmujWueJvB9yCIQTc,252
 labcode/_child.py,sha256=dXsOyvX9J39-G9Y5XuXsT0Cp-gzZ6v0t4iKIHruIbRU,3695
-labcode/backend.py,sha256=rBaicVGPsKnIOCN_MjT4sZM7mFQodL75LtvLva-tLzU,33680
+labcode/backend.py,sha256=kkJ1DcJQciM-86fTQWyy0N-wAEVyo5JJ3HuVRzDiEuY,33630
 labcode/cli.py,sha256=paeYARy1BvACCf0lmlZLdgWyCgq3VyywSpvUKsGI0Mc,3538
-labcode/dialect.py,sha256=2K3F_m8UJlOd2JPCppQjkQ7TqAnYsLfvjrQx6P1Gu6o,25211
-labcode/extension.py,sha256=vR-hPf16qSXRErMVZvVaFj0cpFp83leX9NyRNyvTbPs,19790
+labcode/dialect.py,sha256=x6defFkzP-fv4fi2SG-Qt8XxJRuF1NXhiOXxcKFyx3k,27468
+labcode/extension.py,sha256=4qrw4jEMDNrj-l66HWNlBsy-bWHStSIe7CMcrj41-LQ,21377
 labcode/idgen.py,sha256=MYCke8ytQU1GnwNVq2sPwlvzqrs0JS-FZzgs5MoosFw,2850
 labcode/objectid.py,sha256=NQHZ81WCRwCXF7SwdXPUg2Q8ln4UJ936kepxHQAxUS0,10620
 labcode/otel.py,sha256=FvMIb07nn6OSSuAjixA898AxXp8OcSD-iNJYboa_pyI,14713
@@ -12,14 +12,14 @@ labcode/otel_sila2.py,sha256=t2H8x_jH2cysWRQ5joX6b8cqFDArALYcObEPTXHzepw,8612
 labcode/probe.py,sha256=niUm3qrHdKBq0DCbVTh3ThmBlIn0GIkx_zDSqKrPbfs,8305
 labcode/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 labcode/record.py,sha256=TuqalknpDeOkOCjfoLuW_8cSMGou9NZVJK7x1N-Z6kA,12094
-labcode/run_cli.py,sha256=_xMfQBDYTZnjyJcNC6Uh4lHpYYrANYa_N8CUr_gxPsc,18131
+labcode/run_cli.py,sha256=7VUdOWoxdofbw5UI32UeWCH-sEPGHRHAjjau-bgLiZA,18897
 labcode/runner.py,sha256=Ux_gkgAxOepuKO9zRicoeCe-YG5ycKjqRd8BY14ovxk,11277
 labcode/sila2.py,sha256=jd_f2ARVvH96As5HCa9qAG6cDERPpsvjg_ZYioDyI7U,13477
 labcode/sila2_commands.py,sha256=oYuqUDUKcN5sxo2QvxtkNqRfvietrHkLg7Yqvcj1eZ4,5349
 labcode/sila2_instrument.py,sha256=Lne4AO257UfAHprh4Pmlqg8jVLng8haeJhMVfSfMfdE,24564
-labcode-0.3.0.dist-info/licenses/LICENSE,sha256=weUnWoHlmaiawSjaLy_ECNpyTe7F5vDBfLGJKocpUhI,1071
-labcode-0.3.0.dist-info/METADATA,sha256=U2AjqpMA7ZLJYvEthsphZmJoiFsgVoHRitr_biFsOPc,16186
-labcode-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-labcode-0.3.0.dist-info/entry_points.txt,sha256=eP2fNwGx6ZYNJ_AWzGZhiDJaPqeqaA0iZAc-Tae1PGQ,40
-labcode-0.3.0.dist-info/top_level.txt,sha256=7WhrsXy6psZ8TDzksIEEuj2q93GeXWkHL9h1RbdBrJg,8
-labcode-0.3.0.dist-info/RECORD,,
+labcode-0.4.0.dist-info/licenses/LICENSE,sha256=weUnWoHlmaiawSjaLy_ECNpyTe7F5vDBfLGJKocpUhI,1071
+labcode-0.4.0.dist-info/METADATA,sha256=yuxDVZ9Wg58EwEl2YV4mGFr7Qo7k624uaTpVKQMOKTc,16952
+labcode-0.4.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+labcode-0.4.0.dist-info/entry_points.txt,sha256=eP2fNwGx6ZYNJ_AWzGZhiDJaPqeqaA0iZAc-Tae1PGQ,40
+labcode-0.4.0.dist-info/top_level.txt,sha256=7WhrsXy6psZ8TDzksIEEuj2q93GeXWkHL9h1RbdBrJg,8
+labcode-0.4.0.dist-info/RECORD,,