labnotes 0.1.1__tar.gz → 0.2.0__tar.gz

{labnotes-0.1.1 → labnotes-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.1.1
+Version: 0.2.0
 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>
@@ -121,7 +121,8 @@ line per event instead.
 - `--concurrency N` runs N at a time (default 1).
 - `-e PATH` reads another file instead of `experiment.toml`.
 - `--PARAM=VALUE` runs only the cells where that param has that value, like
-  `--model=small`.
+  `--model=small`. Repeat a param to run several values:
+  `--model=small --model=large`.
 - With runs going, Ctrl-C asks first. Enter (or a second Ctrl-C) stops the running scripts and records their end,
   then kills any still going 5 seconds later. Escape goes back. SIGTERM and
   SIGHUP stop them the same way.

{labnotes-0.1.1 → labnotes-0.2.0}/README.md

@@ -96,7 +96,8 @@ line per event instead.
 - `--concurrency N` runs N at a time (default 1).
 - `-e PATH` reads another file instead of `experiment.toml`.
 - `--PARAM=VALUE` runs only the cells where that param has that value, like
-  `--model=small`.
+  `--model=small`. Repeat a param to run several values:
+  `--model=small --model=large`.
 - With runs going, Ctrl-C asks first. Enter (or a second Ctrl-C) stops the running scripts and records their end,
   then kills any still going 5 seconds later. Escape goes back. SIGTERM and
   SIGHUP stop them the same way.

{labnotes-0.1.1 → labnotes-0.2.0}/src/labnotes/context.md

@@ -102,19 +102,17 @@ 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_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.
+run; a failing teardown fails the invocation. Hooks and `meta` get no folder
+placeholders: `{run_dir}` or `{invocation_dir}` in one fails before anything
+starts. Share values through state instead.
 Setup can call `labnotes.set_state({"container": "abc"})`; runs and teardown read the
 dict with `labnotes.get_state()`. Writes merge by top-level key, replacing an
 existing value without dropping other keys. Values must be JSON serializable;
 reading before any write returns `{}`. Runs can only read: `set_state` raises
 `RuntimeError` there. Both functions raise outside an invocation and in `meta`.
 Labnotes gives setup/teardown `LABNOTES_STATE` and runs `LABNOTES_RUN_STATE`,
-pointing to `{invocation_dir}/state.json` or, without a shared folder, a temp
+pointing to `state.json` in the multi-run adhoc group folder or the lone run's
+folder, or, without a shared folder, a temp
 file kept through all runs and teardown and then removed. Queued runs and retries
 read the same file after setup finishes. `meta` receives neither state variable;
 state is never copied into `run.json`.
@@ -125,8 +123,8 @@ children and set their own hook and run variables.
 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}` and
-`{invocation_dir}` placeholders. In hooks and meta, only `{invocation_dir}` is
-available, and it requires one planned run in matrix mode.
+`{invocation_dir}` placeholders. Hooks and meta get neither, so values using
+one are left out of their environment; runs still get them.
 `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
@@ -192,8 +190,10 @@ going. Elsewhere, it prints a line per event instead.
 - `--PARAM=VALUE` runs only the cells where that param has that value, e.g.
   `labnotes experiments NAME run --model=small`. PARAM must be a key in
   `[params]` and VALUE one of its values, written as it shows in `runs`
-  (`true`, `2`); anything else is an error. One value per param; give several
-  params to narrow further (`--model=small --lang=en`). It changes only what
+  (`true`, `2`); anything else is an error. Repeat a param to run any of
+  several values (`--model=small --model=large`); give several params to
+  narrow further (`--model=small --lang=en`). Values are never split on
+  commas. It changes only what
   this `run` starts: counts, progress and `repeats` still cover the full
   matrix, so a later plain `run` fills in the rest. Use it instead of editing
   `experiment.toml` to run a slice.

{labnotes-0.1.1 → labnotes-0.2.0}/src/labnotes/experiments.py

@@ -33,7 +33,8 @@ class PassthroughCommand(click.Command):
     cls=PassthroughCommand,
     help="List experiments, show one, list its runs, or run it."
     " `new [NAME]` creates one. With run, --PARAM=VALUE runs only the"
-    " matrix cells where that param has that value, and anything after --"
+    " matrix cells where that param has that value (repeat it for several"
+    " values), and anything after --"
     " is appended to every run's command and recorded in run.json, so never"
     " pass secrets there.",
     context_settings={"ignore_unknown_options": True, "allow_extra_args": True},

{labnotes-0.1.1 → labnotes-0.2.0}/src/labnotes/parse_subset.py

