labnotes 0.0.129__tar.gz → 0.0.130__tar.gz

{labnotes-0.0.129 → labnotes-0.0.130}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.0.129
+Version: 0.0.130
 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.129 → labnotes-0.0.130}/src/labnotes/context.md

@@ -72,10 +72,9 @@ 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. `{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.
+script so it writes its outputs there. `{invocation_dir}` is the shared adhoc
+group folder's absolute path when several runs are planned; otherwise it equals
+each run's `{run_dir}`. Both placeholders 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,
@@ -96,16 +95,20 @@ 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. Both get `{invocation_id}`, and
-`{run_id}` only when one run is planned; otherwise `{run_id}` there fails the
-invocation before anything starts.
+run; a failing teardown fails the invocation. Both get `{invocation_dir}` only:
+the shared folder for a multi-run adhoc invocation, or the run folder when one
+run is planned. That folder exists before setup starts. In matrix mode with
+several runs there is no shared folder, so `{invocation_dir}` in a hook fails.
+`{run_dir}` is never filled in hooks; use `{invocation_dir}` instead. An
+unavailable placeholder fails before anything starts.
 `[env]` in `experiment.toml` sets string environment values for `command`,
 `meta`, `setup`, and `teardown`. `[experiment.env]` in `.labnotes.toml`
 provides shared values; experiment values replace them by name. Variables in
 the environment that starts `labnotes experiments NAME run` win over both,
-including inline assignments. Values can use raw `{run_dir}`, `{run_id}` and
-`{invocation_id}` placeholders. In hooks and meta, `{run_id}` and `{run_dir}`
-require exactly one planned run. `LABNOTES_*` names are reserved for labnotes.
+including inline assignments. Values can use raw `{run_dir}` and
+`{invocation_dir}` placeholders. In hooks and meta, only `{invocation_dir}` is
+available, and it requires one planned run in matrix mode.
+`LABNOTES_*` names are reserved for labnotes.
 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.129/src/labnotes/runner/fill_ids.py → labnotes-0.0.130/src/labnotes/runner/fill_dirs.py

@@ -2,7 +2,7 @@ import shlex
 from collections.abc import Mapping
 
 
-def fill_ids(command: str, ids: Mapping[str, str], *, quote: bool = True) -> str:
-    for name, value in ids.items():
+def fill_dirs(command: str, dirs: Mapping[str, str], *, quote: bool = True) -> str:
+    for name, value in dirs.items():
         command = command.replace(f"{{{name}}}", shlex.quote(value) if quote else value)
     return command

{labnotes-0.0.129 → labnotes-0.0.130}/src/labnotes/runner/fill_experiment_env.py

@@ -1,12 +1,12 @@
 from collections.abc import Mapping
 
-from labnotes.runner.fill_ids import fill_ids
+from labnotes.runner.fill_dirs import fill_dirs
 
 
 def fill_experiment_env(
     configured: Mapping[str, str],
     inherited: Mapping[str, str],
-    ids: Mapping[str, str],
+    dirs: Mapping[str, str],
     *,
     hook: str | None = None,
     runs: int = 1,
@@ -20,12 +20,15 @@ def fill_experiment_env(
     for key, value in configured.items():
         if key in caller:
             continue
-        for name in ("run_dir", "run_id"):
-            if f"{{{name}}}" in value and name not in ids:
+        if hook is not None and "{run_dir}" in value:
+            raise ValueError(
+                f"{hook} env.{key} uses {{run_dir}}; use {{invocation_dir}} instead."
+            )
+        for name in ("run_dir", "invocation_dir"):
+            if f"{{{name}}}" in value and name not in dirs:
                 raise ValueError(
                     f"{hook} env.{key} uses {{{name}}}, but this invocation plans "
-                    f"{runs} runs. {{{name}}} needs exactly one; "
-                    "use {invocation_id} instead."
+                    f"{runs} runs. {{{name}}} needs exactly one run in this mode."
                 )
-        filled[key] = fill_ids(value, ids, quote=False)
+        filled[key] = fill_dirs(value, dirs, quote=False)
     return {**filled, **caller}

labnotes-0.0.130/src/labnotes/runner/hook_dirs.py

@@ -0,0 +1,21 @@
+def hook_dirs(
+    hooks: dict[str, str | None], invocation_dir: str | None, run_dirs: list[str]
+) -> dict[str, str]:
+    match run_dirs:
+        case [run_dir]:
+            invocation_dir = invocation_dir or run_dir
+    available = {"invocation_dir": invocation_dir} if invocation_dir is not None else {}
+    for hook, command in hooks.items():
+        if command is None:
+            continue
+        if "{run_dir}" in command:
+            raise ValueError(
+                f"{hook} command {command} uses {{run_dir}}; "
+                "use {invocation_dir} instead."
+            )
+        if "{invocation_dir}" in command and invocation_dir is None:
+            raise ValueError(
+                f"{hook} command {command} uses {{invocation_dir}}, but this "
+                f"invocation plans {len(run_dirs)} runs and has no shared folder."
+            )
+    return available

{labnotes-0.0.129 → labnotes-0.0.130}/src/labnotes/runner/run_experiment.py

@@ -2,6 +2,7 @@ import asyncio
 import json
 import os
 import signal
+from pathlib import Path
 
 import psutil
 
@@ -15,8 +16,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_experiment_env import fill_experiment_env
-from labnotes.runner.fill_ids import fill_ids
-from labnotes.runner.hook_ids import hook_ids
+from labnotes.runner.fill_dirs import fill_dirs
+from labnotes.runner.hook_dirs import hook_dirs
 from labnotes.runner.in_subset import in_subset
 from labnotes.runner.invocation_hook import invocation_hook
 from labnotes.runner.invocation_meta import invocation_meta
@@ -80,27 +81,24 @@ async def run_experiment(
         run = new_id(params)
         planned.add(run)
         plan.append((run, params))
-    hook_run_dir: str | None
-    match plan:
-        case [(invocation, _)]:
-            hook_run_dir = str(
-                run_folder(config.root, config.runs, name, invocation).resolve()
-            )
-        case _:
-            invocation = group or new_stamped_run_id(taken)
-            hook_run_dir = None
-    planned.add(invocation)
+    run_dirs = [
+        str(run_folder(config.root, config.runs, name, run).resolve())
+        for run, _ in plan
+    ]
+    group_dir = (
+        str(run_folder(config.root, config.runs, name, group).resolve())
+        if group is not None
+        else None
+    )
     hooks = {
         "setup": experiment.setup,
         "teardown": experiment.teardown,
         "meta": experiment.meta,
     }
-    ids = hook_ids(hooks, invocation, [run for run, _ in plan])
-    if hook_run_dir is not None:
-        ids["run_dir"] = hook_run_dir
+    dirs = hook_dirs(hooks, group_dir, run_dirs)
     hook_env = {
         hook: fill_experiment_env(
-            experiment.env, inherited, ids, hook=hook, runs=len(plan)
+            experiment.env, inherited, dirs, hook=hook, runs=len(plan)
         )
         for hook, command in hooks.items()
         if command is not None
@@ -108,8 +106,10 @@ async def run_experiment(
     meta = None
     if experiment.meta is not None:
         meta = await invocation_meta(
-            config.root, fill_ids(experiment.meta, ids), hook_env["meta"]
+            config.root, fill_dirs(experiment.meta, dirs), hook_env["meta"]
         )
+    if dirs:
+        Path(dirs["invocation_dir"]).mkdir(parents=True, exist_ok=True)
     runs = [{"run": run, "params": params} for run, params in plan]
     report(
         {
@@ -238,14 +238,21 @@ async def run_experiment(
 
     async def start(run: str, params: dict[str, object]) -> None:
         folder = run_folder(config.root, config.runs, name, run)
-        folder.mkdir(parents=True)
+        folder.mkdir(parents=True, exist_ok=True)
+        run_invocation_dir = group_dir or str(folder.resolve())
         report({"event": "started", "run": run, "params": params, "folder": folder})
         running[run] = set()
         trees[run] = set()
         result = await execute_run(
             config.root,
             folder,
-            fill_ids(experiment.command, {"run_id": run, "invocation_id": invocation}),
+            fill_dirs(
+                experiment.command,
+                {
+                    "run_dir": str(folder.resolve()),
+                    "invocation_dir": run_invocation_dir,
+                },
+            ),
             params,
             running[run],
             stopping,
@@ -262,8 +269,7 @@ async def run_experiment(
                 inherited,
                 {
                     "run_dir": str(folder.resolve()),
-                    "run_id": run,
-                    "invocation_id": invocation,
+                    "invocation_dir": run_invocation_dir,
                 },
             ),
         )
@@ -282,7 +288,7 @@ async def run_experiment(
             await invocation_hook(
                 config.root,
                 "teardown",
-                fill_ids(experiment.teardown, ids),
+                fill_dirs(experiment.teardown, dirs),
                 hook_env["teardown"],
             )
 
@@ -292,7 +298,10 @@ async def run_experiment(
         if experiment.setup is not None:
             report({"event": "setting up"})
             await invocation_hook(
-                config.root, "setup", fill_ids(experiment.setup, ids), hook_env["setup"]
+                config.root,
+                "setup",
+                fill_dirs(experiment.setup, dirs),
+                hook_env["setup"],
             )
         fill()
         await done.wait()

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

@@ -1,14 +0,0 @@
-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}