moonrockz/notebooks/nbformat

type Attachments derive(Eq, @moonbitlang/core/debug.Debug)

An immutable mapping from attachment filenames to validated MIME bundles. Traversal and names use lexical filename order, independent of input key order.

fn Attachments::Attachments(value : Json) -> Attachments raise FormatError

Validate a filename-keyed object of MIME bundles, copying all JSON inputs. Raise InvalidField for a non-object or invalid bundle payload.

fn Attachments::equal(Attachments, Attachments) -> Bool

fn Attachments::get(self : Attachments, name : String) -> MimeBundle?

Find an immutable MIME bundle by its exact filename, or return None.

fn Attachments::names(self : Attachments) -> ReadOnlyArray[String]

Return attachment filenames in lexical order.

fn Attachments::not_equal(x : Attachments, y : Attachments) -> Bool

fn Attachments::to_json(self : Attachments) -> Json

Export an independent filename-keyed JSON object of MIME bundles.

fn Attachments::to_repr(Attachments) -> @moonbitlang/core/debug.Repr

type Cell derive(Eq, @moonbitlang/core/debug.Debug)

An immutable validated Jupyter cell. IDs may be absent in pre-4.5 files; the containing notebook enforces version-specific ID presence and uniqueness.

fn Cell::Cell(content : CellContent, id? : CellId?, metadata? : @moonrockz/notebooks.Metadata) -> Cell raise FormatError

Validate a typed payload and cell metadata. Defaults to no ID and empty metadata; Notebook construction requires IDs for v4.5 and later. Unknown fields must not repeat cell_type, id or metadata. Raises InvalidField for invalid metadata or a conflicting Unknown payload.

fn Cell::cell_type(self : Cell) -> String

Return the wire-format cell type, retaining unknown type names unchanged.

fn Cell::content(self : Cell) -> CellContent

Return the typed cell payload for exhaustive pattern matching.

fn Cell::equal(Cell, Cell) -> Bool

fn Cell::extensions(self : Cell) -> JsonObject

Return extra fields preserved when reading a recognized cell. Additional fields of an unknown cell are stored in its Unknown payload instead.

fn Cell::has_mime_type(self : Cell, mime_type : String) -> Bool

Whether a rich output or attachment contains this exact MIME key. Source text and metadata are not searched. Empty payloads and JSON null count as present; matching follows MimeBundle::get.

fn Cell::id(self : Cell) -> CellId?

Return the validated ID, or None when reading or constructing an older cell.

fn Cell::kind(self : Cell) -> @moonrockz/notebooks.CellKind

Classify this cell without discarding its format-specific payload.

fn Cell::metadata(self : Cell) -> @moonrockz/notebooks.Metadata

Return the immutable cell metadata object.

fn Cell::mime_capability(self : Cell) -> &@moonrockz/notebooks.MimeTyped?

fn Cell::not_equal(x : Cell, y : Cell) -> Bool

fn Cell::outputs(self : Cell) -> ReadOnlyArray[Output]

Return code outputs in stored order. Return an empty immutable array for Markdown, raw and unknown cells.

fn Cell::source(self : Cell) -> String?

Return normalized source for code, Markdown and raw cells. Return None for unknown cells, whose uninterpreted source may remain in their fields.

fn Cell::to_json(self : Cell) -> Json raise FormatError

Export an independent cell object, including its discriminator, optional ID, metadata, typed content and preserved fields. Text is normalized.

fn Cell::to_repr(Cell) -> @moonbitlang/core/debug.Repr

fn kind(self : Cell) -> @moonrockz/notebooks.CellKind

fn metadata(self : Cell) -> @moonrockz/notebooks.Metadata?

fn mime_capability(self : Cell) -> &@moonrockz/notebooks.MimeTyped?

Every Jupyter cell supports MIME lookup. Cells without rich output or attachments still return Some, and their lookup predicate returns false.

fn source(self : Cell) -> String?

fn has_mime_type(self : Cell, mime_type : String) -> Bool

pub(all) enum CellContent {
  Markdown(source~ : String, attachments~ : Attachments?)
  Raw(source~ : String, attachments~ : Attachments?)
  Code(source~ : String, execution_count~ : ExecutionCount?, outputs~ : ReadOnlyArray[Output])
  Unknown(cell_type~ : String, fields~ : JsonObject)
} derive(Eq, @moonbitlang/core/debug.Debug)

The source and format-specific payload of a cell. Only code cells carry outputs and execution counts; only Markdown and raw cells carry attachments. Unknown preserves the original cell type and its additional JSON fields.

fn CellContent::equal(CellContent, CellContent) -> Bool

fn CellContent::not_equal(x : CellContent, y : CellContent) -> Bool

fn CellContent::to_repr(CellContent) -> @moonbitlang/core/debug.Repr

