provevi.runs

Where runs live, and how to find one.

A run keeps its files in one folder under a runs root::

<runs root>/<run_id>/evidence/   the evidence
<runs root>/<run_id>/output/     what the agent wrote
<runs root>/<run_id>/bundle.json where the bundle was committed, if anywhere

The runs root is PROVRUN_RUNS, or else $XDG_DATA_HOME/provrun/runs, or else ~/.local/share/provrun/runs.

default_runs_root

source

default_runs_root() -> Path

The folder that holds the runs, from the environment; it need not exist.

Parameter	Type	Default	Description
returns	Path		PROVRUN_RUNS, or `$XDG_DATA_HOME/provrun/runs`, or `~/.local/share/provrun/runs`

find_run

source

find_run(run: str | Path, root: str | Path | None = None, *, ids_only: bool = False) -> Path

Find the folder of a run.

A run ID that names a link under root is refused. Raises RunNotFound.

Parameter	Type	Default	Description
`run`	str \| Path	required	A run ID under root, or else a path to a run folder
`root`	str \| Path \| None	`None`	The runs root; `None` for the default runs root
`ids_only`	bool	`False`	Accept a run ID only, so a name from a user cannot reach another folder
returns	Path		The run’s folder, as an absolute path

list_runs

source

list_runs(root: str | Path | None = None) -> list[str]

List the run IDs under a runs root, oldest first.

A run ID starts with its UTC time. Links are left out, as find_run refuses them.

Parameter	Type	Default	Description
`root`	str \| Path \| None	`None`	The runs root; `None` for the default runs root
returns	list[str]		The run IDs; empty when root is no folder