Skip to main content

Source constructors

Source constructors return a Notebook with the same view, variable, state, and close APIs as a Python-authored notebook. Imported cells and remote modules run with the host page's browser privileges. Read the trust boundary in Browser execution.

Notebook.from_html​

Notebook.from_html(
    source,
    *,
    files=None,
    base_path=None,
    embed_file_attachments=False,
    rewrite_imports=False,
    variables=None,
    show_pinned_source=False,
) -> Notebook

Creates a source-backed notebook from Notebook Kit HTML text. The notebook theme comes from the HTML. Each data-pyobservablejs-key becomes the public cell key.

from pathlib import Path

import observablejs as obs

path = Path("notebooks/report.html")
notebook = obs.Notebook.from_html(
    path.read_text(encoding="utf-8"),
    base_path=path.parent,
    embed_file_attachments=True,
    rewrite_imports=True,
)
  • source is a string containing Notebook Kit HTML.
  • files registers explicit attachment URLs, paths, or typed file records.
  • base_path resolves relative attachment and module paths.
  • embed_file_attachments embeds referenced local files as data URLs.
  • rewrite_imports embeds quoted relative JavaScript modules.
  • variables sets the initial Python-owned variable mapping.
  • show_pinned_source displays source for cells marked as pinned.

The constructor raises TypeError for an invalid source type or file mapping. It raises ValueError for malformed notebook metadata, duplicate cell ids or keys, unsupported themes, and invalid local import graphs. File reads may raise OSError or UnicodeError.

Notebook.from_observablehq​

Notebook.from_observablehq(
    specifier,
    *,
    variables=None,
    files=None,
    show_pinned_source=False,
    timeout=30,
) -> Notebook

Fetches the original source model from a public Observable notebook page. The specifier may be a notebook URL, slug, id, or document API URL. Append @version to request an exact revision.

import observablejs as obs

notebook = obs.Notebook.from_observablehq("@d3/bar-chart", timeout=10)
notebook.view()

Every imported cell has a public key. Classic node names become keys when provided. Other cells use cell-<id>, including anonymous cells and native cells defining several variables. Keys survive HTML export and reimport. Use notebook.cells.keys() to list them and notebook.view(key) to render a selection.

notebook.variables contains Python overrides and starts empty by default. Use notebook.data.names() to list notebook-defined variables and notebook.data[name].to_python() to evaluate and read one through the optional headless engine. notebook.data[name].cell returns the defining cell, which you can pass directly to notebook.view().

Remote uploaded files become URL-backed attachments. Explicit files replace records with the same file name. Notebook dependencies are fetched through Python when the browser requests them and evaluated in the same Observable Runtime. Each dependency retains its own library and attachment scope. timeout=None disables the constructor fetch timeout.

Invalid specifiers and document shapes raise ValueError. Network failures raise OSError. Response decoding may raise UnicodeError.

Notebook.from_observablehq_document​

Notebook.from_observablehq_document(
    document,
    *,
    title=None,
    variables=None,
    files=None,
    show_pinned_source=False,
) -> Notebook

Creates a notebook from an existing observablejs.types.ObservableDocument. ObservableClassicDocument uses nodes, where js means Observable JavaScript. ObservableNotebookModel uses cells, while ObservablePageDocument carries those cells in body. Native cells preserve js, ts, and ojs as distinct languages. stdlib selects the library independently: "1" uses classic Observable builtins and "2" uses Notebook Kit builtins. The defaults are "1" for classic documents and "2" for native models. Cell keys follow the same rules as from_observablehq().

import observablejs as obs

document: obs.types.ObservableDocument = {
    "id": "1234567890abcdef",
    "version": 7,
    "title": "Report",
    "nodes": [
        {"id": 1, "mode": "js", "name": "answer", "value": "answer = 42"},
    ],
}

notebook = obs.Notebook.from_observablehq_document(document)

title=None uses the document title and then "Untitled". Document files become URL-backed attachments, with explicit files taking precedence. Preserve id, version, and resolutions when saving classic documents. Explicit import revisions and declared notebook resolutions are retained through HTML export and reimport. Unpinned dependencies resolve when loaded.

A document must contain exactly one cell collection, nodes or cells. A supplied legacy API response marked unsupported_mode has already lost its cell languages. Fetch its original source with from_observablehq(). Unsupported cell modes, unsafe or duplicate ids, duplicate public keys, and malformed node records raise TypeError or ValueError.

See observablejs.types for the document, node, file, source, data, and display records.