type CellId derive(Eq, @moonbitlang/core/debug.Debug)

An immutable Jupyter cell identifier containing 1 to 64 ASCII letters, digits, hyphens or underscores. Notebook construction checks uniqueness.

fn CellId::CellId(value : String) -> CellId raise FormatError

Validate a cell identifier. Raise InvalidField for an empty, oversized or otherwise invalid ID. This constructor does not generate an ID.

test "doc: construct a stable cell ID" {
  let id = @nbformat.CellId("results-01")
  @expect.expect(id.to_string()).to_equal("results-01")
}

fn CellId::equal(CellId, CellId) -> Bool

fn CellId::not_equal(x : CellId, y : CellId) -> Bool

fn CellId::to_repr(CellId) -> @moonbitlang/core/debug.Repr

fn CellId::to_string(self : CellId) -> String

Return the validated identifier unchanged.

type ExecutionCount derive(Eq, @moonbitlang/core/debug.Debug)

A nonnegative integral JSON number. Preserve its available JSON representation instead of converting large counts to a machine integer. Use None, rather than an ExecutionCount value, for an unexecuted cell.

fn ExecutionCount::ExecutionCount(value : Int) -> ExecutionCount raise FormatError

Construct a count from a nonnegative 32-bit integer. Raise InvalidField for a negative value. Use from_json for larger JSON numbers.

fn ExecutionCount::equal(ExecutionCount, ExecutionCount) -> Bool

fn ExecutionCount::from_json(value : Json) -> ExecutionCount raise FormatError

Validate a finite, nonnegative integral JSON number and retain its representation. Raise InvalidField for null, negative or fractional values, non-numbers and non-finite values. Null counts are represented by None.

fn ExecutionCount::not_equal(x : ExecutionCount, y : ExecutionCount) -> Bool

fn ExecutionCount::to_json(self : ExecutionCount) -> Json

Export the numeric JSON value without converting it to an integer string.

fn ExecutionCount::to_repr(ExecutionCount) -> @moonbitlang/core/debug.Repr

type JsonObject derive(Eq, @moonbitlang/core/debug.Debug)

An immutable JSON object. Construction and JSON exports copy the entire value graph, including nested arrays and objects. Accessors never expose mutable aliases to the stored object.

fn JsonObject::JsonObject(value : Json) -> JsonObject raise FormatError

Require an object and make a defensive deep copy. Raise InvalidField for any non-object value. Notebook and cell constructors separately validate the meaning of known metadata fields.

fn JsonObject::equal(JsonObject, JsonObject) -> Bool

fn JsonObject::get(self : JsonObject, key : String) -> Json?

Look up a field, returning a defensive deep copy of its JSON value. Return None when the field is absent.

fn JsonObject::keys(self : JsonObject) -> ReadOnlyArray[String]

Return immutable field names. Their order is not a sorting guarantee.

fn JsonObject::not_equal(x : JsonObject, y : JsonObject) -> Bool

fn JsonObject::to_json(self : JsonObject) -> Json

Export a defensive deep copy that callers may mutate independently.

fn JsonObject::to_repr(JsonObject) -> @moonbitlang/core/debug.Repr

type MimeBundle derive(Eq, @moonbitlang/core/debug.Debug)

An immutable mapping of MIME types to data. Textual data is normalized to strings; application/json and +json values retain their JSON structure.

fn MimeBundle::MimeBundle(value : Json) -> MimeBundle raise FormatError

Require a MIME-keyed object. Join string arrays without separators for textual MIME values, while retaining JSON MIME payloads as-is. Raise InvalidField for a non-object or invalid textual payload. Copy all inputs.

fn MimeBundle::equal(MimeBundle, MimeBundle) -> Bool

fn MimeBundle::get(self : MimeBundle, mime_type : String) -> Json?

Look up a MIME representation and return an independent JSON value. Textual representations are strings; JSON MIME values retain their type.

fn MimeBundle::mime_types(self : MimeBundle) -> ReadOnlyArray[String]

Return the immutable MIME type keys, without a sorting guarantee.

fn MimeBundle::not_equal(x : MimeBundle, y : MimeBundle) -> Bool

fn MimeBundle::to_json(self : MimeBundle) -> Json

Export an independent MIME-keyed object with normalized textual values.

fn MimeBundle::to_repr(MimeBundle) -> @moonbitlang/core/debug.Repr

pub(all) enum Node {
  Notebook(Notebook)
  Cell(Cell)
  Output(Output)
  Attachment(name~ : String, data~ : MimeBundle)
} derive(Eq, @moonbitlang/core/debug.Debug)

A concrete Jupyter traversal node. Notebooks contain cells; code cells contain outputs; Markdown and raw cells contain attachments. Output and attachment nodes are leaves. Metadata and MIME JSON use their own accessors.

