Notebook

Notebook is a traitlets controller for one notebook definition and the values set from Python. It creates renderable views backed by NotebookView objects.

Constructor

Notebook(
    *cells,
    title="Untitled",
    theme="air",
    files=None,
    base_path=None,
    variables=None,
    show_pinned_source=False,
)

import observablejs as obs

notebook = obs.Notebook(
    obs.md("# Summary", key="title"),
    obs.ojs("answer = 40 + 2", key="answer"),
    variables={"precision": 2},
)

Argument	Contract
*cells	Cell objects from the public helpers or direct Cell construction.
title	Notebook Kit document title.
theme	Theme name or typed light and dark theme pair.
files	Mapping of attachment names to URLs, paths, or typed file records.
base_path	Base directory for relative paths in files.
variables	Initial mapping of Python-owned Observable variables.
show_pinned_source	Shows source for selected cells marked as pinned.

Invalid cell types, mappings, or serializable values raise TypeError. Duplicate cell ids or keys, invalid variable names, and unsupported themes raise ValueError. Local attachment access may raise OSError.

Notebook.view(*selectors, **options)

Returns a new renderable view. With no selectors, it renders every cell. In a running marimo notebook, the return value is a marimo UI element that proxies its NotebookView.

import observablejs as obs

answer = obs.ojs("answer = 40 + 2", key="answer")
double = obs.ojs("double = answer * 2", key="double")
notebook = obs.Notebook(answer, double)

full_view = notebook.view()
answer_view = notebook.view("answer")
mixed_view = notebook.view(double, notebook.cells["answer"])
preview = notebook.view(capture_state=False)

Each positional selector is one of:

• a string public cell key
• an authored Cell with a key
• a NotebookCell owned by this notebook

Each selector resolves to one cell, then cells render in notebook order. Unknown keys raise KeyError. Authored Cell selectors need a key, and NotebookCell selectors must belong to the notebook. Duplicate selections and foreign handles raise ValueError. Invalid selector types raise TypeError.

Every view has its own browser run and state snapshot. Views from the same notebook receive the same Python variables and supported browser input values.

options is typed as NotebookViewOptions. capture_state controls whether browser evaluation updates NotebookView.state and defaults to True. Set it to False when the rendered output is all you need and Python will not read its state. The view remains interactive and state stays at its initial value.

Unknown options and non-boolean capture_state values raise TypeError. See Skip Python state capture for performance guidance.

Notebook.cells

An ordered collection of canonical cell handles. String indexing selects public keys and integer indexing selects notebook positions. Iteration follows notebook order, including anonymous cells.

answer = notebook.cells["answer"]
first = notebook.cells[0]
keys = notebook.cells.keys()

Unknown or ambiguous keys raise KeyError. Notebook Kit id is serialization metadata. Pass a cell handle or key to view() when selecting cells.

Data and files

notebook.files[name] exposes attachment metadata and synchronous file loading. notebook.data[name] reads computed values through the optional headless engine. notebook.graph provides static dependencies and imports. See the data namespace reference.

notebook.with_variables(**variables) returns an independent notebook with merged Python bindings. It preserves source, attachments, theme, and original source records. Use a context manager or close() for its execution lifetime.

Controller state

Notebook.state is a separate, deeply read-only NotebookState snapshot. It contains variables, attachments, and theme.

def on_state(change):
    print(change["new"].variables)

notebook.observe(on_state, names="state")

Notebook.variables and Notebook.theme read from the latest snapshot. Changing an object passed during construction does not change the notebook. Snapshot values cannot be edited. Use the variable methods or assign notebook.theme for changes. Each real change publishes one state event. Sending the same serialized value publishes none.

An unchanged variable update can still clear a browser-owned input with the same name and reapply the Python value. The controller snapshot stays the same.

Source-backed notebooks read their theme from source HTML. Assigning a theme to one raises traitlets.TraitError.

Variable mutation

Notebook.update_variables(values, /)

Merges exactly one Mapping[str, object] into the Python-owned environment.

notebook.update_variables({"threshold": 0.8})

Notebook.replace_variables(values, /)

Replaces the environment with exactly one mapping. Omitted names return to their notebook-defined values.

notebook.replace_variables({"rows": [{"x": 1}, {"x": 2}]})

Notebook.reset_variables(*names)

Releases the listed Python-owned names. Unknown names and an empty call are no-ops.

All three methods return None. Invalid or reserved variable names raise ValueError. Non-mapping update and replacement arguments or unsupported values raise TypeError.

Notebook.to_notebook_html()

Returns the definition as Notebook Kit HTML. Public cell keys use the data-pyobservablejs-key script attribute. Controller variables remain session state.

Notebook.close()

Closes the shared session and every live view. Repeated calls are no-ops. Creating a view or mutating a closed notebook raises RuntimeError.

See Source constructors for from_html, from_observablehq, and from_observablehq_document.