labnotes 0.0.20__tar.gz → 0.0.22__tar.gz

{labnotes-0.0.20 → labnotes-0.0.22}/PKG-INFO

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

@@ -22,8 +22,8 @@ Paths are relative to the root. `{experiment}` and `{run}` stand for folder name
   `experiment.toml`, files or runs.
 - `files`: `experiment`, `filename`, `path`, `ctime`, `mtime`.
 - `runs`: `experiment`, `id`, `folder`, `created`, `ended`, `exit_code`,
-  `error`, `stdout`, `stderr`, and `params` as JSON, read from each run
-  folder's `run.json`.
+  `error`, `stdout`, `stderr`, `params` as JSON, 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.
@@ -57,7 +57,8 @@ effort = ["low", "high"]
 and as `display_name` in `experiments`. The folder name stays the key, so
 renaming the experiment means editing `name`.
 Each combination of `[params]` runs `repeats` times, round-robin. Only runs
-that exit 0 count, so running again fills in what failed or never ran.
+that count fill a combination, so running again fills in what failed or never
+ran.
 Each run gets a new run folder. `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.
@@ -65,15 +66,22 @@ 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), `stdout.log` and `stderr.log` to the run folder.
-To exclude a run, add `"excluded": true` and an optional `"reason"` to its
-`run.json`. An excluded run doesn't count toward `repeats`, so the next `run`
-replaces it; both show as columns in `runs`.
+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`.
+`counts` in `experiment.toml` replaces the rule with a SQL condition over
+`runs`, for example `counts = "exit_code = 0 AND created > '2026-10-01'"` to
+drop runs from before a script change. The default is
+`exit_code = 0 AND NOT coalesce(run ->> 'excluded', false)`.
+`experiments foo runs` shows the rule's result as `counted`; queries over
+`runs` itself see every run, so apply the rule there too.
 
 A script run by labnotes should:
 
 - take each param as a `--name value` flag, parsing lists and tables from JSON;
 - take its output folder as an argument, passed in `command` as `{run_dir}`, and write everything it produces there;
-- exit non-zero when it fails, so the run counts as failed and runs again next time.
+- exit non-zero when it fails, so the run counts as failed and runs again next time;
+- stop any background process it starts before it exits; the run ends when `command` exits.
 
 Runs can take a long time. Start `run` in the background, then check on it with `labnotes experiments foo runs`; a run with no `ended` is still going.
 
@@ -89,4 +97,4 @@ line per event instead.
 - A second `run` of the same experiment fails while the first holds the lock.
 - It exits 1 if any run failed.
 
-`uvx labnotes server` serves the experiments, their markdown files and their runs as a local site, read from the same `.labnotes.toml`. A grid cell is full once it has `repeats` runs that exited 0 and aren't excluded.
+`uvx labnotes server` serves the experiments, their markdown files and their runs as a local site, read from the same `.labnotes.toml`. A grid cell is full once it has `repeats` runs that count.

labnotes-0.0.22/src/labnotes/default_counts.py

@@ -0,0 +1,2 @@
+# Which runs count toward repeats, unless experiment.toml sets `counts`.
+DEFAULT_COUNTS = "exit_code = 0 AND NOT coalesce(run ->> 'excluded', false)"

{labnotes-0.0.20 → labnotes-0.0.22}/src/labnotes/experiments.py

