labnotes 0.0.82__tar.gz → 0.0.84__tar.gz

{labnotes-0.0.82 → labnotes-0.0.84}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.0.82
+Version: 0.0.84
 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>
@@ -68,7 +68,11 @@ labnotes experiments foo        # the same, plus config
 labnotes experiments foo runs   # foo's runs, oldest first
 ```
 
-Each takes `--format table` (the default) or `--format json`.
+Each takes `--format table` or `--format json`, which print rows and exit.
+Without `--format`, `labnotes experiments` and `labnotes experiments foo` open
+a browser in a terminal: the experiment list, Enter to open one, Escape to go
+back. An experiment shows its runs grouped by invocation; Space opens 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

{labnotes-0.0.82 → labnotes-0.0.84}/README.md

@@ -44,7 +44,11 @@ labnotes experiments foo        # the same, plus config
 labnotes experiments foo runs   # foo's runs, oldest first
 ```
 
-Each takes `--format table` (the default) or `--format json`.
+Each takes `--format table` or `--format json`, which print rows and exit.
+Without `--format`, `labnotes experiments` and `labnotes experiments foo` open
+a browser in a terminal: the experiment list, Enter to open one, Escape to go
+back. An experiment shows its runs grouped by invocation; Space opens 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

{labnotes-0.0.82 → labnotes-0.0.84}/src/labnotes/context.md

@@ -29,12 +29,14 @@ 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.
 
 ```sh
-labnotes experiments            # name, last_run, created, files, runs
-labnotes experiments foo        # the same, plus config
-labnotes experiments foo runs   # foo's runs, oldest first
+labnotes experiments --format json            # name, last_run, created, files, runs
+labnotes experiments foo --format json        # the same, plus config
+labnotes experiments foo runs --format json   # foo's runs, oldest first
 ```
 
-Each takes `--format table` (the default) or `--format json`; use `--format json` when you parse the output.
+Always pass `--format json` (to parse) or `--format table`. Without `--format`,
+`labnotes experiments` and `labnotes experiments foo` open an interactive
+browser when they find a terminal, and wait for 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
@@ -58,11 +60,11 @@ 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 (1 if omitted), round-robin, on every
 `run`, whatever is already on disk. That is `mode = "adhoc"`, the default.
-`mode = "fill"` counts what is there: only runs that count fill a combination,
+`mode = "matrix"` counts what is there: only runs that count fill a combination,
 so running again fills in what failed or never ran. `mode` under
 `[experiments]` in `.labnotes.toml` sets it for every experiment that doesn't
 set its own.
-Each run gets a new run folder. In `fill` mode it is named for the UTC time it was planned
+Each run gets a new run folder. In `matrix` mode it is named for the UTC time it was planned
 (`runs/20261020-000429-brave-fox`). In `adhoc` mode a `run` command that plans one run names
 its folder the same way. One that plans more gets one folder named that way, and its runs nest
 inside it (`runs/20261020-000429-brave-fox/quiet-river`); the run id is that path under `runs/`. Either way, folder listings sort by start. `command` runs in a shell from the root, with
@@ -91,7 +93,7 @@ A script run by labnotes should:
 - stop any background process it starts before it exits; the run ends when `command` exits.
 - flush its output as it goes (`print(..., flush=True)`, or `PYTHONUNBUFFERED=1`), so the live view shows it as it happens.
 
-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.
+Runs can take a long time. Start `run` in the background, then check on it with `labnotes experiments foo runs --format json`; a run with no `ended` is still going.
 
 In a terminal, `run` shows a live table of runs (status and time) and stays
 open when they finish. Failed runs show their status in red; `f` hides or shows them, and `r` on one

{labnotes-0.0.82 → labnotes-0.0.84}/src/labnotes/experiments.py

@@ -11,6 +11,7 @@ from labnotes.print_rows import print_rows
 from labnotes.read_config import CONFIG_FILE
 from labnotes.runner.run_headless import run_headless
 from labnotes.tables.experiment_rows import experiment_rows
