View state and graph

NotebookView.state is one consistent, read-only snapshot of browser work.

state = view.state

if (
    not state.pending
    and state.input_revision is not None
    and state.settled_revision == state.input_revision
):
    result = state.result("chart")

ViewState

Field	Type	Contract
input_revision	optional int	Latest browser update number.
settled_revision	optional int	Latest update where every selected cell finished.
pending	bool	Whether the latest update is still running.
results	tuple[CellResult, ...]	Selected-cell results in notebook order.
errors	tuple[ViewError, ...]	Setup or view-level failures.
graph	optional NotebookGraph	Current read-only dependency graph snapshot.

Before display, both revisions are None. The first browser run uses revision 0. Python updates, browser inputs, and later generator values advance input_revision. While work runs, settled_revision stays at the previous finished revision. Results from older revisions are ignored.

ViewState.result(selector)

Returns the result for a key string, keyed authored Cell, or NotebookCell from the same notebook. Missing results raise KeyError, including requests made before the browser starts. Invalid selector types raise TypeError. Once the state contains results, a handle from another notebook raises ValueError.

CellResult

Field	Type	Contract
cell	NotebookCell	Stable selected-cell handle.
revision	int	Input revision represented by this result.
status	CellStatus	"pending", "success", or "error".
values	Mapping[str, object]	Separate, read-only output values.
errors	tuple[CellError, ...]	Structured failures for this cell.

success means every expected output finished. An error result may still contain values from outputs that succeeded. Read results after the current revision finishes.

Structured errors

CellError contains name, message, phase, and an optional output variable. ViewError contains name, message, and phase. The phase is analysis, evaluation, rendering, or serialization. Browser stack text is not part of the contract.

A JavaScript expression that returns new Error("invalid value") has succeeded. Its value becomes BrowserErrorValue(name, message). A rejected evaluation produces CellError and an error result.

NotebookGraph

Member	Contract
cells	Immutable CellInfo records.
edges	Immutable DependencyEdge records.
defines	Unique defined names in cell order.
references	Unique referenced names in cell order.
external_references	Referenced names absent from evaluated cell outputs.

NotebookGraph.cell(key)

Returns the unique keyed CellInfo. Anonymous cells remain available through graph.cells. Unknown or ambiguous keys raise KeyError.

NotebookGraph.cell_for_variable(variable)

Returns the unique cell that defines a variable. Missing or ambiguous definitions raise KeyError.

Diagram export

graph.to_mermaid() returns a Mermaid flowchart LR string. graph.to_d2() returns a D2 diagram with rightward layout. Diagram labels use the public key and fall back to notebook position for anonymous cells.

CellInfo

CellInfo exposes id, index, mode, key, defines, references, output, outputs, runtime_outputs, autodisplay, autoview, automutable, and optional error fields. The id and index are metadata.

DependencyEdge

Each edge contains source and target CellInfo objects plus the linking variable name.

See Inspect the dependency graph for a live workflow.