Notebook

Notebook is a traitlets controller for one notebook definition and the values set from Python. It creates renderable 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)

Returns a new NotebookView. With no selectors, it renders every cell.

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.cell("answer"))

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.

Notebook.cell(key)

Returns the stable NotebookCell for one unique string key.

answer = notebook.cell("answer")

Unknown keys raise KeyError. Non-string selectors raise TypeError. The Notebook Kit id and notebook-order index are metadata and are not selectors.

Notebook.cells

Returns all NotebookCell handles in notebook order. Anonymous cells remain available in this tuple.

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, Notebook.attachments, 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.