jellycell.format.cells

Pydantic IR for notebook cells.

We keep nbformat’s :class:~nbformat.NotebookNode for I/O (mime bundles, outputs), but everything we reason about (cells, tags, deps, PEP-723 metadata) lives in the pydantic models defined here. See spec §2.2.

Module Contents

Classes

CellSpec	Parsed form of a cell’s jc.* tags (spec §2.2).
Cell	A single notebook cell — jellycell’s in-memory representation.
Notebook	A parsed jellycell notebook.

Data

CellKind

API

jellycell.format.cells.CellKind

None

class jellycell.format.cells.CellSpec(/, **data: Any)

Bases: pydantic.BaseModel

Parsed form of a cell’s jc.* tags (spec §2.2).

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config

‘ConfigDict(…)’

kind: jellycell.format.cells.CellKind

‘step’

The jc.<kind> category. Defaults to step for untagged code cells.

name: str | None

None

Cell’s human-readable name, from the name=... tag.

deps: list[str]

‘Field(…)’

Explicit dep names, from deps=a,b,c tag or jc.deps(...) calls.

timeout_s: int | None

None

Per-cell timeout override, from the timeout=N tag.

class jellycell.format.cells.Cell(/, **data: Any)

Bases: pydantic.BaseModel

A single notebook cell — jellycell’s in-memory representation.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config

‘ConfigDict(…)’

cell_type: Literal[code, markdown, raw]

None

nbformat cell type.

source: str

None

Cell source text (joined, no trailing split-by-line structure).

spec: jellycell.format.cells.CellSpec

‘Field(…)’

Parsed tags. Non-code cells always have default spec.

metadata: dict[str, Any]

‘Field(…)’

Raw nbformat metadata for round-tripping (includes tags list).

ordinal: int

0

Zero-based position in the source notebook. Used to build default names.

class jellycell.format.cells.Notebook(/, **data: Any)

Bases: pydantic.BaseModel

A parsed jellycell notebook.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config

‘ConfigDict(…)’

cells: list[jellycell.format.cells.Cell]

None

All cells, preserving source order.

metadata: dict[str, Any]

‘Field(…)’

Notebook-level metadata. metadata['jellycell']['pep723'] holds the verbatim PEP-723 block string when present (spec §2.2).

pep723_block: str | None

None

Raw PEP-723 block extracted during parse. Re-inserted verbatim on write.

leading_whitespace: str = <Multiline-String>

Whitespace between the PEP-723 block (or BOF) and the first cell marker.

Preserved verbatim so round-trip is byte-exact — jupytext would otherwise interpret leading blank lines as an implicit empty first code cell.