labnotes 0.0.127__tar.gz → 0.0.128__tar.gz

{labnotes-0.0.127 → labnotes-0.0.128}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.0.127
+Version: 0.0.128
 Summary: Browse experiment designs, notes, and run data from a folder.
 Project-URL: Repository, https://github.com/thekevinscott/labnotes
 Author-email: Kevin Scott <me@thekevinscott.com>

{labnotes-0.0.127 → labnotes-0.0.128}/src/labnotes/context.md

@@ -72,12 +72,15 @@ Each run gets a new run folder. In `matrix` mode it is named for the UTC time it
 its folder the same way. One that plans more gets one folder named that way, and its runs nest
 inside it (`runs/20261020-000429-brave-fox/quiet-river`); the run id is that path under `runs/`. Either way, folder listings sort by start. `command` runs in a shell from the root, with
 `{run_dir}` replaced by the run folder's absolute path. Pass it to the
-script so it writes its outputs there.
+script so it writes its outputs there. `{run_id}` becomes the run id, and
+`{invocation_id}` an id every run of one `run` command shares: the run id when
+it plans one run, else the adhoc invocation folder's name, or in `matrix` mode a
+stamped id that names no folder. All three are shell-quoted.
 Each param is appended as `--name value`, with the name as written (use
 `source-language` for a `--source-language` flag), booleans as 0 or 1, and lists
 and tables as JSON. labnotes writes `run.json` (params, `command`, created,
 ended, exit code, `ended_by`, `signal`), `stdout.log` and `stderr.log` to the
-run folder. `command` is the shell command the run executed, with `{run_dir}`
+run folder. `command` is the shell command the run executed, with the placeholders
 and the params filled in, written before the run starts, so a killed run has it
 and a later edit to `experiment.toml` doesn't hide what a run did. `ended_by` is `"timeout"`, `"stop"` (labnotes stopped it),
 `"signal"` (a signal labnotes didn't send, like the out-of-memory killer),
@@ -93,7 +96,9 @@ the value from the start, even if the code changed while they waited.
 commands run once per `run` from the root: setup before the first run starts,
 teardown after the last one ends, even if runs failed, were stopped, or setup
 failed (so teardown must cope with a partial setup). A failing setup starts no
-run; a failing teardown fails the invocation.
+run; a failing teardown fails the invocation. Both get `{invocation_id}`, and
+`{run_id}` only when one run is planned; otherwise `{run_id}` there fails the
+invocation before anything starts.
 A run counts when it exited 0 and its `run.json` doesn't hold
 `"excluded": true`, so excluding a run by hand means adding that key; the next
 `run` replaces it. Other keys you add to `run.json` are kept and show in `run`.

labnotes-0.0.128/src/labnotes/runner/fill_ids.py

@@ -0,0 +1,8 @@
+import shlex
+from collections.abc import Mapping
+
+
+def fill_ids(command: str, ids: Mapping[str, str]) -> str:
+    for name, value in ids.items():
+        command = command.replace(f"{{{name}}}", shlex.quote(value))
+    return command

labnotes-0.0.128/src/labnotes/runner/hook_ids.py

@@ -0,0 +1,14 @@
+def hook_ids(
+    hooks: dict[str, str | None], invocation: str, runs: list[str]
+) -> dict[str, str]:
+    match runs:
+        case [run]:
+            return {"run_id": run, "invocation_id": invocation}
+    for hook, command in hooks.items():
+        if command is not None and "{run_id}" in command:
+            raise ValueError(
+                f"{hook} command {command} uses {{run_id}}, but this invocation plans "
+                f"{len(runs)} runs. {{run_id}} needs exactly one; "
+                "use {invocation_id} instead."
+            )
+    return {"invocation_id": invocation}

{labnotes-0.0.127 → labnotes-0.0.128}/src/labnotes/runner/run_experiment.py

@@ -13,6 +13,8 @@ from labnotes.models import (
 )
 from labnotes.retries import RETRY_EXIT_CODE, RETRY_SECONDS
 from labnotes.runner.execute_run import execute_run
+from labnotes.runner.fill_ids import fill_ids
+from labnotes.runner.hook_ids import hook_ids
 from labnotes.runner.in_subset import in_subset
 from labnotes.runner.invocation_hook import invocation_hook
 from labnotes.runner.invocation_meta import invocation_meta
@@ -77,6 +79,14 @@ async def run_experiment(
         run = new_id(params)
         planned.add(run)
         plan.append((run, params))
+    match plan:
+        case [(invocation, _)]:
+            pass
+        case _:
+            invocation = group or new_stamped_run_id(taken)
+    planned.add(invocation)
+    hooks = {"setup": experiment.setup, "teardown": experiment.teardown}
+    ids = hook_ids(hooks, invocation, [run for run, _ in plan])
     runs = [{"run": run, "params": params} for run, params in plan]
     report(
         {
@@ -212,7 +222,7 @@ async def run_experiment(
         result = await execute_run(
             config.root,
             folder,
-            experiment.command,
+            fill_ids(experiment.command, {"run_id": run, "invocation_id": invocation}),
             params,
             running[run],
             stopping,
@@ -237,14 +247,16 @@ async def run_experiment(
     async def teardown() -> None:
         if experiment.teardown is not None:
             report({"event": "tearing down"})
-            await invocation_hook(config.root, "teardown", experiment.teardown)
+            await invocation_hook(
+                config.root, "teardown", fill_ids(experiment.teardown, ids)
+            )
 
     listen(Controls(interrupt, set_concurrency, kill, finish))
     # Like vitest's globalSetup: a failed setup still gets its teardown.
     try:
         if experiment.setup is not None:
             report({"event": "setting up"})
-            await invocation_hook(config.root, "setup", experiment.setup)
+            await invocation_hook(config.root, "setup", fill_ids(experiment.setup, ids))
         fill()
         await done.wait()
         await asyncio.gather(*started)