@@ -1,10 +1,8 @@
-def parse_subset(args: list[str]) -> dict[str, str]:
-    only: dict[str, str] = {}
+def parse_subset(args: list[str]) -> dict[str, list[str]]:
+    only: dict[str, list[str]] = {}
     for arg in args:
         param, equals, value = arg.removeprefix("--").partition("=")
         if not arg.startswith("--") or not equals or not param:
             raise ValueError(f"Unexpected {arg}. Pick params with --PARAM=VALUE.")
-        if param in only:
-            raise ValueError(f"--{param} given twice. Pass one value per param.")
-        only[param] = value
+        only.setdefault(param, []).append(value)
     return only

labnotes-0.2.0/src/labnotes/runner/check_hook_placeholders.py

@@ -0,0 +1,12 @@
+from labnotes.runner.placeholders import PLACEHOLDERS
+
+
+def check_hook_placeholders(hooks: dict[str, str | None]) -> None:
+    for hook, command in hooks.items():
+        for name in PLACEHOLDERS:
+            if command is not None and f"{{{name}}}" in command:
+                raise ValueError(
+                    f"{hook} command {command} uses {{{name}}}; setup, teardown, "
+                    "and meta get no folder placeholders. "
+                    "Share values with set_state() and get_state()."
+                )

{labnotes-0.1.1 → labnotes-0.2.0}/src/labnotes/runner/check_subset.py

@@ -1,13 +1,14 @@
 from labnotes.format_value import format_value
 
 
-def check_subset(params: dict[str, list[object]], only: dict[str, str]) -> None:
-    for param, value in only.items():
+def check_subset(params: dict[str, list[object]], only: dict[str, list[str]]) -> None:
+    for param, wanted in only.items():
         if param not in params:
             declared = ", ".join(params) or "none"
             raise ValueError(f"No param {param}. Params: {declared}.")
         values = [format_value(option) for option in params[param]]
-        if value not in values:
-            raise ValueError(
-                f"No value {value} for {param}. Values: {', '.join(values)}."
-            )
+        for value in wanted:
+            if value not in values:
+                raise ValueError(
+                    f"No value {value} for {param}. Values: {', '.join(values)}."
+                )

labnotes-0.2.0/src/labnotes/runner/fill_experiment_env.py

@@ -0,0 +1,23 @@
+from collections.abc import Mapping
+
+from labnotes.runner.fill_dirs import fill_dirs
+from labnotes.runner.placeholders import PLACEHOLDERS
+
+
+def fill_experiment_env(
+    configured: Mapping[str, str],
+    inherited: Mapping[str, str],
+    dirs: Mapping[str, str],
+) -> dict[str, str]:
+    caller = {
+        key: value
+        for key, value in inherited.items()
+        if not key.startswith("LABNOTES_")
+    }
+    filled = {
+        key: fill_dirs(value, dirs, quote=False)
+        for key, value in configured.items()
+        if key not in caller
+        and all(name in dirs for name in PLACEHOLDERS if f"{{{name}}}" in value)
+    }
+    return {**filled, **caller}

labnotes-0.2.0/src/labnotes/runner/in_subset.py

@@ -0,0 +1,5 @@
+from labnotes.format_value import format_value
+
+
+def in_subset(cell: dict[str, object], only: dict[str, list[str]]) -> bool:
+    return all(format_value(cell[param]) in values for param, values in only.items())

{labnotes-0.1.1 → labnotes-0.2.0}/src/labnotes/runner/placeholders.py

@@ -1,2 +1 @@
 PLACEHOLDERS = ("run_dir", "invocation_dir")
-HOOK_PLACEHOLDERS = ("invocation_dir",)

{labnotes-0.1.1 → labnotes-0.2.0}/src/labnotes/runner/prepare_experiment.py

