labnotes 0.2.5__tar.gz → 0.2.7__tar.gz

{labnotes-0.2.5 → labnotes-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.2.5
+Version: 0.2.7
 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>
@@ -20,6 +20,7 @@ Requires-Dist: psutil>=7.2.2
 Requires-Dist: rich>=14
 Requires-Dist: starlette>=1.8.0
 Requires-Dist: textual>=8.2.8
+Requires-Dist: tomlkit>=0.15.2
 Requires-Dist: uvicorn>=0.54.0
 Description-Content-Type: text/markdown
 
@@ -83,7 +84,10 @@ one. Piped, they print a table.
 
 `labnotes experiments new [NAME]` creates an experiment folder with a starter
 `experiment.toml`, picking a random name if you give none. `new` itself can't
-be an experiment name.
+be an experiment name. `--command`, `--param NAME=VALUE` (repeat it for several
+values) and `--repeats` write those settings into the file. `--from OTHER`
+copies another experiment's `experiment.toml` and files, never its runs, and
+records `from = "OTHER"`; the other flags replace the copied values.
 
 `labnotes experiments foo run` runs `foo` from its `experiment.toml`, in the
 experiments folder:

{labnotes-0.2.5 → labnotes-0.2.7}/README.md

@@ -58,7 +58,10 @@ one. Piped, they print a table.
 
 `labnotes experiments new [NAME]` creates an experiment folder with a starter
 `experiment.toml`, picking a random name if you give none. `new` itself can't
-be an experiment name.
+be an experiment name. `--command`, `--param NAME=VALUE` (repeat it for several
+values) and `--repeats` write those settings into the file. `--from OTHER`
+copies another experiment's `experiment.toml` and files, never its runs, and
+records `from = "OTHER"`; the other flags replace the copied values.
 
 `labnotes experiments foo run` runs `foo` from its `experiment.toml`, in the
 experiments folder:

{labnotes-0.2.5 → labnotes-0.2.7}/pyproject.toml

@@ -25,6 +25,7 @@ dependencies = [
     "rich>=14",
     "starlette>=1.8.0",
     "textual>=8.2.8",
+    "tomlkit>=0.15.2",
     "uvicorn>=0.54.0",
 ]
 

{labnotes-0.2.5 → labnotes-0.2.7}/src/labnotes/cli.py

@@ -2,6 +2,7 @@ from pathlib import Path
 
 import click
 
+from labnotes.command_line_group import CommandLineGroup
 from labnotes.context_guide import context_guide
 from labnotes.experiments import experiments
 from labnotes.init import init
@@ -11,6 +12,7 @@ from labnotes.server import server
 
 
 @click.group(
+    cls=CommandLineGroup,
     invoke_without_command=True,
     help="Manage experiments in a folder. `labnotes context` prints a guide for"
     " coding agents.",

labnotes-0.2.7/src/labnotes/command_line_group.py

@@ -0,0 +1,20 @@
+import shlex
+from typing import Any
+
+import click
+
+COMMAND_LINE = "labnotes.command_line"
+
+
+class CommandLineGroup(click.Group):
+    def make_context(
+        self,
+        info_name: str | None,
+        args: list[str],
+        parent: click.Context | None = None,
+        **extra: Any,
+    ) -> click.Context:
+        command_line = shlex.join(["labnotes", *args])
+        ctx = super().make_context(info_name, args, parent, **extra)
+        ctx.meta[COMMAND_LINE] = command_line
+        return ctx

{labnotes-0.2.5 → labnotes-0.2.7}/src/labnotes/context.md

@@ -43,7 +43,10 @@ keys that never come.
 
 `labnotes experiments new [NAME]` creates an experiment folder with a starter
 `experiment.toml`, picking a random name if you give none. `new` itself can't
-be an experiment name.
+be an experiment name. `--command`, `--param NAME=VALUE` (repeat it for several
+values) and `--repeats` write those settings into the file. `--from OTHER`
+copies another experiment's `experiment.toml` and files, never its runs, and
+records `from = "OTHER"`; the other flags replace the copied values.
 
 `labnotes experiments foo run` runs `foo` from its `experiment.toml`, in the
 experiments folder:

labnotes-0.2.7/src/labnotes/copy_experiment.py

@@ -0,0 +1,12 @@
+import shutil
+from pathlib import Path
+
+
+def copy_experiment(source: Path, target: Path, runs: Path) -> None:
+    def skip(folder: str, names: list[str]) -> set[str]:
+        here = Path(folder)
+        if here == runs:
+            return {name for name in names if (here / name / "run.json").exists()}
+        return {name for name in names if here / name == runs}
+
+    shutil.copytree(source, target, ignore=skip, symlinks=True)

{labnotes-0.2.5 → labnotes-0.2.7}/src/labnotes/create_experiment.py

@@ -1,7 +1,10 @@
 from pathlib import Path
 
+from labnotes.copy_experiment import copy_experiment
+from labnotes.experiment_definition import experiment_definition
 from labnotes.models import LabnotesConfig
 from labnotes.runner.new_run_id import new_run_id
+from labnotes.runner.runs_parent import runs_parent
 
 STARTER = """\
 # Runs from the project root. {run_dir} becomes the run's folder.
@@ -14,7 +17,14 @@ repeats = 1
 """
 
 
-def create_experiment(config: LabnotesConfig, name: str | None) -> Path:
+def create_experiment(
+    config: LabnotesConfig,
+    name: str | None,
+    source: str | None = None,
+    command: str | None = None,
+    repeats: int | None = None,
+    params: dict[str, list[object]] | None = None,
+) -> Path:
     def folder(candidate: str) -> Path:
         return config.root / config.experiments.replace("{experiment}", candidate)
 
@@ -31,6 +41,19 @@ def create_experiment(config: LabnotesConfig, name: str | None) -> Path:
     path = folder(name)
     if path.exists():
         raise ValueError(f"{name} already exists at {path}.")
-    path.mkdir(parents=True)
-    (path / "experiment.toml").write_text(STARTER, encoding="utf-8")
+    text = STARTER
+    if source is not None:
+        origin = folder(source) / "experiment.toml"
+        if not origin.is_file():
+            raise ValueError(f"No experiment.toml for {source} at {origin}.")
+        text = origin.read_text(encoding="utf-8")
+        copy_experiment(
+            origin.parent, path, runs_parent(config.root, config.runs, source)
+        )
+    else:
+        path.mkdir(parents=True)
+    (path / "experiment.toml").write_text(
+        experiment_definition(text, source, command, repeats, params or {}),
+        encoding="utf-8",
+    )
     return path

labnotes-0.2.7/src/labnotes/experiment_definition.py

@@ -0,0 +1,22 @@
+import tomlkit
+
+
+def experiment_definition(
+    text: str,
+    source: str | None,
+    command: str | None,
+    repeats: int | None,
+    params: dict[str, list[object]],
+) -> str:
+    document = tomlkit.parse(text)
+    document.pop("from", None)
+    if command is not None:
+        document["command"] = command
+    if repeats is not None:
+        document["repeats"] = repeats
+    if params:
+        table = document.setdefault("params", tomlkit.table())
+        for name, values in params.items():
+            table[name] = values
+    head = "" if source is None else tomlkit.dumps({"from": source})
+    return head + tomlkit.dumps(document)

{labnotes-0.2.5 → labnotes-0.2.7}/src/labnotes/experiments.py

@@ -4,10 +4,12 @@ from pathlib import Path
 
 import click
 
+from labnotes.command_line_group import COMMAND_LINE
 from labnotes.create_experiment import create_experiment
 from labnotes.runner.start_experiment import start_experiment
 from labnotes.utils.format_bytes import format_bytes
 from labnotes.load_config import load_config
+from labnotes.parse_params import parse_params
 from labnotes.parse_subset import parse_subset
 from labnotes.print_rows import print_rows
 from labnotes.read_config import CONFIG_FILE
@@ -32,7 +34,8 @@ class PassthroughCommand(click.Command):
 @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"
+    " `new [NAME]` creates one, from --command, --param, --repeats and"
+    " --from OTHER if given. With run, --PARAM=VALUE runs only the"
     " 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"
@@ -79,6 +82,31 @@ class PassthroughCommand(click.Command):
     help="With run: shell command to run once after every run ends."
     " Overrides experiment.toml and .labnotes.toml.",
 )
+@click.option(
+    "--command",
+    metavar="COMMAND",
+    help="With new: the experiment's command.",
+)
+@click.option(
+    "--param",
+    "params",
+    multiple=True,
+    metavar="NAME=VALUE",
+    help="With new: a value for a param, parsed as TOML or else taken as a"
+    " string. Repeat it for several values.",
+)
+@click.option(
+    "--repeats",
+    type=click.IntRange(min=1),
+    help="With new: how many times each combination runs.",
+)
+@click.option(
+    "--from",
+    "source",
+    metavar="OTHER",
+    help="With new: start from OTHER's experiment.toml and files, never its"
+    " runs. Other flags replace the copied values.",
+)
 @click.pass_context
 def experiments(
     ctx: click.Context,
@@ -90,6 +118,10 @@ def experiments(
     timeout: int | None,
     setup: str | None,
     teardown: str | None,
+    command: str | None,
+    params: tuple[str, ...],
+    repeats: int | None,
+    source: str | None,
 ) -> None:
     passthrough: list[str] | None = ctx.meta.get(PASSTHROUGH)
     config = load_config(ctx)
@@ -97,10 +129,22 @@ def experiments(
         raise click.ClickException(
             f"No {CONFIG_FILE} here. Run labnotes init, or pass -c PATH."
         )
+    if name != "new":
+        given = {
+            "--command": command,
+            "--param": params or None,
+            "--repeats": repeats,
+            "--from": source,
+        }
+        for flag, value in given.items():
+            if value is not None:
+                raise click.UsageError(f"{flag} needs new.")
     match name, action:
         case "new", _:
             try:
-                path = create_experiment(config, action)
+                path = create_experiment(
+                    config, action, source, command, repeats, parse_params(list(params))
+                )
             except ValueError as error:
                 raise click.ClickException(str(error)) from error
             click.echo(f"Created {path / 'experiment.toml'}")
@@ -120,6 +164,7 @@ def experiments(
                 passthrough or None,
                 setup,
                 teardown,
+                ctx.meta.get(COMMAND_LINE),
             )
             try:
                 if sys.stdout.isatty() and sys.stderr.isatty():

labnotes-0.2.7/src/labnotes/parse_param_value.py

@@ -0,0 +1,8 @@
+import tomllib
+
+
+def parse_param_value(value: str) -> object:
+    try:
+        return tomllib.loads(f"value = {value}")["value"]
+    except tomllib.TOMLDecodeError:
+        return value

labnotes-0.2.7/src/labnotes/parse_params.py

@@ -0,0 +1,11 @@
+from labnotes.parse_param_value import parse_param_value
+
+
+def parse_params(pairs: list[str]) -> dict[str, list[object]]:
+    params: dict[str, list[object]] = {}
+    for pair in pairs:
+        name, equals, value = pair.partition("=")
+        if not equals or not name:
+            raise ValueError(f"--param {pair} must look like NAME=VALUE.")
+        params.setdefault(name, []).append(parse_param_value(value))
+    return params

{labnotes-0.2.5 → labnotes-0.2.7}/src/labnotes/runner/execute_run.py

@@ -5,6 +5,7 @@ import os
 import time
 from collections.abc import Callable, Sequence
 from datetime import UTC, datetime
+from importlib.metadata import version
 from pathlib import Path
 
 import psutil
@@ -43,6 +44,7 @@ async def execute_run(
     environment: dict[str, str] | None = None,
     git_info: dict[str, str | bool] | None = None,
     continues: bool = False,
+    command_line: str | None = None,
 ) -> dict[str, object]:
     resolved = shell_command(command, folder, params, args)
     git = git_info if git_info is not None else await asyncio.to_thread(run_git, root)
@@ -56,6 +58,8 @@ async def execute_run(
         "ended_by": None,
         "signal": None,
         "git": git,
+        "labnotes_version": version("labnotes"),
+        "labnotes_command": command_line,
     }
     if args:
         run["args"] = list(args)
@@ -76,6 +80,8 @@ async def execute_run(
             "error": None,
             "git": None if git is None else git["commit"],
             "args": list(args),
+            "labnotes_version": run["labnotes_version"],
+            "labnotes_command": command_line,
             **logs,
         }
         record = folder / "run.json"

{labnotes-0.2.5 → labnotes-0.2.7}/src/labnotes/runner/first_invocation.py

@@ -8,6 +8,8 @@ def first_invocation(run: dict[str, object]) -> dict[str, object]:
         "error": run.get("error"),
         "git": git.get("commit") if isinstance(git, dict) else None,
         "args": run.get("args", []),
+        "labnotes_version": run.get("labnotes_version"),
+        "labnotes_command": run.get("labnotes_command"),
         "stdout": "stdout.log",
         "stderr": "stderr.log",
     }

{labnotes-0.2.5 → labnotes-0.2.7}/src/labnotes/runner/read_experiment_config.py

@@ -28,6 +28,7 @@ SETTINGS = {
     "teardown",
     "env",
     "continues",
+    "from",
 }
 HOOKS = ("setup", "teardown")
 VIEWS = {"runs"}
@@ -86,6 +87,9 @@ def read_experiment_config(
     memory_interval = values.get("memory_interval", DEFAULT_MEMORY_INTERVAL)
     if not is_non_negative_number(memory_interval):
         raise ValueError(f"{path}: memory_interval must be 0 or more seconds")
+    origin = values.get("from")
+    if origin is not None and (not isinstance(origin, str) or not origin.strip()):
+        raise ValueError(f"{path}: from must be an experiment name")
     for hook in HOOKS:
         run = values.get(hook)
         if run is not None and (not isinstance(run, str) or not run.strip()):

{labnotes-0.2.5 → labnotes-0.2.7}/src/labnotes/runner/run_experiment.py

@@ -53,6 +53,7 @@ async def run_experiment(
     args: list[str] | None = None,
     environment: dict[str, str] | None = None,
     snapshot: ProjectSnapshot | None = None,
+    command_line: str | None = None,
 ) -> list[dict[str, object]]:
     command_root = snapshot.root if snapshot is not None else config.root
     inherited = dict(os.environ) if environment is None else environment
@@ -323,6 +324,7 @@ async def run_experiment(
                 else None
             ),
             continues=experiment.continues,
+            command_line=command_line,
         )
         del running[run], trees[run]
         report({"event": "ended", "run": run, **result})

{labnotes-0.2.5 → labnotes-0.2.7}/src/labnotes/runner/start_experiment.py

@@ -17,6 +17,7 @@ def start_experiment(
     args: list[str] | None,
     setup: str | None,
     teardown: str | None,
+    command_line: str | None = None,
 ) -> Start:
     async def start(report: Report, listen: Listen) -> list[dict[str, object]]:
         experiment, limit = await prepare_experiment(
@@ -35,6 +36,7 @@ def start_experiment(
                 only=only,
                 args=args,
                 snapshot=snapshot,
+                command_line=command_line,
             )
 
     return start

{labnotes-0.2.5 → labnotes-0.2.7}/uv.lock

@@ -568,6 +568,7 @@ dependencies = [
     { name = "rich" },
     { name = "starlette" },
     { name = "textual" },
+    { name = "tomlkit" },
     { name = "uvicorn" },
 ]
 
@@ -597,6 +598,7 @@ requires-dist = [
     { name = "rich", specifier = ">=14" },
     { name = "starlette", specifier = ">=1.8.0" },
     { name = "textual", specifier = ">=8.2.8" },
+    { name = "tomlkit", specifier = ">=0.15.2" },
     { name = "uvicorn", specifier = ">=0.54.0" },
 ]
 
@@ -1307,6 +1309,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/fb/be/35261223d9416a0751cdff1c7b4a6f881387218a12d439fe22fefebc8c04/textual-8.2.8-py3-none-any.whl", hash = "sha256:267375fd402dc8d981457212efa71f0e3365fd17bba144ba9bb3ed7563cb374a", size = 731418, upload-time = "2026-06-30T06:51:26.364Z" },
 ]
 
+[[package]]
+name = "tomlkit"
+version = "0.15.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/08/72/fc01563df95c189a9f65850096bdc205bc2fe37da6c740cd64afaf18d07e/tomlkit-0.15.2.tar.gz", hash = "sha256:83e32755ba1d20d9340bd069ee97e9f6232ba2346b63ffcba425de01f7e327a6", size = 190522, upload-time = "2026-10-16T04:07:08.166Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/da/46/7d84138a60a8bd796825b2d38ebe92d0d16501ca57d501b7c5d677401bbc/tomlkit-0.15.2-py3-none-any.whl", hash = "sha256:05562412163a3037b94497385fb7f9204c637bc605af7a48199e41cf2272f437", size = 52225, upload-time = "2026-10-16T04:07:09.216Z" },
+]
+
 [[package]]
 name = "tornado"
 version = "6.5.10"