@@ -82,7 +82,10 @@ def experiments(
             ctx.exit(1 if failed else 0)
     if action not in (None, "runs"):
         raise click.UsageError(f"Unknown action {action}. Use runs or run.")
-    rows = asyncio.run(experiment_rows(config, name, action))
+    try:
+        rows = asyncio.run(experiment_rows(config, name, action))
+    except ValueError as error:
+        raise click.ClickException(str(error)) from error
     if rows is None:
         raise click.ClickException(f"No experiment named {name}.")
     print_rows(rows, output_format)

{labnotes-0.0.20 → labnotes-0.0.22}/src/labnotes/models.py

@@ -3,6 +3,8 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
+from labnotes.default_counts import DEFAULT_COUNTS
+
 Report = Callable[[dict[str, object]], None]
 Listen = Callable[[Callable[[], None]], None]
 Start = Callable[[Report, Listen], Coroutine[Any, Any, list[dict[str, object]]]]
@@ -31,3 +33,4 @@ class ExperimentConfig:
     repeats: int
     params: dict[str, list[object]]
     name: str | None = None
+    counts: str = DEFAULT_COUNTS

{labnotes-0.0.20 → labnotes-0.0.22}/src/labnotes/runner/execute_run.py

@@ -3,6 +3,7 @@ import time
 from pathlib import Path
 
 from labnotes.runner.shell_command import shell_command
+from labnotes.runner.wait_for_group import wait_for_group
 from labnotes.runner.write_run_json import write_run_json
 from labnotes.tables.iso_time import iso_time
 
@@ -13,6 +14,7 @@ async def execute_run(
     command: str,
     params: dict[str, object],
     running: set[asyncio.subprocess.Process],
+    stopping: asyncio.Event,
 ) -> dict[str, object]:
     run: dict[str, object] = {
         "params": params,
@@ -42,6 +44,11 @@ async def execute_run(
             running.add(process)
             try:
                 run["exit_code"] = await process.wait()
+                # The shell can exit on SIGTERM before what it started. Once
+                # stopping, the run stays killable until its whole group is
+                # gone. A normal exit ends the run even if helpers linger.
+                if stopping.is_set():
+                    await wait_for_group(process.pid)
             finally:
                 running.discard(process)
     run["ended"] = iso_time(time.time())

{labnotes-0.0.20 → labnotes-0.0.22}/src/labnotes/runner/read_experiment_config.py

@@ -2,9 +2,10 @@ import json
 import tomllib
 from pathlib import Path
 
+from labnotes.default_counts import DEFAULT_COUNTS
 from labnotes.models import ExperimentConfig
 
-SETTINGS = {"name", "command", "repeats", "params"}
+SETTINGS = {"name", "command", "repeats", "params", "counts"}
 
 
 def read_experiment_config(path: Path) -> ExperimentConfig:
@@ -35,4 +36,7 @@ def read_experiment_config(path: Path) -> ExperimentConfig:
         json.dumps(params)
     except TypeError as error:
         raise ValueError(f"{path}: params can't hold dates or times") from error
-    return ExperimentConfig(command, repeats, params, name)
+    counts = values.get("counts", DEFAULT_COUNTS)
+    if not isinstance(counts, str) or not counts.strip():
+        raise ValueError(f"{path}: counts must be a SQL condition")
+    return ExperimentConfig(command, repeats, params, name, counts)

{labnotes-0.0.20 → labnotes-0.0.22}/src/labnotes/runner/run_experiment.py

@@ -22,17 +22,13 @@ async def run_experiment(
     report: Report,
     listen: Listen,
 ) -> list[dict[str, object]]:
-    runs = await list_experiment_runs(open_tables(config), name)
-    finished = [
-        json.loads(str(run["params"]))
-        for run in runs
-        if run["exit_code"] == 0 and not run["excluded"]
-    ]
+    runs = await list_experiment_runs(open_tables(config), name, experiment.counts)
+    finished = [json.loads(str(run["params"])) for run in runs if run["counted"]]
     plan = plan_runs(param_grid(experiment.params), experiment.repeats, finished)
     report({"event": "planned", "runs": len(plan), "concurrency": concurrency})
     running: set[asyncio.subprocess.Process] = set()
     results: list[dict[str, object]] = []
-    stopping = False
+    stopping = asyncio.Event()
 
     def signal_runs(signal_number: int) -> None:
         for process in running:
@@ -40,10 +36,9 @@ async def run_experiment(
                 os.killpg(process.pid, signal_number)
 
     def interrupt() -> None:
-        nonlocal stopping
         plan.clear()
-        if not stopping:
-            stopping = True
+        if not stopping.is_set():
+            stopping.set()
             report({"event": "stopping"})
             signal_runs(signal.SIGTERM)
         elif running:
@@ -60,7 +55,7 @@ async def run_experiment(
             folder.mkdir(parents=True)
             report({"event": "started", "run": run, "params": params})
             result = await execute_run(
-                config.root, folder, experiment.command, params, running
+                config.root, folder, experiment.command, params, running, stopping
             )
             report({"event": "ended", "run": run, **result})
             results.append(result)

labnotes-0.0.22/src/labnotes/runner/wait_for_group.py

@@ -0,0 +1,11 @@
+import asyncio
+import os
+
+
+async def wait_for_group(group: int) -> None:
+    while True:
+        try:
+            os.killpg(group, 0)
+        except ProcessLookupError:
+            return
+        await asyncio.sleep(0.1)

{labnotes-0.0.20 → labnotes-0.0.22}/src/labnotes/summarize_config.py

@@ -1,7 +1,6 @@
 from math import prod
 
-# What the runner counts toward repeats.
-COMPLETED_RUN = "exit_code = 0 AND NOT coalesce(excluded, 0)"
+from labnotes.default_counts import DEFAULT_COUNTS
 
 
 def summarize_config(config: dict[str, object] | None) -> dict[str, object]:
@@ -15,12 +14,13 @@ def summarize_config(config: dict[str, object] | None) -> dict[str, object]:
     repeats = repeats if isinstance(repeats, int) else None
     cells = prod(len(values) for values in varies.values())
     command = config.get("command")
+    counts = config.get("counts")
     return {
         "fixed": {},
         "varies": varies,
         "cell_count": cells,
         "runs_per_cell": repeats,
         "target": cells * repeats if repeats is not None else None,
-        "completed_run": COMPLETED_RUN,
+        "completed_run": counts if isinstance(counts, str) else DEFAULT_COUNTS,
         "other": {} if command is None else {"command": command},
     }

{labnotes-0.0.20 → labnotes-0.0.22}/src/labnotes/tables/experiment_rows.py

@@ -1,4 +1,7 @@
+import json
+
 from labnotes.models import LabnotesConfig
+from labnotes.summarize_config import summarize_config
 from labnotes.tables.list_experiment_runs import list_experiment_runs
 from labnotes.tables.open_tables import open_tables
 from labnotes.tables.summarize_experiments import summarize_experiments
@@ -13,5 +16,10 @@ async def experiment_rows(
         return None
     match name, action:
         case str(), "runs":
-            return await list_experiment_runs(tables, name)
+            [row] = rows
+            stored = row["config"]
+            summary = summarize_config(json.loads(str(stored)) if stored else None)
+            return await list_experiment_runs(
+                tables, name, str(summary["completed_run"])
+            )
     return rows

labnotes-0.0.22/src/labnotes/tables/list_experiment_runs.py

@@ -0,0 +1,16 @@
+from dirsql import DirSQL
+
+from labnotes.sql_quote import quote_string
+
+
+async def list_experiment_runs(
+    tables: DirSQL, name: str, counts: str
+) -> list[dict[str, object]]:
+    try:
+        return await tables.query(
+            f"SELECT id, created, ended, exit_code, error, ({counts}) AS counted,"
+            " params, folder FROM runs"
+            f" WHERE experiment = {quote_string(name)} ORDER BY created, id"
+        )
+    except RuntimeError as error:
+        raise ValueError(f"{name}: counts doesn't work: {error}") from error

{labnotes-0.0.20 → labnotes-0.0.22}/src/labnotes/tables/open_tables.py

@@ -31,8 +31,8 @@ CREATE TABLE files (
 RUNS = """
 CREATE TABLE runs (
   experiment TEXT, id TEXT, folder TEXT, created TEXT, ended TEXT,
-  exit_code INTEGER, error TEXT, excluded INTEGER, reason TEXT,
-  stdout TEXT, stderr TEXT, params TEXT,
+  exit_code INTEGER, error TEXT,
+  stdout TEXT, stderr TEXT, params TEXT, run TEXT,
   PRIMARY KEY (experiment, id)
 )
 """

{labnotes-0.0.20 → labnotes-0.0.22}/src/labnotes/tables/read_run.py

@@ -20,10 +20,9 @@ def read_run(root: Path, template: str, path: str) -> list[dict[str, object]]:
             "ended": run.get("ended"),
             "exit_code": run.get("exit_code"),
             "error": run.get("error"),
-            "excluded": run.get("excluded") is True,
-            "reason": run.get("reason"),
             "stdout": f"{folder}/stdout.log",
             "stderr": f"{folder}/stderr.log",
             "params": json.dumps(run.get("params", {})),
+            "run": json.dumps(run),
         }
     ]

labnotes-0.0.20/src/labnotes/tables/list_experiment_runs.py

@@ -1,11 +0,0 @@
-from dirsql import DirSQL
-
-from labnotes.sql_quote import quote_string
-
-
-async def list_experiment_runs(tables: DirSQL, name: str) -> list[dict[str, object]]:
-    return await tables.query(
-        "SELECT id, created, ended, exit_code, error, excluded, reason, params, folder"
-        " FROM runs"
-        f" WHERE experiment = {quote_string(name)} ORDER BY created, id"
-    )