labnotes 0.0.131__tar.gz → 0.0.133__tar.gz

{labnotes-0.0.131 → labnotes-0.0.133}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.0.131
+Version: 0.0.133
 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.133/src/labnotes/__init__.py

@@ -0,0 +1,6 @@
+from labnotes import view
+from labnotes.get_state import get_state
+from labnotes.log import log
+from labnotes.set_state import set_state
+
+__all__ = ["get_state", "log", "set_state", "view"]

{labnotes-0.0.131 → labnotes-0.0.133}/src/labnotes/context.md

@@ -103,6 +103,18 @@ 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.
+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
+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`.
+Nested labnotes invocations clear inherited `LABNOTES_*` context for their
+children and set their own hook and run variables.
 `[env]` in `experiment.toml` sets string environment values for `command`,
 `meta`, `setup`, and `teardown`. `[experiment.env]` in `.labnotes.toml`
 provides shared values; experiment values replace them by name. Variables in

labnotes-0.0.133/src/labnotes/get_state.py

@@ -0,0 +1,15 @@
+import json
+
+from labnotes.state_path import state_path
+
+
+def get_state() -> dict[str, object]:
+    """Read setup's invocation state from a hook or run command."""
+    path = state_path()
+    try:
+        state = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return {}
+    if not isinstance(state, dict):
+        raise ValueError("Invocation state must be a JSON object")
+    return state

{labnotes-0.0.131 → labnotes-0.0.133}/src/labnotes/runner/execute_run.py

@@ -14,6 +14,7 @@ from labnotes.runner.shell_command import shell_command
 from labnotes.runner.stop_then_kill import GRACE_SECONDS
 from labnotes.runner.wait_for_tree import wait_for_tree
 from labnotes.runner.write_run_json import write_run_json
+from labnotes.state_path import RUN_STATE_ENV
 from labnotes.tables.iso_time import iso_time
 from labnotes.tui.format_elapsed import format_elapsed
 
@@ -33,6 +34,7 @@ async def execute_run(
     meta: dict[str, object] | None = None,
     args: Sequence[str] = (),
     *,
+    state_file: Path,
     memory_interval: float,
     environment: dict[str, str] | None = None,
 ) -> dict[str, object]:
@@ -65,9 +67,16 @@ async def execute_run(
                 env={
                     "FORCE_COLOR": "1",
                     "CLICOLOR_FORCE": "1",
-                    **(os.environ if environment is None else environment),
+                    **{
+                        key: value
+                        for key, value in (
+                            os.environ if environment is None else environment
+                        ).items()
+                        if not key.startswith("LABNOTES_")
+                    },
                     LOG_ENV: str(folder / "log.jsonl"),
                     RUN_ENV: str(folder.resolve()),
+                    RUN_STATE_ENV: str(state_file),
                 },
                 stdout=stdout,
                 stderr=stderr,

{labnotes-0.0.131 → labnotes-0.0.133}/src/labnotes/runner/run_experiment.py

@@ -2,7 +2,9 @@ import asyncio
 import json
 import os
 import signal
+from contextlib import nullcontext
 from pathlib import Path
+from tempfile import TemporaryDirectory
 
 import psutil
 
@@ -27,6 +29,7 @@ from labnotes.runner.param_grid import param_grid
 from labnotes.runner.plan_runs import plan_runs
 from labnotes.runner.run_folder import run_folder
 from labnotes.runner.signal_tree import signal_tree
+from labnotes.state_path import STATE_ENV
 from labnotes.tables.experiment_run_ids import experiment_run_ids
 from labnotes.tables.list_experiment_runs import list_experiment_runs
 from labnotes.tables.open_tables import open_tables
@@ -263,6 +266,7 @@ async def run_experiment(
             stopped=lambda: run in stopped,
             meta=meta,
             args=args or (),
+            state_file=state_file,
             memory_interval=experiment.memory_interval,
             environment=fill_experiment_env(
                 experiment.env,
@@ -293,24 +297,33 @@ async def run_experiment(
             )
 
     listen(Controls(interrupt, set_concurrency, kill, finish))
-    # Like vitest's globalSetup: a failed setup still gets its teardown.
-    try:
-        if experiment.setup is not None:
-            report({"event": "setting up"})
-            await invocation_hook(
-                config.root,
-                "setup",
-                fill_dirs(experiment.setup, dirs),
-                hook_env["setup"],
-            )
-        fill()
-        await done.wait()
-        await asyncio.gather(*started)
-    except BaseException:
+    with (
+        nullcontext(dirs["invocation_dir"])
+        if dirs
+        else TemporaryDirectory(prefix="labnotes-state-")
+    ) as state_dir:
+        state_file = Path(state_dir) / "state.json"
+        for hook in ("setup", "teardown"):
+            if hook in hook_env:
+                hook_env[hook][STATE_ENV] = str(state_file)
+        # Like vitest's globalSetup: a failed setup still gets its teardown.
         try:
-            await teardown()
-        except Exception as failure:  # noqa: BLE001
-            report({"event": "teardown failed", "error": str(failure)})
-        raise
-    await teardown()
+            if experiment.setup is not None:
+                report({"event": "setting up"})
+                await invocation_hook(
+                    config.root,
+                    "setup",
+                    fill_dirs(experiment.setup, dirs),
+                    hook_env["setup"],
+                )
+            fill()
+            await done.wait()
+            await asyncio.gather(*started)
+        except BaseException:
+            try:
+                await teardown()
+            except Exception as failure:  # noqa: BLE001
+                report({"event": "teardown failed", "error": str(failure)})
+            raise
+        await teardown()
     return results

labnotes-0.0.133/src/labnotes/set_state.py

@@ -0,0 +1,11 @@
+import json
+
+from labnotes.get_state import get_state
+from labnotes.state_path import state_path
+
+
+def set_state(values: dict[str, object]) -> None:
+    """Merge setup's JSON state by key for this invocation's teardown."""
+    path = state_path(writable=True)
+    content = json.dumps({**get_state(), **values})
+    path.write_text(content, encoding="utf-8")

labnotes-0.0.133/src/labnotes/state_path.py

@@ -0,0 +1,18 @@
+import os
+from pathlib import Path
+
+STATE_ENV = "LABNOTES_STATE"
+RUN_STATE_ENV = "LABNOTES_RUN_STATE"
+
+
+def state_path(*, writable: bool = False) -> Path:
+    value = os.environ.get(STATE_ENV)
+    if not value and not writable:
+        value = os.environ.get(RUN_STATE_ENV)
+    if not value:
+        raise RuntimeError(
+            "State is only writable in setup and teardown hooks"
+            if writable
+            else "State is only available in setup, runs, and teardown"
+        )
+    return Path(value)

labnotes-0.0.131/src/labnotes/__init__.py

@@ -1,4 +0,0 @@
-from labnotes import view
-from labnotes.log import log
-
-__all__ = ["log", "view"]