@@ -13,7 +13,7 @@ async def prepare_experiment(
     name: str,
     experiment_config: Path | None,
     concurrency: int | None,
-    only: dict[str, str] | None = None,
+    only: dict[str, list[str]] | None = None,
     args: list[str] | None = None,
     setup: str | None = None,
     teardown: str | None = None,

{labnotes-0.1.1 → labnotes-0.2.0}/src/labnotes/runner/run_experiment.py

@@ -16,10 +16,10 @@ from labnotes.models import (
     Report,
 )
 from labnotes.retries import RETRY_EXIT_CODE, RETRY_SECONDS
+from labnotes.runner.check_hook_placeholders import check_hook_placeholders
 from labnotes.runner.execute_run import execute_run
 from labnotes.runner.fill_experiment_env import fill_experiment_env
 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
@@ -47,7 +47,7 @@ async def run_experiment(
     listen: Listen,
     timeout: float | None = None,
     retry_seconds: float = RETRY_SECONDS,
-    only: dict[str, str] | None = None,
+    only: dict[str, list[str]] | None = None,
     args: list[str] | None = None,
     environment: dict[str, str] | None = None,
     snapshot: ProjectSnapshot | None = None,
@@ -101,21 +101,21 @@ async def run_experiment(
         "teardown": experiment.teardown,
         "meta": experiment.meta,
     }
-    dirs = hook_dirs(hooks, group_dir, run_dirs)
+    check_hook_placeholders(hooks)
     hook_env = {
-        hook: fill_experiment_env(
-            experiment.env, inherited, dirs, hook=hook, runs=len(plan)
-        )
+        hook: fill_experiment_env(experiment.env, inherited, {})
         for hook, command in hooks.items()
         if command is not None
     }
     meta = None
     if experiment.meta is not None:
-        meta = await invocation_meta(
-            command_root, fill_dirs(experiment.meta, dirs), hook_env["meta"]
-        )
-    if dirs:
-        Path(dirs["invocation_dir"]).mkdir(parents=True, exist_ok=True)
+        meta = await invocation_meta(command_root, experiment.meta, hook_env["meta"])
+    invocation_dir = group_dir
+    match run_dirs:
+        case [run_dir]:
+            invocation_dir = run_dir
+    if invocation_dir is not None:
+        Path(invocation_dir).mkdir(parents=True, exist_ok=True)
     runs = [{"run": run, "params": params} for run, params in plan]
     report(
         {
@@ -248,7 +248,7 @@ async def run_experiment(
         if snapshot is not None and snapshot.sha is not None:
             (folder / "git-sha.txt").write_text(snapshot.sha + "\n")
             (folder / "git-diff.patch").write_bytes(snapshot.diff or b"")
-        run_invocation_dir = dirs.get("invocation_dir") or str(folder.resolve())
+        run_invocation_dir = invocation_dir or str(folder.resolve())
         report({"event": "started", "run": run, "params": params, "folder": folder})
         running[run] = set()
         trees[run] = set()
@@ -303,14 +303,14 @@ async def run_experiment(
             await invocation_hook(
                 command_root,
                 "teardown",
-                fill_dirs(experiment.teardown, dirs),
+                experiment.teardown,
                 hook_env["teardown"],
             )
 
     listen(Controls(interrupt, set_concurrency, kill, finish))
     with (
-        nullcontext(dirs["invocation_dir"])
-        if dirs
+        nullcontext(invocation_dir)
+        if invocation_dir is not None
         else TemporaryDirectory(prefix="labnotes-state-")
     ) as state_dir:
         state_file = Path(state_dir) / "state.json"
@@ -324,7 +324,7 @@ async def run_experiment(
                 await invocation_hook(
                     command_root,
                     "setup",
-                    fill_dirs(experiment.setup, dirs),
+                    experiment.setup,
                     hook_env["setup"],
                 )
             fill()

{labnotes-0.1.1 → labnotes-0.2.0}/src/labnotes/runner/start_experiment.py

@@ -13,7 +13,7 @@ def start_experiment(
     experiment_config: Path | None,
     concurrency: int | None,
     timeout: int | None,
-    only: dict[str, str] | None,
+    only: dict[str, list[str]] | None,
     args: list[str] | None,
     setup: str | None,
     teardown: str | None,

labnotes-0.1.1/src/labnotes/runner/fill_experiment_env.py

@@ -1,34 +0,0 @@
-from collections.abc import Mapping
-
-from labnotes.runner.fill_dirs import fill_dirs
-from labnotes.runner.placeholders import HOOK_PLACEHOLDERS, PLACEHOLDERS
-
-
-def fill_experiment_env(
-    configured: Mapping[str, str],
-    inherited: Mapping[str, str],
-    dirs: Mapping[str, str],
-    *,
-    hook: str | None = None,
-    runs: int = 1,
-) -> dict[str, str]:
-    caller = {
-        key: value
-        for key, value in inherited.items()
-        if not key.startswith("LABNOTES_")
-    }
-    filled: dict[str, str] = {}
-    for key, value in configured.items():
-        if key in caller:
-            continue
-        used = [name for name in PLACEHOLDERS if f"{{{name}}}" in value]
-        if hook is not None and any(name not in HOOK_PLACEHOLDERS for name in used):
-            continue
-        for name in used:
-            if name not in dirs:
-                raise ValueError(
-                    f"{hook} env.{key} uses {{{name}}}, but this invocation plans "
-                    f"{runs} runs. {{{name}}} needs exactly one run in this mode."
-                )
-        filled[key] = fill_dirs(value, dirs, quote=False)
-    return {**filled, **caller}

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

@@ -1,21 +0,0 @@
-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.1.1/src/labnotes/runner/in_subset.py

@@ -1,5 +0,0 @@
-from labnotes.format_value import format_value
-
-
-def in_subset(cell: dict[str, object], only: dict[str, str]) -> bool:
-    return all(format_value(cell[param]) == value for param, value in only.items())