lunartrace.workbench.lab

Lab: generate editable marimo notebooks for a ROI and serve them with marimo edit.

The notebook is ordinary marimo Python: a header, a setup cell binding the exact ROI ring, taus and source manifest, then one cell per chosen preset. The researcher edits and re-runs it freely; nothing it computes is promoted to a Study or admitted.

`MARIMO_VERSION`

attribute

MARIMO_VERSION

marimo release written into the __generated_with field of generated notebooks.

`notebook_source`

function

def notebook_source(cells: Sequence[str]) -> str

Build a marimo app file from cell bodies, deriving references statically.

Parameters

Name	Type	Description
`cells`	`sequence of str`	Python source of each cell body, in notebook order.

Returns

str — The complete .py source of a marimo app with one @app.cell per body.

Raises

SyntaxError — If a cell body does not parse.

Notes

For each cell, the arguments are the names it loads that other cells define, and the return value is the cell’s own top-level definitions (names starting with _ are private to the cell). Built-in names are never arguments.

`source_index_for`

function

def source_index_for(site: wroi.Site, ring: Sequence[wroi.LonLat]) -> int | None

Find the source ROI that a ring corresponds to, by ring digest.

Parameters

Name	Type	Description
`site`	`lunartrace.workbench.roi.Site`	The Site whose served source rings are compared.
`ring`	`sequence of LonLat`	User ring vertices in lon/lat decimal degrees.

Returns

int or None — The index of the source ROI whose served ring has the same digest, or None.

`roi_label`

function

def roi_label(ring: Sequence[wroi.LonLat], source: int | None) -> tuple[str, str]

Return the ROI id and kind for a ring, as evaluate_ring labels it.

Parameters

Name	Type	Description
`ring`	`sequence of LonLat`	Ring vertices in lon/lat decimal degrees.
`source`	`int or None`	Source ROI index from `source_index_for`, or `None` for a user ring.

Returns

tuple of str — (id, kind): ("source:<i>", "source-ring") or ("user:<12 hex digits>", "user-drawn").

`roi_notebook`

function

def roi_notebook(
    ring: Sequence[wroi.LonLat],
    taus: Sequence[float],
    preset_ids: Sequence[str],
    manifest: Path,
    store: Path,
    *,
    source: int | None = None,
) -> str

Generate the Lab notebook source for one ROI and a set of presets.

Parameters

Name	Type	Description
`ring`	`sequence of LonLat`	Ring vertices in lon/lat decimal degrees; bound verbatim in the setup cell.
`taus`	`sequence of float`	Slope-RMS cutoffs in degrees; bound verbatim in the setup cell.
`preset_ids`	`sequence of str`	Ids of the presets to include, in order.
`manifest`	`pathlib.Path`	Site source manifest bound in the setup cell.
`store`	`pathlib.Path`	Source store root bound in the setup cell.
`source`	`int`	Python-derived source index from `source_index_for`, keyword-only. Default `None`.

Returns

str — The marimo app source: a header cell, the setup cell and one cell per preset.

Raises

KeyError — If a preset id is unknown.
SyntaxError — If a generated cell body does not parse.

Notes

The header states that results are METHOD_EXECUTED and NOT_ADMITTED. Valid-cell fraction is not lunar area, and tau is a slope-RMS data-quality cutoff.

`LabUnavailable`

class

LabUnavailable

The Lab marimo edit process could not be started (port busy, exit or timeout).

`LabServer`

class

LabServer

One marimo edit process over the lab directory, with a per-process token.

Attributes

Name	Type	Description
`directory`	`pathlib.Path`	Directory of generated notebooks that the marimo process edits.
`port`	`int, default 4319`	Loopback TCP port the marimo process listens on.
`token`	`str`	Access token for the marimo session, generated per instance from `secrets`.
`process`	`subprocess.Popen of bytes or None`	The running marimo process, or `None` before the first `ensure`.

`LabServer.ensure`

def ensure(self) -> None

Start the marimo edit process if it is not already running.

Raises

LabUnavailable — If the port is already in use, if marimo exits during start, or if it does not open the port within 30 seconds.

Notes

The process is started as python -m marimo edit bound to 127.0.0.1 with the instance token and without update checks. The token is passed on stdin (--token-password-file -), not on the command line, so other local processes cannot read it from the process table. Its output is discarded.

`LabServer.url`

def url(self, name: str) -> str

Return the browser URL that opens one notebook in the running Lab.

Parameters

Name	Type	Description
`name`	`str`	File name of a notebook inside `directory`.

Returns

str — http://127.0.0.1:<port>/?file=<name>&access_token=<token>. The URL carries the access token, so it is for the local user only.

`LabServer.stop`

def stop(self) -> None

Terminate the marimo process if it is running.

Notes

Sends a terminate signal and returns without waiting for the process to exit.