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 a public ObservableHQ notebook through its document API. The specifier may be a notebook URL, slug, id, or document API URL.

import observablejs as obs

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

Remote uploaded files become URL-backed attachments. Explicit files replace records with the same file name. The fetched document id and version pin its Observable notebook imports. timeout=None disables the per-request 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. ObservableHQ node names become public cell keys at this adapter boundary.

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 a valid source id and version when imported Observable notebooks must keep the source revision's dependency resolution.

The document must be a mapping with a node sequence. Unsupported node 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.