fn Node::at(self : Node, path : @moonrockz/notebooks.NodePath) -> Node?

Resolve a shared child-index path relative to this node. Return None for any invalid index. The path does not refer to JSON object fields.

fn Node::children(self : Node) -> ReadOnlyArray[Node]

Return immutable children. Cells and outputs retain stored order; attachments use lexical filename order. Metadata is not a traversal child.

fn Node::cursor(self : Node) -> @moonrockz/notebooks.Cursor[Node]

Start a new navigation root at this node. Use an existing cursor to retain its original ancestors and paths.

fn Node::equal(Node, Node) -> Bool

fn Node::kind(self : Node) -> @moonrockz/notebooks.NodeKind

Classify this node for format-independent traversal without converting or discarding the concrete Jupyter payload.

fn Node::metadata(self : Node) -> @moonrockz/notebooks.Metadata?

Return this node's own metadata. Some(empty) retains an empty container; None means this node has none. Ancestor metadata is never inherited.

fn Node::not_equal(x : Node, y : Node) -> Bool

fn Node::source(self : Node) -> String?

Return a recognized cell's normalized source. Notebook, output, attachment and unknown-cell nodes return None.

fn Node::to_repr(Node) -> @moonbitlang/core/debug.Repr

fn children(self : Node) -> ReadOnlyArray[Node]

fn kind(self : Node) -> @moonrockz/notebooks.NodeKind

fn metadata(self : Node) -> @moonrockz/notebooks.Metadata?

fn source(self : Node) -> String?

type Notebook derive(Eq, @moonbitlang/core/debug.Debug)

An immutable Jupyter v4 document with metadata, ordered cells and preserved extension fields. The file's minor version is retained.

fn Notebook::Notebook(cells : ReadOnlyArray[Cell], minor? : Int, metadata? : @moonrockz/notebooks.Metadata) -> Notebook raise FormatError

Construct a v4 notebook, defaulting to file format 4.5 and empty metadata. Raise UnsupportedVersion for a negative minor version, InvalidField for invalid metadata or a missing required ID, and DuplicateCellId or DuplicateCellName for repeated identities. v4.5 and later require IDs.

fn Notebook::cell(self : Notebook, index : Int) -> Cell?

Look up a cell by zero-based document index. Return None for negative indices or an index at or beyond the cell count.

fn Notebook::cell_by_id(self : Notebook, id : CellId) -> Cell?

Find a cell by its validated ID. Return None if no cell has that ID.

fn Notebook::cells(self : Notebook) -> ReadOnlyArray[Cell]

Return immutable cells in document order.

fn Notebook::cells_by_mime_type(self : Notebook, mime_type : String) -> ReadOnlyArray[Cell]

Select cells containing an exact MIME key in a rich output or attachment. Return each matching cell once, in document order, in an immutable array. Empty or JSON null payloads count as present. Matching is case-sensitive, without wildcard or parameter normalization, just like MimeBundle::get. Source text, metadata, streams, errors and unknown payloads are not searched. Return an empty array when there are no matches.

fn Notebook::cursor(self : Notebook) -> @moonrockz/notebooks.Cursor[Node]

Start a typed Jupyter cursor at this notebook, with depth zero and path $.

fn Notebook::equal(Notebook, Notebook) -> Bool

fn Notebook::extensions(self : Notebook) -> JsonObject

Return notebook-level fields outside metadata, cells and version fields.

fn[A] Notebook::fold(self : Notebook, init : A, f : (A, @moonrockz/notebooks.Cursor[Node]) -> A) -> A

Thread an accumulator through this notebook tree in pre-order. Callbacks receive typed Jupyter cursors. Use walk for pruning or early termination.

fn Notebook::from_json(value : Json) -> Notebook raise FormatError

Validate an existing JSON notebook and copy all mutable value graphs. Accept v4 minor versions, requiring cell IDs from 4.5 onward. Raise FormatError on invalid fields, unsupported major versions or duplicate IDs/names. Later mutation of value cannot change the notebook.

fn Notebook::metadata(self : Notebook) -> @moonrockz/notebooks.Metadata

Return immutable notebook metadata, including custom namespaces.

fn Notebook::nbformat(_self : Notebook) -> Int

Return the notebook file format's major version, always 4. This is independent of the upstream Python library's release number.

fn Notebook::nbformat_minor(self : Notebook) -> Int

Return the retained notebook file format minor version.

fn Notebook::not_equal(x : Notebook, y : Notebook) -> Bool

fn Notebook::root(self : Notebook) -> Node

Wrap this notebook as the concrete root accepted by shared traversal.

fn Notebook::to_json(self : Notebook) -> Json raise FormatError