+from labnotes.tui.browse_tui import browse_tui
 from labnotes.tui.run_tui import run_tui
 
 
@@ -24,8 +25,8 @@ from labnotes.tui.run_tui import run_tui
     "--format",
     "output_format",
     type=click.Choice(["table", "json"]),
-    default="table",
-    show_default=True,
+    help="Print rows and exit. Unset, a terminal browses them instead;"
+    " anything else gets table.",
 )
 @click.option(
     "--concurrency",
@@ -44,7 +45,7 @@ def experiments(
     ctx: click.Context,
     name: str | None,
     action: str | None,
-    output_format: str,
+    output_format: str | None,
     concurrency: int | None,
     experiment_config: Path | None,
 ) -> None:
@@ -75,10 +76,21 @@ def experiments(
             return
     if action not in (None, "runs"):
         raise click.UsageError(f"Unknown action {action}. Use runs or run.")
+    if (
+        action is None
+        and output_format is None
+        and sys.stdout.isatty()
+        and sys.stderr.isatty()
+    ):
+        try:
+            browse_tui(config, name)
+        except ValueError as error:
+            raise click.ClickException(str(error)) from error
+        return
     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)
+    print_rows(rows, output_format or "table")

labnotes-0.0.84/src/labnotes/modes.py

@@ -0,0 +1,2 @@
+MODES = ("matrix", "adhoc")
+DEFAULT_MODE = "adhoc"

{labnotes-0.0.82 → labnotes-0.0.84}/src/labnotes/read_config.py

@@ -24,7 +24,7 @@ def read_config(path: Path) -> LabnotesConfig:
     experiments = values.get("experiments", {})
     mode = experiments.get("mode", DEFAULT_MODE)
     if mode not in MODES:
-        raise ValueError(f"{path}: [experiments] mode must be fill or adhoc")
+        raise ValueError(f"{path}: [experiments] mode must be matrix or adhoc")
     concurrency = experiments.get("concurrency", 1)
     if not is_positive_int(concurrency):
         raise ValueError(

{labnotes-0.0.82 → labnotes-0.0.84}/src/labnotes/runner/read_experiment_config.py

@@ -44,7 +44,7 @@ def read_experiment_config(
         raise ValueError(f"{path}: counts must be a SQL condition")
     mode = values.get("mode", mode)
     if mode not in MODES:
-        raise ValueError(f"{path}: mode must be fill or adhoc")
+        raise ValueError(f"{path}: mode must be matrix or adhoc")
     concurrency = values.get("concurrency", concurrency)
     if not is_positive_int(concurrency):
         raise ValueError(f"{path}: concurrency must be a positive integer")

{labnotes-0.0.82 → labnotes-0.0.84}/src/labnotes/runner/run_experiment.py

@@ -37,7 +37,7 @@ async def run_experiment(
     existing = await experiment_run_ids(tables, name)
     finished: list[dict[str, object]] = []
     match experiment.mode:
-        case "fill":
+        case "matrix":
             counted = await list_experiment_runs(tables, name, experiment.counts)
             finished = [json.loads(str(r["params"])) for r in counted if r["counted"]]
     planned: set[str] = set()

{labnotes-0.0.82 → labnotes-0.0.84}/src/labnotes/summarize_config.py

@@ -15,13 +15,13 @@ def summarize_config(config: dict[str, object] | None, mode: str) -> dict[str, o
     cells = prod(len(values) for values in varies.values())
     command = config.get("command")
     counts = config.get("counts")
-    fill = config.get("mode", mode) == "fill"
+    matrix = config.get("mode", mode) == "matrix"
     return {
         "fixed": {},
         "varies": varies,
         "cell_count": cells,
         "runs_per_cell": repeats,
         "completed_run": counts if isinstance(counts, str) else DEFAULT_COUNTS,
-        "mode": "fill" if fill else "adhoc",
+        "mode": "matrix" if matrix else "adhoc",
         "other": {} if command is None else {"command": command},
     }

labnotes-0.0.84/src/labnotes/tui/browse_app.py

@@ -0,0 +1,25 @@
+from textual.app import App
+from textual.binding import Binding
+
+from labnotes.models import LabnotesConfig
+from labnotes.tables.open_tables import open_tables
+from labnotes.tui.experiment_screen import ExperimentScreen
+from labnotes.tui.experiments_screen import ExperimentsScreen
+
+
+class BrowseApp(App[BaseException | None]):
+    BINDINGS = [Binding("q", "quit", "Quit")]
+
+    def __init__(self, config: LabnotesConfig, name: str | None) -> None:
+        super().__init__()
+        self.config = config
+        self.experiment_name = name
+        self.title = config.root.name
+
+    def on_mount(self) -> None:
+        tables = open_tables(self.config)
+        self.push_screen(ExperimentsScreen(tables, self.config))
+        if self.experiment_name is not None:
+            self.push_screen(
+                ExperimentScreen(tables, self.config, self.experiment_name)
+            )

labnotes-0.0.84/src/labnotes/tui/browse_tui.py

@@ -0,0 +1,8 @@
+from labnotes.models import LabnotesConfig
+from labnotes.tui.browse_app import BrowseApp
+
+
+def browse_tui(config: LabnotesConfig, name: str | None) -> None:
+    error = BrowseApp(config, name).run()
+    if error is not None:
+        raise error

labnotes-0.0.84/src/labnotes/tui/experiment_screen.py

@@ -0,0 +1,80 @@
+from typing import Any
+
+from dirsql import DirSQL
+from starlette.datastructures import QueryParams
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.screen import Screen
+from textual.widgets import DataTable, Footer, Header
+from textual.worker import Worker, WorkerState
+
+from labnotes.load_experiment import load_experiment
+from labnotes.models import LabnotesConfig
+from labnotes.tui.invocation_columns import invocation_columns
+from labnotes.tui.invocation_rows import invocation_rows
+from labnotes.tui.runs_table import RunsTable
+
+
+class ExperimentScreen(Screen[None]):
+    BINDINGS = [
+        Binding("space", "open_invocation", "Open invocation"),
+        Binding("escape", "app.pop_screen", "Back"),
+    ]
+
+    def __init__(self, tables: DirSQL, config: LabnotesConfig, name: str) -> None:
+        super().__init__()
+        self.tables = tables
+        self.config = config
+        self.experiment_name = name
+        self.experiment: dict[str, Any] = {}
+        self.opened: set[str] = set()
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield RunsTable(id="runs", cursor_type="row")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.sub_title = self.experiment_name
+        self.run_worker(self.load(), exit_on_error=False)
+
+    def on_worker_state_changed(self, event: Worker.StateChanged) -> None:
+        if event.state == WorkerState.ERROR:
+            self.app.exit(event.worker.error)
+
+    async def load(self) -> None:
+        loaded = await load_experiment(
+            self.tables,
+            self.config.root,
+            self.config.mode,
+            self.experiment_name,
+            QueryParams(),
+        )
+        if loaded is None:
+            raise ValueError(f"No experiment named {self.experiment_name}.")
+        self.experiment = loaded
+        self.sub_title = str(loaded["display_name"])
+        self.query_one(DataTable).add_columns(*invocation_columns(loaded))
+        self.redraw()
+
+    def redraw(self) -> None:
+        table = self.query_one(DataTable)
+        row = table.cursor_row
+        table.clear()
+        for key, cells in invocation_rows(self.experiment, self.opened):
+            table.add_row(*cells, key=key)
+        table.move_cursor(row=row)
+
+    def action_open_invocation(self) -> None:
+        table = self.query_one(DataTable)
+        if not table.row_count:
+            return
+        key = str(table.coordinate_to_cell_key(table.cursor_coordinate).row_key.value)
+        groups = {
+            group["name"]
+            for group in self.experiment["run_groups"] or ()
+            if not group["flat"]
+        }
+        if key in groups:
+            self.opened ^= {key}
+            self.redraw()

labnotes-0.0.84/src/labnotes/tui/experiments_screen.py

@@ -0,0 +1,47 @@
+from dirsql import DirSQL
+from textual.app import ComposeResult
+from textual.screen import Screen
+from textual.widgets import DataTable, Footer, Header
+from textual.worker import Worker, WorkerState
+
+from labnotes.models import LabnotesConfig
+from labnotes.tables.summarize_experiments import summarize_experiments
+from labnotes.tui.experiment_screen import ExperimentScreen
+from labnotes.tui.runs_table import RunsTable
+
+
+class ExperimentsScreen(Screen[None]):
+    def __init__(self, tables: DirSQL, config: LabnotesConfig) -> None:
+        super().__init__()
+        self.tables = tables
+        self.config = config
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield RunsTable(id="experiments", cursor_type="row")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.run_worker(self.load(), exit_on_error=False)
+
+    def on_worker_state_changed(self, event: Worker.StateChanged) -> None:
+        if event.state == WorkerState.ERROR:
+            self.app.exit(event.worker.error)
+
+    async def load(self) -> None:
+        rows = await summarize_experiments(self.tables)
+        if not rows:
+            self.sub_title = "No experiments."
+            return
+        table = self.query_one(DataTable)
+        table.add_columns(*rows[0])
+        for row in rows:
+            table.add_row(
+                *("" if value is None else str(value) for value in row.values()),
+                key=str(row["name"]),
+            )
+
+    def on_data_table_row_selected(self, event: DataTable.RowSelected) -> None:
+        self.app.push_screen(
+            ExperimentScreen(self.tables, self.config, str(event.row_key.value))
+        )

labnotes-0.0.84/src/labnotes/tui/group_cells.py

@@ -0,0 +1,26 @@
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from rich.text import Text
+
+from labnotes.format_value import format_value
+
+
+def group_cells(
+    group: Mapping[str, Any], columns: Sequence[str], live: bool
+) -> list[object]:
+    status = Text.assemble(
+        (f"{group['passed']}✓", "green"), " ", (f"{group['failed']}✕", "red")
+    )
+    if group["unfinished"]:
+        mark, style = ("◐", "yellow") if live else ("–", "dim")
+        status.append(f" {group['unfinished']}{mark}", style=style)
+    cells: list[object] = [status, group["name"], str(len(group["runs"]))]
+    for column in columns[1:]:
+        if column == "started":
+            cells.append(group["started"] or "")
+        elif column in group["shared"]:
+            cells.append(format_value(group["shared"][column]))
+        else:
+            cells.append("")
+    return cells

labnotes-0.0.84/src/labnotes/tui/invocation_columns.py

@@ -0,0 +1,9 @@
+from collections.abc import Mapping
+from typing import Any
+
+
+def invocation_columns(experiment: Mapping[str, Any]) -> list[str]:
+    columns = ["", *experiment["run_columns"]]
+    if experiment["run_groups"] is not None:
+        columns.insert(2, "runs")
+    return columns

labnotes-0.0.84/src/labnotes/tui/invocation_rows.py

@@ -0,0 +1,31 @@
+from collections.abc import Collection, Mapping
+from typing import Any
+
+from labnotes.tui.group_cells import group_cells
+from labnotes.tui.run_cells import run_cells
+
+
+def invocation_rows(
+    experiment: Mapping[str, Any], opened: Collection[str]
+) -> list[tuple[str, list[object]]]:
+    columns = experiment["run_columns"]
+    live = experiment["runs_live"]
+    groups = experiment["run_groups"]
+    if groups is None:
+        return [
+            (str(run["id"]), run_cells(run, columns, False, live))
+            for run in experiment["runs_list"]
+        ]
+    rows = []
+    for group in groups:
+        if group["flat"]:
+            [run, *_] = group["runs"]
+            rows.append((str(run["id"]), run_cells(run, columns, True, live)))
+            continue
+        rows.append((group["name"], group_cells(group, columns, live)))
+        if group["name"] in opened:
+            rows += [
+                (str(run["id"]), run_cells(run, columns, True, live))
+                for run in group["runs"]
+            ]
+    return rows

labnotes-0.0.84/src/labnotes/tui/run_cells.py

@@ -0,0 +1,29 @@
+from collections.abc import Mapping, Sequence
+
+from rich.text import Text
+
+from labnotes.format_duration import format_duration
+from labnotes.format_value import format_value
+from labnotes.tui.dim import dim
+
+
+def run_cells(
+    run: Mapping[str, object], columns: Sequence[str], nested: bool, live: bool
+) -> list[object]:
+    if run["labnotes_unfinished"]:
+        status = Text("◐", style="yellow") if live else dim("–")
+    elif run["labnotes_completed"]:
+        status = Text("✓", style="green")
+    else:
+        status = Text("✕", style="red")
+    cells: list[object] = [status]
+    for column in columns:
+        value = run[column]
+        if column == "id" and nested:
+            child = str(value).partition("/")[2]
+            cells += [f"  {child}" if child else str(value), ""]
+        elif column == "duration":
+            cells.append(format_duration(value))  # type: ignore[arg-type]
+        else:
+            cells.append(format_value(value))
+    return cells

{labnotes-0.0.82 → labnotes-0.0.84}/testing-conventions.toml

@@ -14,13 +14,13 @@ reason = "last_stream is always the same str object taken from STREAMS, so is no
 path = "src/labnotes/runner/run_experiment.py"
 rules = ["mutation"]
 lines = [47]
-reason = "mode is validated to fill or adhoc; \"fill\" <= \"adhoc\" is false like ==, and both are interned literals so is equals =="
+reason = "mode is validated to matrix or adhoc; \"matrix\" <= \"adhoc\" is false like ==, and both are interned literals so is equals =="
 
 [[python.exempt]]
 path = "src/labnotes/load_experiment.py"
 rules = ["mutation"]
 lines = [59]
-reason = "summarize_config returns mode fill or adhoc; \"fill\" <= \"adhoc\" is false like ==, and both are interned literals so is equals =="
+reason = "summarize_config returns mode matrix or adhoc; \"matrix\" <= \"adhoc\" is false like ==, and both are interned literals so is equals =="
 
 [[python.exempt]]
 path = "src/labnotes/daemon/exit_when_idle.py"
@@ -45,3 +45,27 @@ path = "src/labnotes/run_control.py"
 rules = ["mutation"]
 lines = [38]
 reason = "argument counts are small ints, which CPython caches, so is not equals !="
+
+[[python.exempt]]
+path = "src/labnotes/tui/run_cells.py"
+rules = ["mutation"]
+lines = [22, 25]
+reason = "run columns come from string literals in load_experiment, which CPython interns, so is equals =="
+
+[[python.exempt]]
+path = "src/labnotes/tui/group_cells.py"
+rules = ["mutation"]
+lines = [20]
+reason = "run columns come from string literals in load_experiment, which CPython interns, so is equals =="
+
+[[python.exempt]]
+path = "src/labnotes/tui/experiment_screen.py"
+rules = ["mutation"]
+lines = [42]
+reason = "WorkerState members are singletons, so is equals =="
+
+[[python.exempt]]
+path = "src/labnotes/tui/experiments_screen.py"
+rules = ["mutation"]
+lines = [28, 37]
+reason = "WorkerState members are singletons, so is equals ==; every row of one query has the same keys, so any row names the columns"

{labnotes-0.0.82 → labnotes-0.0.84}/tests/integration/conftest.py

@@ -13,7 +13,7 @@ from playwright.async_api import Page, async_playwright
 from labnotes.daemon.socket_path import socket_path
 
 CONFIG = (
-    'name = "Alpha study"\ncommand = "go"\nrepeats = 2\nmode = "fill"\n'
+    'name = "Alpha study"\ncommand = "go"\nrepeats = 2\nmode = "matrix"\n'
     '[params]\nsource-language = ["en", "fr"]\n'
 )
 

labnotes-0.0.82/src/labnotes/modes.py

@@ -1,2 +0,0 @@
-MODES = ("fill", "adhoc")
-DEFAULT_MODE = "adhoc"