labnotes 0.2.4__tar.gz → 0.2.6__tar.gz

{labnotes-0.2.4 → labnotes-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.2.4
+Version: 0.2.6
 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.4 → labnotes-0.2.6}/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.4 → labnotes-0.2.6}/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.4 → labnotes-0.2.6}/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.6/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.4 → labnotes-0.2.6}/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.6/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.4 → labnotes-0.2.6}/src/labnotes/experiments.py

@@ -8,6 +8,7 @@ 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 +33,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 +81,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 +117,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 +128,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'}")

labnotes-0.2.6/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.6/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.4 → labnotes-0.2.6}/src/labnotes/runner/project_snapshot.py

@@ -11,6 +11,8 @@ from pathlib import Path
 from tempfile import TemporaryDirectory
 from types import FrameType
 
+from labnotes.runner.untracked_diff import untracked_diff
+
 
 @dataclass
 class ProjectSnapshot:
@@ -37,7 +39,7 @@ def project_snapshot(root: Path) -> Iterator[ProjectSnapshot]:
         sha = git(root, "rev-parse", "HEAD").decode("ascii").strip()
         repo_root = Path(git(root, "rev-parse", "--show-toplevel").decode().strip())
         project_prefix = root.resolve().relative_to(repo_root.resolve())
-        diff = git(repo_root, "diff", "HEAD")
+        diff = git(repo_root, "diff", "HEAD") + untracked_diff(repo_root)
     except (OSError, subprocess.SubprocessError):
         logging.warning("Project has no readable Git HEAD; running from the live tree")
         yield ProjectSnapshot(root)

{labnotes-0.2.4 → labnotes-0.2.6}/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.6/src/labnotes/runner/untracked_diff.py

@@ -0,0 +1,39 @@
+import os
+import subprocess
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+
+def untracked_diff(repo_root: Path) -> bytes:
+    """Patch adding every untracked, non-ignored file, as the snapshot copies them."""
+    listing = subprocess.check_output(
+        ["git", "ls-files", "-o", "--exclude-standard", "-z"],
+        cwd=repo_root,
+        stderr=subprocess.DEVNULL,
+    )
+    # A trailing slash marks an untracked nested repository, which git cannot add.
+    paths = [path for path in listing.split(b"\0") if path and not path.endswith(b"/")]
+    if not paths:
+        return b""
+    with TemporaryDirectory(prefix="labnotes-index-") as directory:
+        # A throwaway index keeps the user's real index untouched.
+        env = {**os.environ, "GIT_INDEX_FILE": str(Path(directory) / "index")}
+        subprocess.run(
+            ["git", "add", "--intent-to-add", "--pathspec-from-file=-"]
+            + ["--pathspec-file-nul"],
+            cwd=repo_root,
+            env=env,
+            input=b"\0".join(paths),
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=True,
+        )
+        # Files over 1 MiB show as binary so stray data cannot bloat every patch.
+        return subprocess.run(
+            ["git", "-c", "core.bigFileThreshold=1m", "diff"],
+            cwd=repo_root,
+            env=env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            check=True,
+        ).stdout

{labnotes-0.2.4 → labnotes-0.2.6}/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"