Export an independent notebook JSON object, retaining version numbers, metadata and extension payloads. Multiline values use normalized strings. Mutating the exported object does not alter this notebook.

fn Notebook::to_repr(Notebook) -> @moonbitlang/core/debug.Repr

fn Notebook::to_string(self : Notebook) -> String raise FormatError

Serialize notebook JSON with normalized multiline strings. Preserve metadata and extensions, but not original whitespace, key order or line splitting. The result can be passed to parse.

type Output derive(Eq, @moonbitlang/core/debug.Debug)

An immutable validated output, including preserved extension fields. Construct with Output(content), or obtain outputs from a parsed code cell.

fn Output::Output(content : OutputContent) -> Output raise FormatError

Validate a typed output payload using the JSON codec's boundary rules. Unknown must use an unrecognized output_type and must not repeat that key inside fields. Raise InvalidField for invalid payload or metadata.

fn Output::content(self : Output) -> OutputContent

Return the typed output payload for exhaustive pattern matching.

fn Output::equal(Output, Output) -> Bool

fn Output::extensions(self : Output) -> JsonObject

Return extra JSON fields preserved when reading a recognized output. For an unknown output, additional fields live in its Unknown payload.

fn Output::not_equal(x : Output, y : Output) -> Bool

fn Output::output_type(self : Output) -> String

Return the wire-format discriminator, such as stream or display_data. An unknown output retains its original discriminator.

fn Output::to_json(self : Output) -> Json raise FormatError

Export an independent output object with its discriminator, typed payload and preserved fields. Text is normalized; JSON MIME data is retained.

fn Output::to_repr(Output) -> @moonbitlang/core/debug.Repr

pub(all) enum OutputContent {
  Stream(name~ : String, text~ : String)
  DisplayData(data~ : MimeBundle, metadata~ : @moonrockz/notebooks.Metadata)
  ExecuteResult(data~ : MimeBundle, metadata~ : @moonrockz/notebooks.Metadata, execution_count~ : ExecutionCount?)
  Error(ename~ : String, evalue~ : String, traceback~ : ReadOnlyArray[String])
  Unknown(output_type~ : String, fields~ : JsonObject)
} derive(Eq, @moonbitlang/core/debug.Debug)

The typed payload of a Jupyter output. Rich display and execution results carry MIME bundles and metadata; None denotes a null execution count. Unknown preserves an unrecognized output type and its additional fields.

fn OutputContent::equal(OutputContent, OutputContent) -> Bool

fn OutputContent::not_equal(x : OutputContent, y : OutputContent) -> Bool

fn OutputContent::to_repr(OutputContent) -> @moonbitlang/core/debug.Repr

pub(all) suberror FormatError {
  InvalidJson(String)
  InvalidField(path~ : String, expected~ : String)
  UnsupportedVersion(major~ : Int, minor~ : Int)
  DuplicateCellId(String)
  DuplicateCellName(String)
} derive(Eq, @moonbitlang/core/debug.Debug)

A JSON decoding or notebook validation failure. InvalidField reports a logical JSON field path and the expected value. UnsupportedVersion carries file format numbers, not the upstream Python library release version.

fn FormatError::equal(FormatError, FormatError) -> Bool

fn FormatError::not_equal(x : FormatError, y : FormatError) -> Bool

fn FormatError::to_repr(FormatError) -> @moonbitlang/core/debug.Repr

using @moonrockz/notebooks { type Control }

Shared navigation types. Explicit cursor annotations use Cursor[Node].

using @moonrockz/notebooks { type Cursor }

Shared navigation types. Explicit cursor annotations use Cursor[Node].

using @moonrockz/notebooks { type Metadata }

Shared navigation types. Explicit cursor annotations use Cursor[Node].

using @moonrockz/notebooks { type NodePath }

Shared navigation types. Explicit cursor annotations use Cursor[Node].

fn parse(source : String) -> Notebook raise FormatError

Read notebook JSON into an immutable v4 document. Normalize multiline strings and preserve unknown fields, cell types and output types. Raise InvalidJson for malformed JSON, UnsupportedVersion for another major version, or a typed FormatError for invalid structure or identities.

fn walk(root : Node, enter : (Node) -> @moonrockz/notebooks.Control, leave? : (Node) -> Unit) -> Unit

Walk Jupyter nodes in depth-first pre-order with the shared engine. Use walk_cursor when callbacks need path, parent or sibling context.

fn walk_cursor(root : Node, enter : (@moonrockz/notebooks.Cursor[Node]) -> @moonrockz/notebooks.Control, leave? : (@moonrockz/notebooks.Cursor[Node]) -> Unit) -> Unit

Use the shared engine to walk Jupyter positions from a new root. Callbacks retain typed Node payloads. SkipChildren still receives leave; Stop returns immediately without pending leave callbacks.