labnotes 0.0.109__tar.gz → 0.0.111__tar.gz

{labnotes-0.0.109 → labnotes-0.0.111}/PKG-INFO

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

@@ -24,8 +24,9 @@ When `experiment.toml` sits next to `.labnotes.toml`, the root is the one experi
   `experiment.toml`, files or runs.
 - `files`: `experiment`, `filename`, `path`, `ctime`, `mtime`.
 - `runs`: `experiment`, `id`, `folder`, `created`, `ended`, `exit_code`,
-  `error`, `stdout`, `stderr`, `params` as JSON, and `run`, the whole
-  `run.json` as JSON, read from each run folder's `run.json`.
+  `error`, `stdout`, `stderr`, `params` as JSON, `meta` as JSON (null without
+  a `meta` command), `command`, and `run`, the whole `run.json` as JSON, read
+  from each run folder's `run.json`.
 
 Keys come from folder names, so renaming a folder renames its rows on the next
 read. Paths are relative to the root, and times are UTC ISO 8601.
@@ -74,13 +75,20 @@ inside it (`runs/20261020-000429-brave-fox/quiet-river`); the run id is that pat
 script so it writes its outputs there.
 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, created, ended, exit
-code, `ended_by`, `signal`), `stdout.log` and `stderr.log` to the
-run folder. `ended_by` is `"timeout"`, `"stop"` (labnotes stopped it),
+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}`
+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),
 `"lost"` (its process died unseen; the daemon marks these when it starts, with
 `ended` set and `exit_code` null) or null (the script exited itself). `signal` is the signal number read from the
 exit code (negative, or 128 + N from the shell), else null.
+`meta` in `experiment.toml` (or `[experiment]` in `.labnotes.toml`) is a shell
+command that prints one JSON object, such as the git commit. labnotes runs it
+once from the root when `run` starts and copies it into every run's `run.json`
+as `meta`. If it fails or prints anything else, no run starts. Queued runs keep
+the value from the start, even if the code changed while they waited.
 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.109 → labnotes-0.0.111}/src/labnotes/models.py

@@ -65,3 +65,4 @@ class ExperimentConfig:
     mode: str = DEFAULT_MODE
     concurrency: int = 1
     retries: int = DEFAULT_RETRIES
+    meta: str | None = None

{labnotes-0.0.109 → labnotes-0.0.111}/src/labnotes/runner/execute_run.py

@@ -29,9 +29,12 @@ async def execute_run(
     timeout: float | None = None,
     stop: Callable[[], None] = lambda: None,
     stopped: Callable[[], bool] = lambda: False,
+    meta: dict[str, object] | None = None,
 ) -> dict[str, object]:
+    resolved = shell_command(command, folder, params)
     run: dict[str, object] = {
         "params": params,
+        "command": resolved,
         "created": iso_time(time.time()),
         "ended": None,
         "exit_code": None,
@@ -41,6 +44,8 @@ async def execute_run(
     }
     if retry_of is not None:
         run["retry_of"] = retry_of
+    if meta is not None:
+        run["meta"] = meta
     write_run_json(folder, run)
     with (
         (folder / "stdout.log").open("wb") as stdout,
@@ -48,7 +53,7 @@ async def execute_run(
     ):
         try:
             process = await asyncio.create_subprocess_shell(
-                shell_command(command, folder, params),
+                resolved,
                 cwd=root,
                 env={
                     "FORCE_COLOR": "1",

labnotes-0.0.111/src/labnotes/runner/invocation_meta.py

@@ -0,0 +1,28 @@
+import asyncio
+import json
+from pathlib import Path
+
+
+async def invocation_meta(root: Path, command: str) -> dict[str, object]:
+    process = await asyncio.create_subprocess_shell(
+        command,
+        cwd=root,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    stdout, stderr = await process.communicate()
+    detail = stderr.decode(errors="replace").strip()
+
+    def fail(reason: str) -> ValueError:
+        message = f"meta command {command} {reason}"
+        return ValueError(f"{message}: {detail}" if detail else message)
+
+    if process.returncode != 0:
+        raise fail(f"exited {process.returncode}")
+    try:
+        meta = json.loads(stdout)
+    except ValueError:
+        meta = None
+    if not isinstance(meta, dict):
+        raise fail("didn't print a JSON object")
+    return meta

{labnotes-0.0.109 → labnotes-0.0.111}/src/labnotes/runner/read_experiment_config.py

@@ -19,6 +19,7 @@ SETTINGS = {
     "mode",
     "concurrency",
     "retries",
+    "meta",
 }
 
 
@@ -69,6 +70,9 @@ def read_experiment_config(
     retries = values.get("retries", retries)
     if not is_non_negative_int(retries):
         raise ValueError(f"{path}: retries must be 0 or more")
+    meta = values.get("meta")
+    if meta is not None and (not isinstance(meta, str) or not meta.strip()):
+        raise ValueError(f"{path}: meta must be a string")
     return ExperimentConfig(
-        command, repeats, params, name, counts, mode, concurrency, retries
+        command, repeats, params, name, counts, mode, concurrency, retries, meta
     )

{labnotes-0.0.109 → labnotes-0.0.111}/src/labnotes/runner/run_experiment.py

@@ -13,6 +13,7 @@ from labnotes.models import (
 )
 from labnotes.retries import RETRY_EXIT_CODE, RETRY_SECONDS
 from labnotes.runner.execute_run import execute_run
+from labnotes.runner.invocation_meta import invocation_meta
 from labnotes.runner.new_param_run_id import new_param_run_id
 from labnotes.runner.new_stamped_run_id import new_stamped_run_id
 from labnotes.runner.param_grid import param_grid
@@ -36,6 +37,9 @@ async def run_experiment(
     timeout: float | None = None,
     retry_seconds: float = RETRY_SECONDS,
 ) -> list[dict[str, object]]:
+    meta = None
+    if experiment.meta is not None:
+        meta = await invocation_meta(config.root, experiment.meta)
     tables = open_tables(config)
     existing = await experiment_run_ids(tables, name)
     finished: list[dict[str, object]] = []
@@ -256,6 +260,7 @@ async def run_experiment(
             timeout=timeout,
             stop=lambda: kill(run),
             stopped=lambda: run in stopped,
+            meta=meta,
         )
         del running[run], trees[run]
         report({"event": "ended", "run": run, **result})

{labnotes-0.0.109 → labnotes-0.0.111}/src/labnotes/tables/open_tables.py

@@ -22,7 +22,7 @@ RUNS = """
 CREATE TABLE runs (
   experiment TEXT, id TEXT, folder TEXT, created TEXT, ended TEXT,
   exit_code INTEGER, error TEXT,
-  stdout TEXT, stderr TEXT, params TEXT, run TEXT,
+  stdout TEXT, stderr TEXT, params TEXT, meta TEXT, command TEXT, run TEXT,
   PRIMARY KEY (experiment, id)
 )
 """

{labnotes-0.0.109 → labnotes-0.0.111}/src/labnotes/tables/read_run.py

@@ -25,6 +25,8 @@ def read_run(
             "stdout": f"{folder}/stdout.log",
             "stderr": f"{folder}/stderr.log",
             "params": json.dumps(run.get("params", {})),
+            "meta": None if (meta := run.get("meta")) is None else json.dumps(meta),
+            "command": run.get("command"),
             "run": json.dumps(run),
         }
     ]

{labnotes-0.0.109 → labnotes-0.0.111}/testing-conventions.toml

@@ -67,7 +67,7 @@ reason = "WorkerState members are singletons, so is equals =="
 [[python.exempt]]
 path = "src/labnotes/runner/run_experiment.py"
 rules = ["mutation"]
-lines = [184, 263]
+lines = [188, 269]
 reason = "a retry is only scheduled below the budget and each one adds one, so tried never passes retries: >= equals ==; both sides are small ints, which CPython caches, so is equals =="
 
 [[python.exempt]]