Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

Make the document a value and the notebook its owner (#11293)

Trevor Manzcc4d597a5568
diff --git a/marimo/_core/analysis.py b/marimo/_core/analysis.py
index 0a6d2b05bc..cd3da838b0 100644
--- a/marimo/_core/analysis.py
+++ b/marimo/_core/analysis.py
@@ -10,7 +10,7 @@ from marimo._core import protocol
if TYPE_CHECKING:
from collections.abc import Mapping
- from marimo._core.document import DocumentSnapshot
+ from marimo._core.document import Document
class Analyzer(Protocol):
@@ -18,7 +18,7 @@ class Analyzer(Protocol):
One instance belongs to one notebook. Calls are serialized, allowing
implementations to cache compilation by cell ID and code hash.
- Results cover every cell in the snapshot, including syntax errors.
+ Results cover every cell in the document, including syntax errors.
Unexpected failures raise; they are not document diagnostics.
Implementations must keep the event loop responsive. After cancelling
@@ -26,6 +26,6 @@ class Analyzer(Protocol):
"""
async def analyze(
- self, snapshot: DocumentSnapshot
+ self, document: Document
) -> Mapping[protocol.CellId, protocol.CellAnalysis]:
- """Analyze a detached snapshot without modifying it."""
+ """Analyze one revision of the document."""
diff --git a/marimo/_core/backend.py b/marimo/_core/backend.py
index 1b90e43c2a..7b1c28b7cd 100644
--- a/marimo/_core/backend.py
+++ b/marimo/_core/backend.py
@@ -2,7 +2,7 @@
"""Kernel commands and updates for the host API.
```python
-notebook = Notebook(document, Executions(), backend, sink)
+notebook = Notebook(notebook_id, document, Executions(), backend, sink)
runtime, _ = notebook.start() # Calls backend.start(runtime.id).
# The backend reports on that runtime through Notebook.observe.
diff --git a/marimo/_core/document.py b/marimo/_core/document.py
index ffe97693ed..7602c5319a 100644
--- a/marimo/_core/document.py
+++ b/marimo/_core/document.py
@@ -1,5 +1,10 @@
# Copyright 2026 Marimo. All rights reserved.
-"""Notebook cells, order, configuration, and revisions."""
+"""Notebook cells, order, configuration, and revisions.
+
+A document is the notebook's content at one revision. It does not
+change. Editing it returns the next document. The notebook holds the
+current one.
+"""
from __future__ import annotations
@@ -12,10 +17,10 @@ from typing import TYPE_CHECKING, Any
from msgspec import UNSET
from marimo._core import protocol
-from marimo._core.errors import EditConflict, Invalid
+from marimo._core.errors import Invalid
if TYPE_CHECKING:
- from collections.abc import Iterator, Mapping, Sequence
+ from collections.abc import Iterable, Iterator, Mapping, Sequence
def etag(text: str) -> protocol.Etag:
@@ -76,54 +81,45 @@ def default_config() -> protocol.CellConfig:
@dataclass(frozen=True)
-class CellSource:
- """Cell source and metadata supplied by a file or editor."""
+class DocumentCell:
+ """A cell and the hashes of its content.
+
+ Line endings are normalized to newlines and the hashes computed when
+ the cell is built, so they always match the content.
+ """
- id: str
+ id: protocol.CellId
code: str
name: str = "_"
config: protocol.CellConfig = field(default_factory=default_config)
+ etag: protocol.Etag = field(init=False)
+ """Identifies code, name, and config together."""
+ code_hash: protocol.Etag = field(init=False)
+ """Identifies the code alone."""
-
-def revision(
- cells: Sequence[CellSource], app_config: Mapping[str, Any]
-) -> protocol.Etag:
- """The document etag these sources produce."""
- return document_etag(
- order_etag([source.id for source in cells]),
- app_config_etag(app_config),
- [
- cell_etag(
- code_hash(normalize_code(source.code)),
- source.name,
- source.config,
- )
- for source in cells
- ],
- )
-
-
-@dataclass(frozen=True)
-class DocumentSnapshot:
- """A detached document record and its cells in document order."""
-
- document: protocol.Document
- cells: tuple[protocol.Cell, ...]
+ def __post_init__(self) -> None:
+ code = normalize_code(self.code)
+ hashed = code_hash(code)
+ object.__setattr__(self, "code", code)
+ object.__setattr__(self, "code_hash", hashed)
+ object.__setattr__(
+ self, "etag", cell_etag(hashed, self.name, self.config)
+ )
@dataclass(frozen=True)
class Changed:
- """Changed cells, removed cell IDs, and the updated document."""
+ """Changed cells, removed cell IDs, and the new revision."""
- cells: list[protocol.Cell]
+ cells: list[DocumentCell]
"""New cells, and cells whose etag changed."""
- removed: list[str]
+ removed: list[protocol.CellId]
"""Ids of cells that no longer exist."""
- document: protocol.Document | None
- """The document, when any of its fields changed."""
+ etag: protocol.Etag | None
+ """The document's etag, when it changed."""
def __bool__(self) -> bool:
- return bool(self.cells or self.removed or self.document)
+ return bool(self.cells or self.removed or self.etag)
@dataclass(frozen=True)
@@ -131,47 +127,63 @@ class Applied:
"""An edit's effects and the etags of the cells it touched."""
changed: Changed
- cells: dict[str, protocol.CellEtags | None]
+ cells: dict[protocol.CellId, protocol.CellEtags | None]
"""By id, for each cell the edit put, and `None` for each it deleted."""
+@dataclass(frozen=True)
+class Stale:
+ """An edit named a state the document no longer has. Nothing applied."""
+
+ change: int
+ """The index of the first stale change."""
+ cell_id: protocol.CellId | None
+ """The cell that change named, if it named one."""
+
+
class Document:
- """A notebook document with content-derived revisions.
+ """The notebook's content at one revision.
- Cell source uses newline line endings. Edits change cells and their
- order. The app config comes from the store or the editor.
+ Documents with the same etag are equal. Cell IDs must be unique.
"""
+ __slots__ = (
+ "_app_config",
+ "_app_config_etag",
+ "_cells",
+ "_etag",
+ "_order_etag",
+ )
+
def __init__(
- self,
- notebook_id: protocol.NotebookId,
- cells: Sequence[CellSource],
- app_config: Mapping[str, Any],
- *,
- saved: bool = True,
+ self, cells: Iterable[DocumentCell], app_config: Mapping[str, Any]
) -> None:
- self._id = notebook_id
- self._cells: dict[str, protocol.Cell] = {}
- self._order: list[str] = []
- self._app_config: dict[str, Any] = {}
- self._saved_etag: protocol.Etag | None = None
- self._document: protocol.Document | None = None
- self.replace(cells, app_config)
- if saved:
- self.mark_saved()
+ held: dict[protocol.CellId, DocumentCell] = {}
+ for cell in cells:
+ if cell.id in held:
+ raise ValueError("cell ids must be unique within the notebook")
+ held[cell.id] = cell
+ plain = deepcopy(dict(app_config))
+ self._cells = held
+ self._app_config: Mapping[str, Any] = plain
+ self._order_etag = order_etag(list(held))
+ self._app_config_etag = app_config_etag(plain)
+ self._etag = document_etag(
+ self._order_etag,
+ self._app_config_etag,
+ [cell.etag for cell in held.values()],
+ )
@classmethod
- def from_records(
+ def restore(
cls,
document: protocol.Document,
cells: Sequence[protocol.Cell],
) -> Document:
- """Restore a document from its protocol records.
+ """Rebuild a document from the records the notebook published.
- Cell identities, order, and revisions must agree. The saved
- revision is preserved.
+ Cell identities, order, and revisions must agree.
"""
- document, cells = deepcopy((document, cells))
by_id = {cell.id: cell for cell in cells}
if len(by_id) != len(cells) or (
len(set(document.order)) != len(document.order)
@@ -183,13 +195,11 @@ class Document:
if any(cell.notebook_id != document.notebook_id for cell in cells):
raise ValueError("cells must belong to the document")
restored = cls(
- document.notebook_id,
[
- CellSource(cell.id, cell.code, cell.name, cell.config)
+ DocumentCell(cell.id, cell.code, cell.name, cell.config)
for cell in (by_id[cell_id] for cell_id in document.order)
],
document.app_config,
- saved=False,
)
for cell in restored:
original = by_id[cell.id]
@@ -198,126 +208,116 @@ class Document:
or cell.code_hash != original.code_hash
):
raise ValueError("cell revisions must match their content")
- current = restored._record
if (
- current.etag != document.etag
- or current.order_etag != document.order_etag
- or current.app_config_etag != document.app_config_etag
+ restored.etag != document.etag
+ or restored.order_etag != document.order_etag
+ or restored.app_config_etag != document.app_config_etag
):
raise ValueError("document revisions must match its content")
- if document.saved_etag is not None:
- restored.mark_saved(document.saved_etag)
return restored
+ # ---- reading --------------------------------------------------------
+
+ def __iter__(self) -> Iterator[DocumentCell]:
+ """Iterate over cells in document order."""
+ return iter(self._cells.values())
+
+ def cell(self, cell_id: protocol.CellId) -> DocumentCell | None:
+ return self._cells.get(cell_id)
+
@property
- def notebook_id(self) -> protocol.NotebookId:
- """The notebook this document belongs to."""
- return self._id
+ def etag(self) -> protocol.Etag:
+ """Identifies cells, order, and app config together."""
+ return self._etag
@property
- def _record(self) -> protocol.Document:
- assert self._document is not None
- return self._document
+ def order_etag(self) -> protocol.Etag:
+ return self._order_etag
- def __iter__(self) -> Iterator[protocol.Cell]:
- """Iterate over cells in document order."""
- for cell_id in self._order:
- yield self._cells[cell_id]
+ @property
+ def app_config_etag(self) -> protocol.Etag:
+ return self._app_config_etag
@property
- def order(self) -> list[str]:
- return list(self._order)
+ def app_config(self) -> Mapping[str, Any]:
+ """The app config. Treat this mapping and nested values as read-only."""
+ return self._app_config
- def cell(self, cell_id: str) -> protocol.Cell | None:
- return self._cells.get(cell_id)
+ def __eq__(self, other: object) -> bool:
+ return isinstance(other, Document) and other._etag == self._etag
- def snapshot(self) -> DocumentSnapshot:
- """Capture one revision without sharing mutable configuration."""
- return deepcopy(DocumentSnapshot(self._record, tuple(self)))
+ def __hash__(self) -> int:
+ return hash(self._etag)
- def replace(
- self, cells: Sequence[CellSource], app_config: Mapping[str, Any]
- ) -> Changed:
- """Replace cells and configuration and return what changed.
+ def __repr__(self) -> str:
+ return f"Document(etag={self._etag!r}, cells={len(self._cells)})"
- Cell IDs must be unique.
- """
- order = [source.id for source in cells]
- if len(set(order)) != len(order):
- raise ValueError("cell ids must be unique within the notebook")
- built = {source.id: self._build(source) for source in cells}
+ # ---- producing the next revision ------------------------------------
+
+ def replace(
+ self, cells: Iterable[DocumentCell], app_config: Mapping[str, Any]
+ ) -> tuple[Document, Changed]:
+ """The document with these cells and config, and what changed."""
+ document = Document(cells, app_config)
changed = [
- built[cell_id]
- for cell_id in order
- if self._cells.get(cell_id) != built[cell_id]
+ cell for cell in document if self._cells.get(cell.id) != cell
]
- removed = [cell_id for cell_id in self._order if cell_id not in built]
- self._cells = built
- self._order = order
- self._app_config = dict(app_config)
- return Changed(changed, removed, self._refresh())
+ removed = [
+ cell_id
+ for cell_id in self._cells
+ if cell_id not in document._cells
+ ]
+ revised = None if document._etag == self._etag else document._etag
+ return document, Changed(changed, removed, revised)
- def apply(self, changes: Sequence[protocol.Change]) -> Applied:
+ def apply(
+ self, changes: Sequence[protocol.Change]
+ ) -> tuple[Document, Applied] | Stale:
"""Apply `changes` in order as one unit, or none of them.
- Every precondition is compared with the document as it was when
- the request arrived, so one request can create a cell and then
- place it with the order etag the client read.
+ Preconditions are checked against this document, so one request
+ can create a cell and then place it with the order etag the
+ client read. A stale precondition returns `Stale`.
Raises:
- EditConflict: If a precondition names a state the document no
- longer has. Nothing is applied.
Invalid: If a change could not apply to any state.
"""
- staged: dict[str, CellSource] = {
- cell.id: CellSource(cell.id, cell.code, cell.name, cell.config)
- for cell in self
- }
- order = list(self._order)
- touched: dict[str, bool] = {}
- before = self._record
-
- def matches(base: str, cell_id: str) -> bool:
+ staged: dict[protocol.CellId, DocumentCell] = dict(self._cells)
+ order: list[protocol.CellId] = list(self._cells)
+ touched: dict[protocol.CellId, bool] = {}
+
+ def matches(base: str, cell_id: protocol.CellId) -> bool:
if base == "*":
return True
current = self._cells.get(cell_id)
return current is not None and base == current.etag
- def stale(index: int, cell_id: str | None) -> EditConflict:
- return EditConflict(
- f"change {index} names a state the document no longer has",
- change=index,
- cell=None if cell_id is None else self._cells.get(cell_id),
- document=before,
- )
-
for index, change in enumerate(changes):
if isinstance(change, protocol.PutCell):
- source = _source(change.cell)
- cell_id = source.id
+ cell = _cell(change.cell)
if change.base_etag is None:
# A cell deleted earlier in the batch still existed
# when the client read, so creating it is a conflict.
- if cell_id in self._cells or cell_id in staged:
- raise stale(index, cell_id)
- order.insert(_slot(order, change, index), cell_id)
- elif cell_id not in staged or not matches(
- change.base_etag, cell_id
+ if cell.id in self._cells or cell.id in staged:
+ return Stale(index, cell.id)
+ order.insert(_slot(order, change, index), cell.id)
+ elif cell.id not in staged or not matches(
+ change.base_etag, cell.id
):
- raise stale(index, cell_id)
- staged[cell_id] = source
- touched[cell_id] = True
+ return Stale(index, cell.id)
+ staged[cell.id] = cell
+ touched[cell.id] = True
elif isinstance(change, protocol.DeleteCell):
if change.id not in staged or not matches(
change.base_etag, change.id
):
- raise stale(index, change.id)
+ return Stale(index, change.id)
del staged[change.id]
order.remove(change.id)
touched[change.id] = False
elif isinstance(change, protocol.SetOrder):
- if change.base_etag not in ("*", before.order_etag):
- raise stale(index, None)
+ if change.base_etag not in ("*", self._order_etag):
+ return Stale(index, None)
if sorted(change.order) != sorted(order) or len(
set(change.order)
) != len(change.order):
@@ -328,69 +328,28 @@ class Document:
else:
raise Invalid(f"change {index} has an unknown kind")
- changed = self.replace(
+ document, changed = self.replace(
[staged[cell_id] for cell_id in order], self._app_config
)
- cells: dict[str, protocol.CellEtags | None] = {}
+ cells: dict[protocol.CellId, protocol.CellEtags | None] = {}
for cell_id, put in touched.items():
if put:
- cell = self._cells[cell_id]
+ cell = document._cells[cell_id]
cells[cell_id] = protocol.CellEtags(
etag=cell.etag, code_hash=cell.code_hash
)
else:
cells[cell_id] = None
- return Applied(changed, cells)
-
- def mark_saved(
- self, etag: protocol.Etag | None = None
- ) -> protocol.Document | None:
- """Record the persisted revision, which may precede the current one."""
- self._saved_etag = self._record.etag if etag is None else etag
- return self._refresh()
-
- def _build(self, source: CellSource) -> protocol.Cell:
- code = normalize_code(source.code)
- hashed = code_hash(code)
- return protocol.Cell(
- id=protocol.CellId(source.id),
- notebook_id=self._id,
- code=code,
- name=source.name,
- config=source.config,
- etag=cell_etag(hashed, source.name, source.config),
- code_hash=hashed,
- )
-
- def _refresh(self) -> protocol.Document | None:
- """Recompute the document and return it when it changed."""
- order = order_etag(self._order)
- app_config = app_config_etag(self._app_config)
- document = protocol.Document(
- notebook_id=self._id,
- order=tuple(protocol.CellId(c) for c in self._order),
- app_config=dict(self._app_config),
- etag=document_etag(
- order,
- app_config,
- [self._cells[cell_id].etag for cell_id in self._order],
- ),
- saved_etag=self._saved_etag,
- order_etag=order,
- app_config_etag=app_config,
- )
- if document == self._document:
- return None
- self._document = document
- return document
+ return document, Applied(changed, cells)
-def _source(cell: protocol.CellInput) -> CellSource:
+def _cell(cell: protocol.CellInput) -> DocumentCell:
+ """The cell a client's input describes, with unset fields defaulted."""
name = "_" if cell.name is UNSET else cell.name
config = cell.config
if config is UNSET:
- return CellSource(cell.id, cell.code, name)
- return CellSource(
+ return DocumentCell(cell.id, cell.code, name)
+ return DocumentCell(
cell.id,
cell.code,
name,
@@ -405,7 +364,9 @@ def _source(cell: protocol.CellInput) -> CellSource:
)
-def _slot(order: list[str], change: protocol.PutCell, index: int) -> int:
+def _slot(
+ order: list[protocol.CellId], change: protocol.PutCell, index: int
+) -> int:
"""Where a created cell goes: after or before an anchor, or at the end."""
after = None if change.after is UNSET else change.after
before = None if change.before is UNSET else change.before
diff --git a/marimo/_core/executions.py b/marimo/_core/executions.py
index 0ff3803048..8c28c5ac38 100644
--- a/marimo/_core/executions.py
+++ b/marimo/_core/executions.py
@@ -16,6 +16,8 @@ from marimo._core.stream import utcnow
if TYPE_CHECKING:
from collections.abc import Iterable, Mapping
+ from marimo._core.document import DocumentCell
+
@dataclass(frozen=True)
class CellExecution:
@@ -92,7 +94,7 @@ class Executions:
cls,
executions: Mapping[protocol.CellId, CellExecution],
*,
- cells: Iterable[protocol.Cell],
+ cells: Iterable[DocumentCell],
) -> Executions:
"""Restore completed executions for cells in the document.
diff --git a/marimo/_core/notebook.py b/marimo/_core/notebook.py
index 8d40b85479..59b9cf633b 100644
--- a/marimo/_core/notebook.py
+++ b/marimo/_core/notebook.py
@@ -5,14 +5,15 @@ from __future__ import annotations
import asyncio
import logging
+from copy import deepcopy
from typing import TYPE_CHECKING, Any
import msgspec
from msgspec.structs import replace
from marimo._core import backend as be, protocol
-from marimo._core.document import Changed
-from marimo._core.errors import Conflict, NoRuntime, NotFound
+from marimo._core.document import Stale
+from marimo._core.errors import Conflict, EditConflict, NoRuntime, NotFound
from marimo._core.executions import Executions, Released, Removed
from marimo._core.ids import mint
from marimo._core.stream import Event, Kind, kind_of, message, utcnow
@@ -21,7 +22,11 @@ if TYPE_CHECKING:
from collections.abc import Callable, Mapping, Sequence
from marimo._core.analysis import Analyzer
- from marimo._core.document import CellSource, Document, DocumentSnapshot
+ from marimo._core.document import (
+ Changed,
+ Document,
+ DocumentCell,
+ )
from marimo._core.executions import Change
from marimo._core.stream import Body, Sink
@@ -32,10 +37,11 @@ LOGGER = logging.getLogger(__name__)
class Notebook:
"""A document, its execution results, and the runtime that produces them.
- The document and cell results remain when the runtime stops.
- Commands call the backend and publish changes through the sink.
- Change the document and executions through the notebook so each
- change reaches the sink.
+ The notebook gives the document its identity and its saved revision,
+ and publishes the records clients read. The document
+ and cell results remain when the runtime stops. Commands call the
+ backend and publish changes through the sink. Change the document
+ and executions through the notebook so each change reaches the sink.
With an analyzer, the notebook requests analysis of each document
revision and publishes the result when that revision is still
@@ -44,14 +50,21 @@ class Notebook:
def __init__(
self,
+ notebook_id: protocol.NotebookId,
document: Document,
executions: Executions,
backend: be.Backend,
sink: Sink,
*,
+ saved_etag: protocol.Etag | None = None,
analyzer: Analyzer | None = None,
) -> None:
+ self._id = notebook_id
self._document = document
+ self._saved_etag = saved_etag
+ # The document record as last published, so a change that leaves
+ # it the same publishes nothing.
+ self._published: protocol.Document | None = self._document_record
self._executions = executions
self.backend = backend
self.sink = sink
@@ -71,7 +84,7 @@ class Notebook:
@property
def document(self) -> Document:
- """The document owned by this notebook; change it through the notebook."""
+ """The current revision. The notebook's commands produce the next."""
return self._document
@property
@@ -81,7 +94,41 @@ class Notebook:
@property
def id(self) -> protocol.NotebookId:
- return self.document.notebook_id
+ return self._id
+
+ @property
+ def saved_etag(self) -> protocol.Etag | None:
+ """The document revision the store holds, if known."""
+ return self._saved_etag
+
+ def require_revision(self, etags: Sequence[str]) -> None:
+ """Check that the document is at one of `etags`.
+
+ Raises:
+ EditConflict: If it is not, carrying the document as it is.
+ """
+ self._require_open()
+ if self.document.etag not in etags:
+ raise EditConflict(
+ "The document has changed since it was read",
+ change=0,
+ cell=None,
+ document=self._document_record,
+ )
+
+ @property
+ def _document_record(self) -> protocol.Document:
+ """The document as clients read it, built from its current state."""
+ document = self._document
+ return protocol.Document(
+ notebook_id=self._id,
+ order=tuple(cell.id for cell in document),
+ app_config=deepcopy(dict(document.app_config)),
+ etag=document.etag,
+ saved_etag=self._saved_etag,
+ order_etag=document.order_etag,
+ app_config_etag=document.app_config_etag,
+ )
@property
def runtime(self) -> protocol.Runtime | None:
@@ -101,23 +148,34 @@ class Notebook:
def replace(
self,
- cells: Sequence[CellSource],
+ cells: Sequence[DocumentCell],
app_config: Mapping[str, object],
*,
saved: bool = False,
request_id: str | None = None,
- ) -> Changed:
+ ) -> protocol.EditResponse:
"""Replace the document and publish its changes.
With `saved`, the new contents are also the persisted revision.
+ The response carries etags for the cells that changed, and
+ `None` for each cell that was removed.
"""
self._require_open()
- document = self.document
- changed = document.replace(cells, app_config)
- if saved and (published := document.mark_saved()) is not None:
- changed = Changed(changed.cells, changed.removed, published)
+ self._document, changed = self._document.replace(cells, app_config)
+ if saved:
+ self._saved_etag = self._document.etag
self._publish_changed(changed, request_id)
- return changed
+ etags: dict[str, protocol.CellEtags | None] = {
+ cell.id: protocol.CellEtags(
+ etag=cell.etag, code_hash=cell.code_hash
+ )
+ for cell in changed.cells
+ }
+ for cell_id in changed.removed:
+ etags[cell_id] = None
+ return protocol.EditResponse(
+ document=self._document_record, cells=etags
+ )
def edit(
self, changes: Sequence[protocol.Change], *, request_id: str
@@ -129,10 +187,25 @@ class Notebook:
Invalid: If a change could not apply to any state.
"""
self._require_open()
- applied = self.document.apply(changes)
+ result = self._document.apply(changes)
+ if isinstance(result, Stale):
+ cell = (
+ None
+ if result.cell_id is None
+ else self._document.cell(result.cell_id)
+ )
+ raise EditConflict(
+ f"change {result.change} names a state the document no "
+ "longer has",
+ change=result.change,
+ cell=None if cell is None else self._cell_record(cell),
+ document=self._document_record,
+ )
+ self._document, applied = result
self._publish_changed(applied.changed, request_id)
return protocol.EditResponse(
- document=self.document._record, cells=applied.cells
+ document=self._document_record,
+ cells=dict(applied.cells.items()),
)
def mark_saved(
@@ -144,10 +217,30 @@ class Notebook:
changed while it was being written.
"""
self._require_open()
- published = self.document.mark_saved(etag)
+ self._saved_etag = etag
+ published = self._refresh()
if published is not None:
self._publish(published, request_id)
- return self.document._record
+ return self._document_record
+
+ def _cell_record(self, cell: DocumentCell) -> protocol.Cell:
+ return protocol.Cell(
+ id=cell.id,
+ notebook_id=self._id,
+ code=cell.code,
+ name=cell.name,
+ config=cell.config,
+ etag=cell.etag,
+ code_hash=cell.code_hash,
+ )
+
+ def _refresh(self) -> protocol.Document | None:
+ """Return the document record when it differs from the last published."""
+ record = self._document_record
+ if record == self._published:
+ return None
+ self._published = record
+ return record
def _publish_changed(
self, changed: Changed, request_id: str | None
@@ -155,15 +248,16 @@ class Notebook:
"""Publish a document change, then analyze the new revision."""
with self.sink.deferred():
for cell in changed.cells:
- self._publish(cell, request_id)
+ self._publish(self._cell_record(cell), request_id)
for cell_id in changed.removed:
self._apply(
self.executions.remove_cell(protocol.CellId(cell_id))
)
self._remove("cell", cell_id, request_id)
- if changed.document is not None:
- self._publish(changed.document, request_id)
- if changed.document is not None:
+ record = self._refresh()
+ if record is not None:
+ self._publish(record, request_id)
+ if changed.etag is not None:
self._request_analysis(request_id)
# ---- analysis ------------------------------------------------------
@@ -176,22 +270,22 @@ class Notebook:
self._reanalyze, self._reanalyze_request = True, request_id
return
self._analysis_task = asyncio.create_task(
- self._analyze(self.document.snapshot(), request_id)
+ self._analyze(self._document, request_id)
)
async def _analyze(
- self, snapshot: DocumentSnapshot, request_id: str | None
+ self, document: Document, request_id: str | None
) -> None:
assert self._analyzer is not None
try:
while not self._closed:
- etag = snapshot.document.etag
+ etag = document.etag
try:
- cells = await self._analyzer.analyze(snapshot)
+ cells = await self._analyzer.analyze(document)
except Exception:
LOGGER.exception("Could not analyze document %s", etag)
else:
- if not self._closed and etag == self.document._record.etag:
+ if not self._closed and etag == self._document.etag:
self._analysis = protocol.Analysis(
notebook_id=self.id,
document_etag=etag,
@@ -205,7 +299,7 @@ class Notebook:
return
request_id = self._reanalyze_request
self._reanalyze, self._reanalyze_request = False, None
- snapshot = self.document.snapshot()
+ document = self._document
finally:
self._analysis_task = None
@@ -469,7 +563,10 @@ class Notebook:
def _snapshot(self) -> list[Event]:
"""Return current state as events in dependency order."""
- bodies: list[Body] = [*self.document, self.document._record]
+ bodies: list[Body] = [
+ *(self._cell_record(cell) for cell in self.document),
+ self._document_record,
+ ]
if self._analysis is not None:
bodies.append(self._analysis)
if self._runtime is not None:
diff --git a/marimo/_server/host/analysis.py b/marimo/_server/host/analysis.py
index 40246711ce..e84520dc76 100644
--- a/marimo/_server/host/analysis.py
+++ b/marimo/_server/host/analysis.py
@@ -18,21 +18,21 @@ from marimo._runtime.dataflow.edges import resolve_cell_references
from marimo._types.ids import CellId_t
if TYPE_CHECKING:
- from marimo._core.document import DocumentSnapshot
+ from marimo._core.document import Document
SOURCE = "marimo"
class HostAnalyzer:
- """Analyze serialized document snapshots in a worker thread."""
+ """Analyze document revisions in a worker thread."""
def __init__(self) -> None:
self._cells = CellAnalyzer()
async def analyze(
- self, snapshot: DocumentSnapshot
+ self, document: Document
) -> dict[protocol.CellId, protocol.CellAnalysis]:
- return await asyncio.to_thread(self._cells, snapshot)
+ return await asyncio.to_thread(self._cells, document)
@dataclass(frozen=True)
@@ -42,17 +42,17 @@ class _CachedCell:
class CellAnalyzer:
- """Reuse compilation by cell identity and code hash across snapshots."""
+ """Reuse compilation by cell identity and code hash across revisions."""
def __init__(self) -> None:
self._cache: dict[protocol.CellId, _CachedCell] = {}
def __call__(
- self, snapshot: DocumentSnapshot
+ self, document: Document
) -> dict[protocol.CellId, protocol.CellAnalysis]:
cache: dict[protocol.CellId, _CachedCell] = {}
graph = DirectedGraph()
- for cell in snapshot.cells:
+ for cell in document:
cached = self._cache.get(cell.id)
if cached is None or cached.code_hash != cell.code_hash:
try:
@@ -68,7 +68,7 @@ class CellAnalyzer:
self._cache = cache
analyses: dict[protocol.CellId, protocol.CellAnalysis] = {}
- for cell in snapshot.cells:
+ for cell in document:
compiled = cache[cell.id].result
if isinstance(compiled, protocol.Error):
analyses[cell.id] = protocol.CellAnalysis(
diff --git a/marimo/_server/host/bridge.py b/marimo/_server/host/bridge.py
index fb24ac2043..3c98b9726b 100644
--- a/marimo/_server/host/bridge.py
+++ b/marimo/_server/host/bridge.py
@@ -10,11 +10,10 @@ from typing import TYPE_CHECKING, Any
from marimo import _loggers
from marimo._core import protocol
-from marimo._core.document import CellSource, Document, revision
+from marimo._core.document import Document, DocumentCell
from marimo._core.errors import (
Conflict,
DecisionRequired,
- EditConflict,
Invalid,
NotFound,
)
@@ -38,7 +37,6 @@ if TYPE_CHECKING:
from marimo._config.manager import MarimoConfigManager
from marimo._core.backend import Message
- from marimo._core.document import Changed
from marimo._core.stream import Event, Sink
from marimo._messaging.notebook import NotebookCell
from marimo._server.session_manager import SessionManager
@@ -62,7 +60,7 @@ class _FileContents:
"""A notebook file as read: its text and the document it parses to."""
text: str
- cells: list[CellSource]
+ cells: list[DocumentCell]
app_config: dict[str, Any]
@@ -77,19 +75,6 @@ def _texts_differ(text: str, baseline: str) -> bool:
return contents_differ_excluding_generated_with(text, baseline)
-def _etags(
- changed: Changed, document: protocol.Document
-) -> protocol.EditResponse:
- """An edit response for a replacement, with etags for what changed."""
- cells: dict[str, protocol.CellEtags | None] = {
- cell.id: protocol.CellEtags(etag=cell.etag, code_hash=cell.code_hash)
- for cell in changed.cells
- }
- for cell_id in changed.removed:
- cells[cell_id] = None
- return protocol.EditResponse(document=document, cells=cells)
-
-
def _running_loop() -> asyncio.AbstractEventLoop | None:
try:
return asyncio.get_running_loop()
@@ -118,6 +103,9 @@ class SessionBridge(SessionEventListener):
"""Each file's text as the host last read or wrote it, without a session."""
self._rebaselining: dict[protocol.NotebookId, asyncio.Task[None]] = {}
self._adopting: dict[protocol.NotebookId, Session] = {}
+ # TODO(MO-8005): The response to the session's latest mirror of its
+ # app config, for the edit that caused it. Ends with the mirror.
+ self._mirrored: dict[protocol.NotebookId, protocol.EditResponse] = {}
self.host = Host(operations=OPERATIONS)
self._backends: dict[protocol.NotebookId, SessionBackend] = {}
self.index = WorkspaceIndex(
@@ -169,20 +157,20 @@ class SessionBridge(SessionEventListener):
raise Conflict("The notebook document could not be loaded")
cells, app_config = loaded.cells, loaded.app_config
self._file_texts[record.id] = loaded.text
- document = Document(
- record.id,
- cells,
- app_config,
- saved=session is None,
- )
+ document = Document(cells, app_config)
+ # Without a session the file is what was read. With one, the
+ # editor's document may have moved on from the file.
+ saved_etag = document.etag if session is None else None
if session is not None and loaded is not None:
- document.mark_saved(revision(loaded.cells, loaded.app_config))
+ saved_etag = Document(loaded.cells, loaded.app_config).etag
backend = self._make_backend(record.id)
return Notebook(
+ record.id,
document,
Executions(),
backend,
sink,
+ saved_etag=saved_etag,
analyzer=HostAnalyzer(),
)
@@ -257,14 +245,9 @@ class SessionBridge(SessionEventListener):
if file is None:
raise Conflict("The notebook has no file to save to")
# Check and snapshot only after waiting for the file lock.
- snapshot = notebook.document.snapshot()
- if if_match is not None and snapshot.document.etag not in if_match:
- raise EditConflict(
- "The document has changed since it was read",
- change=0,
- cell=None,
- document=snapshot.document,
- )
+ if if_match is not None:
+ notebook.require_revision(if_match)
+ revision = notebook.document
session = self._session_of(notebook.id)
if session is None and await self._file_changed(notebook.id, file):
answer = (decisions or {}).get(_FILE_CHANGED.id)
@@ -275,7 +258,7 @@ class SessionBridge(SessionEventListener):
)
if answer == "reload":
return await self._reload(
- notebook, file, snapshot.document, request_id
+ notebook, file, revision.etag, request_id
)
if answer != "overwrite":
raise Invalid(
@@ -287,7 +270,7 @@ class SessionBridge(SessionEventListener):
# The notebook's writer must persist snapshots without mutating
# the live document; cover attached-session edits during a save.
if session is None:
- cells = [documents.to_notebook_cell(c) for c in snapshot.cells]
+ cells = [documents.to_notebook_cell(c) for c in revision]
manager = None
else:
cells = copy.deepcopy(session.document.cells)
@@ -321,9 +304,9 @@ class SessionBridge(SessionEventListener):
if manager is None:
manager = self._file_manager(path)
text = manager.save_from_cells(cells)
- etag = revision(
+ etag = Document(
documents.sources(cells), manager.app.config.asdict_difference()
- )
+ ).etag
return etag, text
async def _file_changed(
@@ -351,7 +334,7 @@ class SessionBridge(SessionEventListener):
self,
notebook: Notebook,
file: Path,
- before: protocol.Document,
+ before: protocol.Etag,
request_id: str,
) -> protocol.EditResponse:
"""Replace the document with the file's contents as the saved revision."""
@@ -360,18 +343,11 @@ class SessionBridge(SessionEventListener):
raise Conflict("The notebook file could not be loaded")
# An edit may have landed while the file was read. Replacing the
# document now would lose it.
- if notebook.document._record.etag != before.etag:
- raise EditConflict(
- "The document changed while the file was being read",
- change=0,
- cell=None,
- document=notebook.document._record,
- )
+ notebook.require_revision([before])
self._file_texts[notebook.id] = loaded.text
- changed = notebook.replace(
+ return notebook.replace(
loaded.cells, loaded.app_config, saved=True, request_id=request_id
)
- return _etags(changed, notebook.document._record)
async def edit(
self,
@@ -395,9 +371,13 @@ class SessionBridge(SessionEventListener):
session = self._session_of(notebook.id)
if session is None:
return response
+ self._mirrored.pop(notebook.id, None)
documents.apply_to_session(session, notebook.document)
+ mirrored = self._mirrored.pop(notebook.id, None)
+ if mirrored is None:
+ return response
return protocol.EditResponse(
- cells=response.cells, document=notebook.document._record
+ cells=response.cells, document=mirrored.document
)
def _session_of(self, notebook_id: protocol.NotebookId) -> Session | None:
@@ -420,9 +400,8 @@ class SessionBridge(SessionEventListener):
# host is no longer wanted.
self._rebaselining.pop(notebook_id, None)
self._follow_saves(notebook_id, session)
- document = notebook.document
- if document._record.saved_etag != document._record.etag:
- documents.apply_to_session(session, document)
+ if notebook.saved_etag != notebook.document.etag:
+ documents.apply_to_session(session, notebook.document)
return
cells, app_config = documents.from_session(session)
notebook.replace(cells, app_config, saved=True)
@@ -446,7 +425,7 @@ class SessionBridge(SessionEventListener):
def persisted(
cells: Sequence[NotebookCell], app_config: dict[str, Any]
) -> None:
- etag = revision(documents.sources(cells), app_config)
+ etag = Document(documents.sources(cells), app_config).etag
if _running_loop() is loop:
self._saved(notebook_id, etag)
else:
@@ -515,7 +494,7 @@ class SessionBridge(SessionEventListener):
if session is None or notebook is None:
return
cells, app_config = documents.from_session(session)
- notebook.replace(cells, app_config)
+ self._mirrored[notebook_id] = notebook.replace(cells, app_config)
def _project_path(self, path: Path) -> Path:
root = self.index.root
@@ -670,6 +649,7 @@ class SessionBridge(SessionEventListener):
self._backends.pop(event.notebook_id, None)
self._file_texts.pop(event.notebook_id, None)
self._rebaselining.pop(event.notebook_id, None)
+ self._mirrored.pop(event.notebook_id, None)
async def _adopt(self, session: Session) -> None:
path = session.app_file_manager.path
diff --git a/marimo/_server/host/document.py b/marimo/_server/host/document.py
index ceef792954..c4ea4b4c24 100644
--- a/marimo/_server/host/document.py
+++ b/marimo/_server/host/document.py
@@ -22,7 +22,7 @@ from typing import TYPE_CHECKING, Any
from marimo._ast.cell import CellConfig
from marimo._core import protocol
-from marimo._core.document import CellSource
+from marimo._core.document import DocumentCell
from marimo._messaging.notebook import (
CreateCell,
DeleteCell,
@@ -48,26 +48,38 @@ if TYPE_CHECKING:
from marimo._session.session import Session
-def from_session(session: Session) -> tuple[list[CellSource], dict[str, Any]]:
+def from_session(
+ session: Session,
+) -> tuple[list[DocumentCell], dict[str, Any]]:
return (
sources(session.document.cells),
session.app_file_manager.app.config.asdict_difference(),
)
-def sources(cells: Iterable[NotebookCell]) -> list[CellSource]:
+def sources(cells: Iterable[NotebookCell]) -> list[DocumentCell]:
"""The document sources for the editor's cells."""
return [
- CellSource(cell.id, cell.code, cell.name, _config(cell.config))
+ DocumentCell(
+ protocol.CellId(cell.id),
+ cell.code,
+ cell.name,
+ _config(cell.config),
+ )
for cell in cells
]
def from_file_manager(
manager: AppFileManager,
-) -> tuple[list[CellSource], dict[str, Any]]:
+) -> tuple[list[DocumentCell], dict[str, Any]]:
cells = [
- CellSource(data.cell_id, data.code, data.name, _config(data.config))
+ DocumentCell(
+ protocol.CellId(data.cell_id),
+ data.code,
+ data.name,
+ _config(data.config),
+ )
for data in manager.app.cell_manager.cell_data()
]
return cells, manager.app.config.asdict_difference()
@@ -91,7 +103,7 @@ def _cell_config(config: protocol.CellConfig) -> CellConfig:
)
-def to_notebook_cell(cell: protocol.Cell) -> NotebookCell:
+def to_notebook_cell(cell: DocumentCell) -> NotebookCell:
return NotebookCell(
id=CellId_t(cell.id),
code=cell.code,
@@ -153,7 +165,7 @@ def apply_to_session(session: Session, document: Document) -> None:
wanted = {CellId_t(cell.id) for cell in document}
deleted = [c for c in current.cell_ids if c not in wanted]
changes.extend(DeleteCell(cell_id=cell_id) for cell_id in deleted)
- order = [CellId_t(c) for c in document.order]
+ order = [CellId_t(c.id) for c in document]
if current.cell_ids != order:
changes.append(ReorderCells(cell_ids=tuple(order)))
if not changes:
diff --git a/tests/_core/conftest.py b/tests/_core/conftest.py
index 98feaef598..4c66737dc3 100644
--- a/tests/_core/conftest.py
+++ b/tests/_core/conftest.py
@@ -8,7 +8,7 @@ import asyncio
import pytest
from marimo._core import backend as be, protocol
-from marimo._core.document import Document, DocumentSnapshot, code_hash
+from marimo._core.document import Document, code_hash
from marimo._core.executions import CellExecution, Executions
from marimo._core.host import Host
from marimo._core.notebook import Notebook
@@ -44,16 +44,16 @@ class ScriptedAnalyzer:
"""Expose snapshots and let tests complete analysis explicitly."""
def __init__(self) -> None:
- self.requests: list[DocumentSnapshot] = []
+ self.requests: list[Document] = []
self.pending: asyncio.Queue[
tuple[
- DocumentSnapshot,
+ Document,
asyncio.Future[dict[protocol.CellId, protocol.CellAnalysis]],
]
] = asyncio.Queue()
async def analyze(
- self, snapshot: DocumentSnapshot
+ self, snapshot: Document
) -> dict[protocol.CellId, protocol.CellAnalysis]:
result: asyncio.Future[
dict[protocol.CellId, protocol.CellAnalysis]
@@ -65,7 +65,7 @@ class ScriptedAnalyzer:
async def next_request(
self,
) -> tuple[
- DocumentSnapshot,
+ Document,
asyncio.Future[dict[protocol.CellId, protocol.CellAnalysis]],
]:
return await asyncio.wait_for(self.pending.get(), timeout=5)
@@ -109,11 +109,14 @@ def make_notebook(
document: Document | None = None,
analyzer: ScriptedAnalyzer | None = None,
) -> Notebook:
+ document = document if document is not None else Document([], {})
return Notebook(
- document or Document(record.id, [], {}),
+ record.id,
+ document,
Executions(),
backend or ScriptedBackend(),
sink,
+ saved_etag=document.etag,
analyzer=analyzer,
)
diff --git a/tests/_core/test_executions.py b/tests/_core/test_executions.py
index f30d162532..baae72ac79 100644
--- a/tests/_core/test_executions.py
+++ b/tests/_core/test_executions.py
@@ -7,7 +7,7 @@ import pytest
from msgspec.structs import replace
from marimo._core import backend as be, protocol
-from marimo._core.document import CellSource, Document
+from marimo._core.document import Document, DocumentCell
from marimo._core.errors import NoRuntime
from marimo._core.executions import (
CellExecution,
@@ -265,7 +265,7 @@ def test_removing_a_cell_drops_its_result_or_disowns_active_work() -> None:
def test_restored_executions_are_current_until_replaced() -> None:
- document = Document(NOTEBOOK, [CellSource("c1", "42")], {})
+ document = Document([DocumentCell("c1", "42")], {})
retained = retained_execution(run_id="old-run")
executions = Executions.restore(
{protocol.CellId("c1"): retained}, cells=document
@@ -300,7 +300,7 @@ def test_restored_executions_are_current_until_replaced() -> None:
def test_restore_rejects_inconsistent_executions(
invalid: str, message: str
) -> None:
- document = Document(NOTEBOOK, [CellSource("c1", "42")], {})
+ document = Document([DocumentCell("c1", "42")], {})
retained = retained_execution()
execution, outputs = retained.execution, retained.outputs
key = protocol.CellId("c1")
diff --git a/tests/_core/test_notebook.py b/tests/_core/test_notebook.py
index eec5161658..fd1f158e39 100644
--- a/tests/_core/test_notebook.py
+++ b/tests/_core/test_notebook.py
@@ -12,8 +12,8 @@ from inline_snapshot import snapshot
from msgspec import UNSET
from msgspec.structs import replace
-from marimo._core import backend as be
-from marimo._core.document import CellSource, Document
+from marimo._core import backend as be, protocol
+from marimo._core.document import Document, DocumentCell
from marimo._core.errors import Conflict, NoRuntime, NotFound
from marimo._core.executions import CellExecution, Executions
from marimo._core.host import Host
@@ -61,6 +61,16 @@ from tests._core.conftest import (
)
+def published(
+ notebook: Notebook,
+) -> tuple[protocol.Document, list[protocol.Cell]]:
+ """The document and cell records the notebook publishes."""
+ events = notebook._snapshot()
+ (document,) = [e.data.document for e in events if e.kind == "document"] # type: ignore[union-attr]
+ cells = [e.data.cell for e in events if e.kind == "cell"] # type: ignore[union-attr]
+ return document, cells
+
+
def running(notebook: Notebook, backend: ScriptedBackend) -> Runtime:
notebook.start(request_id="req-start")
notebook.observe(
@@ -1134,16 +1144,18 @@ async def test_initial_results_are_published_and_replaced_by_live_execution(
run_id: str | None,
) -> None:
retained = retained_execution(run_id=run_id)
- document = Document(record().id, [CellSource(CellId("c1"), "42")], {})
+ document = Document([DocumentCell(CellId("c1"), "42")], {})
host = Host(operations=[])
host.update_project(project())
host.add_notebook(
record(),
lambda _, sink: Notebook(
+ record().id,
document,
Executions.restore({CellId("c1"): retained}, cells=document),
ScriptedBackend(),
sink,
+ saved_etag=document.etag,
),
)
live: list[Event] = []
@@ -1168,7 +1180,7 @@ async def test_initial_results_are_published_and_replaced_by_live_execution(
async def test_current_cell_results_can_seed_another_notebook() -> None:
_, notebook = await host_at(Clock())
- notebook.replace([CellSource(CellId("c1"), "code")], {})
+ notebook.replace([DocumentCell(CellId("c1"), "code")], {})
run = notebook.run("code", request_id="request")
execution = plan(notebook, run, "cell", "c1")
notebook.observe(
@@ -1176,18 +1188,22 @@ async def test_current_cell_results_can_seed_another_notebook() -> None:
)
finish(notebook, execution)
notebook.observe(be.Done(run.id, "succeeded"))
- document = Document.from_records(
- notebook.document._record, list(notebook.document)
- )
+ document = Document.restore(*published(notebook))
retained = notebook.executions.current(CellId("c1"))
assert retained is not None
restored = Notebook(
+ NotebookId("restored"),
document,
Executions.restore({CellId("c1"): retained}, cells=document),
ScriptedBackend(),
Stream(history=0),
+ saved_etag=notebook.saved_etag,
+ )
+ source_record, source_cells = published(notebook)
+ assert published(restored) == (
+ replace(source_record, notebook_id=restored.id),
+ [replace(cell, notebook_id=restored.id) for cell in source_cells],
)
- assert restored.document._record == notebook.document._record
assert list(restored.document) == list(notebook.document)
assert restored.executions.current(CellId("c1")) == retained
assert fold(restored._snapshot()) == {
@@ -1202,15 +1218,14 @@ def test_restoration_preserves_revisions_and_outputs(
saved: bool,
) -> None:
document = Document(
- record().id,
- [CellSource(CellId("c2"), "pass"), CellSource(CellId("c1"), "42")],
+ [DocumentCell(CellId("c2"), "pass"), DocumentCell(CellId("c1"), "42")],
{"width": "full"},
- saved=saved,
)
+ saved_etag = document.etag if saved else None
# The output belongs to the previous source, and the saved revision can
# precede the current one. Neither is rewritten during restoration.
- document.replace(
- [CellSource(CellId("c2"), "pass"), CellSource(CellId("c1"), "43")],
+ document, _ = document.replace(
+ [DocumentCell(CellId("c2"), "pass"), DocumentCell(CellId("c1"), "43")],
{"width": "full"},
)
seed = retained_execution(run_id="historical-run")
@@ -1228,16 +1243,26 @@ def test_restoration_preserves_revisions_and_outputs(
replace(seed.outputs[0], id=ItemId("last"), seq=2),
),
)
- document_record, cells = deepcopy((document._record, list(document)))
- restored = Document.from_records(document_record, cells[::-1])
+ original = Notebook(
+ record().id,
+ document,
+ Executions(),
+ ScriptedBackend(),
+ Stream(history=0),
+ saved_etag=saved_etag,
+ )
+ document_record, cells = deepcopy(published(original))
+ restored = Document.restore(document_record, cells[::-1])
backend = ScriptedBackend()
notebook = Notebook(
+ document_record.notebook_id,
restored,
Executions.restore({CellId("c1"): retained}, cells=restored),
backend,
Stream(history=0),
+ saved_etag=document_record.saved_etag,
)
- assert notebook.document._record == document._record
+ assert published(notebook) == published(original)
assert list(notebook.document) == list(document)
assert notebook.executions.current(CellId("c1")) == retained
assert backend.calls == []
@@ -1247,25 +1272,27 @@ def test_restoration_preserves_revisions_and_outputs(
assert [getattr(e.data, e.kind).seq for e in outputs] == [0, 1, 2]
# Restoration copies the supplied records.
document_record.app_config["width"] = "medium"
- assert notebook.document._record == document._record
+ assert published(notebook) == published(original)
async def test_edits_preserve_results_and_deletion_removes_them() -> None:
retained = retained_execution()
- document = Document(record().id, [CellSource(CellId("c1"), "42")], {})
+ document = Document([DocumentCell(CellId("c1"), "42")], {})
host = Host(operations=[])
host.update_project(project())
host.add_notebook(
record(),
lambda _, sink: Notebook(
+ record().id,
document,
Executions.restore({CellId("c1"): retained}, cells=document),
ScriptedBackend(),
sink,
+ saved_etag=document.etag,
),
)
notebook = await host.notebook(record().id)
- notebook.replace([CellSource(CellId("c1"), "43")], {})
+ notebook.replace([DocumentCell(CellId("c1"), "43")], {})
assert notebook.executions.current(CellId("c1")) == retained
assert (
next(iter(notebook.document)).code_hash != retained.execution.code_hash
@@ -1288,7 +1315,7 @@ async def test_restoration_excludes_live_work_and_cleans_up_deleted_active_cells
None
):
_, notebook = await host_at(Clock())
- notebook.replace([CellSource(CellId("c1"), "code")], {})
+ notebook.replace([DocumentCell(CellId("c1"), "code")], {})
notebook.attach()
run = notebook.run("code", request_id="request")
execution = plan(notebook, run, "active", "c1")
@@ -1296,9 +1323,7 @@ async def test_restoration_excludes_live_work_and_cleans_up_deleted_active_cells
be.Produced(Console(execution, ItemId("out"), "stdout", 0, "x"))
)
assert notebook.executions.current(CellId("c1")) is None
- document = Document.from_records(
- notebook.document._record, list(notebook.document)
- )
+ document = Document.restore(*published(notebook))
executions = Executions.restore(
{
cell.id: result
@@ -1308,7 +1333,12 @@ async def test_restoration_excludes_live_work_and_cleans_up_deleted_active_cells
cells=document,
)
restored = Notebook(
- document, executions, ScriptedBackend(), Stream(history=0)
+ notebook.id,
+ document,
+ executions,
+ ScriptedBackend(),
+ Stream(history=0),
+ saved_etag=notebook.saved_etag,
)
assert names(restored._snapshot()) == ["cell", "document"]
notebook.replace([], {})
@@ -1322,7 +1352,7 @@ async def test_source_edits_keep_live_results_until_the_cell_is_deleted() -> (
None
):
host, notebook = await host_at(Clock())
- notebook.replace([CellSource("c1", "42")], {})
+ notebook.replace([DocumentCell("c1", "42")], {})
run = notebook.run("42", request_id="run")
execution = plan(notebook, run, "result", "c1")
notebook.observe(
@@ -1332,7 +1362,7 @@ async def test_source_edits_keep_live_results_until_the_cell_is_deleted() -> (
notebook.observe(be.Done(run.id, "succeeded"))
retained = notebook.executions._records()
- notebook.replace([CellSource("c1", "43")], {})
+ notebook.replace([DocumentCell("c1", "43")], {})
assert notebook.executions._records() == retained
live: list[Event] = []
@@ -1353,7 +1383,7 @@ async def test_deleting_an_active_cell_releases_its_result_when_the_run_ends() -
None
):
host, notebook = await host_at(Clock())
- notebook.replace([CellSource("c1", "42")], {})
+ notebook.replace([DocumentCell("c1", "42")], {})
run = notebook.run("42", request_id="run")
execution = plan(notebook, run, "result", "c1")
notebook.replace([], {})
diff --git a/tests/_core/test_notebook_document.py b/tests/_core/test_notebook_document.py
index 9981fe1c30..7ab2d5caee 100644
--- a/tests/_core/test_notebook_document.py
+++ b/tests/_core/test_notebook_document.py
@@ -11,20 +11,20 @@ from msgspec.structs import replace
from marimo._core import protocol
from marimo._core.document import (
- CellSource,
Document,
+ DocumentCell,
+ Stale,
app_config_etag,
cell_etag,
code_hash,
document_etag,
order_etag,
- revision,
)
from marimo._core.errors import EditConflict, Invalid
from marimo._core.executions import Executions
from marimo._core.host import Host
from marimo._core.notebook import Notebook
-from marimo._core.stream import Event
+from marimo._core.stream import Event, Stream
from tests._core.conftest import (
ScriptedAnalyzer,
ScriptedBackend,
@@ -42,15 +42,23 @@ HIDDEN = protocol.CellConfig(
)
-def fixture_cells() -> list[CellSource]:
+def fixture_cells() -> list[DocumentCell]:
"""The cells in pair's `notebook-events.sse` fixture."""
return [
- CellSource("c1", "import marimo as mo"),
- CellSource("c3", "x = 21"),
- CellSource("k7f2", "y = x * 2", config=HIDDEN),
+ DocumentCell(protocol.CellId("c1"), "import marimo as mo"),
+ DocumentCell(protocol.CellId("c3"), "x = 21"),
+ DocumentCell(protocol.CellId("k7f2"), "y = x * 2", config=HIDDEN),
]
+def cell(cell_id: str, code: str, **kwargs: object) -> DocumentCell:
+ return DocumentCell(protocol.CellId(cell_id), code, **kwargs) # type: ignore[arg-type]
+
+
+def ids(document: Document) -> list[str]:
+ return [c.id for c in document]
+
+
def put(
cell_id: str,
code: str,
@@ -79,23 +87,51 @@ def set_order(base_etag: str, *cell_ids: str) -> protocol.SetOrder:
)
+def hosted(document: Document) -> Notebook:
+ """A notebook around `document` with the revision saved."""
+ return Notebook(
+ NOTEBOOK,
+ document,
+ Executions(),
+ ScriptedBackend(),
+ Stream(history=0),
+ saved_etag=document.etag,
+ )
+
+
+def records(
+ notebook: Notebook,
+) -> tuple[protocol.Document, list[protocol.Cell]]:
+ """The document and cell records the notebook publishes."""
+ events = notebook._snapshot()
+ (document,) = [e.data.document for e in events if e.kind == "document"] # type: ignore[union-attr]
+ cells = [e.data.cell for e in events if e.kind == "cell"] # type: ignore[union-attr]
+ return document, cells
+
+
+class TestCells:
+ def test_normalizes_line_endings_and_compares_by_content(self) -> None:
+ c = cell("a", "x = 1\r\ny = 2", name="named", config=HIDDEN)
+ assert c.code == "x = 1\ny = 2"
+ assert c == cell("a", "x = 1\ny = 2", name="named", config=HIDDEN)
+ assert c != cell("a", "x = 1\ny = 2", name="other", config=HIDDEN)
+
+
class TestEtags:
def test_reordering_cell_ids_with_newlines_changes_the_revision(
self,
) -> None:
- cells = [CellSource("a", "x = 1"), CellSource("a\na", "x = 1")]
- document = Document(NOTEBOOK, cells, {})
- before = document._record
+ cells = [cell("a", "x = 1"), cell("a\na", "x = 1")]
+ before = Document(cells, {})
- document.replace(list(reversed(cells)), {})
+ document, _ = before.replace(list(reversed(cells)), {})
- assert [cell.id for cell in document] == ["a\na", "a"]
- assert document._record.order_etag != before.order_etag
- assert document._record.etag != before.etag
- assert document._record.saved_etag == before.etag
+ assert ids(document) == ["a\na", "a"]
+ assert document.order_etag != before.order_etag
+ assert document.etag != before.etag
def test_match_the_values_pinned_in_the_fixtures(self) -> None:
- document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})
+ document = Document(fixture_cells(), {"width": "full"})
c1, c3, k7f2 = document
assert (c3.code_hash, c3.etag) == (
@@ -107,10 +143,10 @@ class TestEtags:
"f199b5f48ae0aabb",
)
assert c1.etag == "48d6363150d6281c"
- assert document._record.order_etag == "b9c412c2d7d63161"
- assert document._record.app_config_etag == "283513048dfeb45b"
- assert document._record.etag == "e59d9c2af02f5814"
- assert document._record.saved_etag == "e59d9c2af02f5814"
+ assert document.order_etag == "b9c412c2d7d63161"
+ assert document.app_config_etag == "283513048dfeb45b"
+ assert document.etag == "e59d9c2af02f5814"
+ assert hosted(document).saved_etag == document.etag
def test_are_derived_from_their_parts(self) -> None:
hashed = code_hash("x = 21")
@@ -135,95 +171,96 @@ class TestEtags:
order_etag(["a"]), app_config_etag({}), [hashed]
) != (document_etag(order_etag(["a"]), app_config_etag({}), []))
- def test_revision_matches_the_document_built_from_the_same_sources(
+
+class TestValue:
+ def test_config_is_detached_from_inputs_and_published_records(
self,
) -> None:
- cells = [*fixture_cells(), CellSource("crlf", "x = 1\r\ny = 2")]
- app_config = {"width": "full"}
- document = Document(NOTEBOOK, cells, app_config)
- assert revision(cells, app_config) == document._record.etag
+ config = {"auto_download": ["html"]}
+ document = Document(fixture_cells(), config)
+ notebook = hosted(document)
+ before, _ = records(notebook)
- def test_normalizes_line_endings_before_hashing(self) -> None:
- document = Document(NOTEBOOK, [CellSource("a", "x = 1\r\ny = 2")], {})
- (cell,) = document
- assert cell.code == "x = 1\ny = 2"
- assert cell.code_hash == code_hash("x = 1\ny = 2")
+ config["auto_download"].append("markdown")
+ published, _ = records(notebook)
+ published.app_config["auto_download"].clear()
+
+ assert document.app_config == {"auto_download": ["html"]}
+ assert records(notebook)[0] == before
+
+ def test_documents_with_the_same_content_are_equal(self) -> None:
+ assert Document(fixture_cells(), {"a": 1}) == Document(
+ fixture_cells(), {"a": 1}
+ )
+ assert Document(fixture_cells(), {}) != Document(
+ fixture_cells()[:2], {}
+ )
+
+ def test_changing_produces_a_new_document_and_keeps_the_old(self) -> None:
+ before = Document(fixture_cells(), {"nested": {"items": [1]}})
+
+ after, _ = before.replace([cell("c1", "42", name="renamed")], {})
+
+ assert ids(before) == ["c1", "c3", "k7f2"]
+ assert before.app_config == {"nested": {"items": [1]}}
+ assert ids(after) == ["c1"]
+ assert after.app_config == {}
+
+ def test_rejects_duplicate_ids(self) -> None:
+ with pytest.raises(ValueError, match="unique"):
+ Document([cell("a", "1"), cell("a", "2")], {})
class TestReplace:
def test_reports_new_changed_and_removed_cells(self) -> None:
- document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})
- before = document._record
+ before = Document(fixture_cells(), {"width": "full"})
- changed = document.replace(
+ document, changed = before.replace(
[
- CellSource("c1", "import marimo as mo"),
- CellSource("new", "z = 3"),
- CellSource("k7f2", "y = x * 3", config=HIDDEN),
+ cell("c1", "import marimo as mo"),
+ cell("new", "z = 3"),
+ cell("k7f2", "y = x * 3", config=HIDDEN),
],
{"width": "full"},
)
- assert [cell.id for cell in changed.cells] == ["new", "k7f2"]
+ assert [c.id for c in changed.cells] == ["new", "k7f2"]
assert changed.removed == ["c3"]
- assert changed.document is not None
- assert changed.document.order == ("c1", "new", "k7f2")
- assert changed.document.order_etag != before.order_etag
- assert changed.document.app_config_etag == before.app_config_etag
- assert changed.document.saved_etag == before.etag
+ assert changed.etag == document.etag != before.etag
+ assert ids(document) == ["c1", "new", "k7f2"]
+ assert document.order_etag != before.order_etag
+ assert document.app_config_etag == before.app_config_etag
def test_a_change_that_changes_nothing_reports_nothing(self) -> None:
- document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})
+ before = Document(fixture_cells(), {"width": "full"})
+
+ document, changed = before.replace(fixture_cells(), {"width": "full"})
- assert not document.replace(fixture_cells(), {"width": "full"})
+ assert not changed
+ assert document == before
def test_an_app_config_change_moves_only_its_etag(self) -> None:
- document = Document(NOTEBOOK, fixture_cells(), {})
- before = document._record
+ before = Document(fixture_cells(), {})
- changed = document.replace(fixture_cells(), {"width": "full"})
+ document, changed = before.replace(fixture_cells(), {"width": "full"})
assert changed.cells == []
assert changed.removed == []
- assert changed.document is not None
- assert changed.document.order_etag == before.order_etag
- assert changed.document.app_config_etag != before.app_config_etag
- assert changed.document.etag != before.etag
-
- def test_rejects_duplicate_ids(self) -> None:
- with pytest.raises(ValueError, match="unique"):
- Document(
- NOTEBOOK, [CellSource("a", "1"), CellSource("a", "2")], {}
- )
-
- def test_marks_saved_state_separately(self) -> None:
- document = Document(NOTEBOOK, fixture_cells(), {}, saved=False)
- assert document._record.saved_etag is None
-
- document.replace([CellSource("c1", "1")], {})
- saved = document.mark_saved()
-
- assert saved is not None
- assert saved.saved_etag == saved.etag
- assert document.mark_saved() is None
-
- # A store may hold a revision other than the live one.
- other = Document(NOTEBOOK, fixture_cells(), {}, saved=False)
- behind = other.mark_saved(saved.etag)
- assert behind is not None
- assert behind.saved_etag == saved.etag != behind.etag
+ assert changed.etag == document.etag
+ assert document.order_etag == before.order_etag
+ assert document.app_config_etag != before.app_config_etag
+ assert document.etag != before.etag
class TestApply:
def test_creates_replaces_deletes_and_reorders_as_one_unit(self) -> None:
- document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})
- before = document._record
- c3 = document.cell("c3")
- k7f2 = document.cell("k7f2")
+ before = Document(fixture_cells(), {"width": "full"})
+ c3 = before.cell("c3")
+ k7f2 = before.cell("k7f2")
assert c3 is not None
assert k7f2 is not None
- applied = document.apply(
+ result = before.apply(
[
put("c2", "print('hi')", None, after="c1"),
put("c3", "x = 22", c3.etag),
@@ -232,11 +269,13 @@ class TestApply:
]
)
- assert document.order == ["c3", "c2", "c1"]
+ assert not isinstance(result, Stale)
+ document, applied = result
+ assert ids(document) == ["c3", "c2", "c1"]
assert [c.id for c in applied.changed.cells] == ["c3", "c2"]
assert applied.changed.removed == ["k7f2"]
- assert applied.changed.document is not None
- assert applied.changed.document.app_config == {"width": "full"}
+ assert applied.changed.etag == document.etag
+ assert document.app_config == {"width": "full"}
assert set(applied.cells) == {"c2", "c3", "k7f2"}
assert applied.cells["k7f2"] is None
new_c3 = document.cell("c3")
@@ -247,66 +286,55 @@ class TestApply:
assert new_c3.etag != c3.etag
def test_a_stale_etag_applies_nothing_and_names_the_change(self) -> None:
- document = Document(NOTEBOOK, fixture_cells(), {})
- before = document._record
+ document = Document(fixture_cells(), {})
- with pytest.raises(EditConflict) as raised:
- document.apply(
- [
- put("new", "z = 1", None),
- put("c3", "x = 22", "0000000000000000"),
- ]
- )
+ result = document.apply(
+ [
+ put("new", "z = 1", None),
+ put("c3", "x = 22", "0000000000000000"),
+ ]
+ )
- assert raised.value.change == 1
- assert raised.value.cell == document.cell("c3")
- assert raised.value.document == before
- assert document._record == before
- assert document.cell("new") is None
+ assert result == Stale(change=1, cell_id="c3")
def test_creating_an_existing_cell_or_replacing_a_missing_one_conflicts(
self,
) -> None:
- document = Document(NOTEBOOK, fixture_cells(), {})
+ document = Document(fixture_cells(), {})
c3 = document.cell("c3")
assert c3 is not None
- with pytest.raises(EditConflict) as raised:
- document.apply([put("c3", "x = 1", None)])
- assert raised.value.cell == c3
-
- with pytest.raises(EditConflict) as raised:
- document.apply([put("nope", "x = 1", "*")])
- assert raised.value.cell is None
-
+ assert document.apply([put("c3", "x = 1", None)]) == Stale(0, "c3")
+ assert document.apply([put("nope", "x = 1", "*")]) == Stale(0, "nope")
# The cell existed when the client read, even if the same batch
# deletes it first.
- with pytest.raises(EditConflict) as raised:
- document.apply([delete("c3", c3.etag), put("c3", "x = 1", None)])
- assert raised.value.change == 1
- assert document.cell("c3") == c3
+ assert document.apply(
+ [delete("c3", c3.etag), put("c3", "x = 1", None)]
+ ) == Stale(1, "c3")
def test_star_skips_the_check(self) -> None:
- document = Document(NOTEBOOK, fixture_cells(), {})
-
- document.apply(
+ result = Document(fixture_cells(), {}).apply(
[put("c3", "x = 23", "*"), set_order("*", "k7f2", "c3", "c1")]
)
- assert document.order == ["k7f2", "c3", "c1"]
+ assert not isinstance(result, Stale)
+ assert ids(result[0]) == ["k7f2", "c3", "c1"]
def test_placement_has_no_precondition(self) -> None:
- document = Document(NOTEBOOK, fixture_cells(), {})
-
- document.apply([put("a", "1", None, before="c1")])
- document.apply([put("b", "2", None, after="c1")])
- document.apply([put("c", "3", None)])
-
- assert document.order == ["a", "c1", "b", "c3", "k7f2", "c"]
+ document = Document(fixture_cells(), {})
+ for change in (
+ put("a", "1", None, before="c1"),
+ put("b", "2", None, after="c1"),
+ put("c", "3", None),
+ ):
+ result = document.apply([change])
+ assert not isinstance(result, Stale)
+ document = result[0]
+
+ assert ids(document) == ["a", "c1", "b", "c3", "k7f2", "c"]
def test_malformed_changes_are_invalid(self) -> None:
- document = Document(NOTEBOOK, fixture_cells(), {})
- before = document._record
+ document = Document(fixture_cells(), {})
with pytest.raises(Invalid):
document.apply([set_order("*", "c1", "c3")])
@@ -316,15 +344,17 @@ class TestApply:
document.apply([put("a", "1", None, after="nope")])
with pytest.raises(Invalid):
document.apply([put("a", "1", None, after="c1", before="c3")])
- assert document._record == before
def test_an_edit_that_changes_nothing_reports_nothing(self) -> None:
- document = Document(NOTEBOOK, fixture_cells(), {})
- c3 = document.cell("c3")
+ before = Document(fixture_cells(), {})
+ c3 = before.cell("c3")
assert c3 is not None
- applied = document.apply([put("c3", "x = 21", c3.etag)])
+ result = before.apply([put("c3", "x = 21", c3.etag)])
+ assert not isinstance(result, Stale)
+ document, applied = result
+ assert document == before
assert not applied.changed
assert applied.cells["c3"] == protocol.CellEtags(
etag=c3.etag, code_hash=c3.code_hash
@@ -332,20 +362,23 @@ class TestApply:
class TestFromRecords:
- def test_preserves_the_saved_revision(self) -> None:
- source = Document(NOTEBOOK, fixture_cells(), {"width": "full"})
- # The saved revision precedes the current one; both survive.
- source.replace([CellSource("c1", "import marimo")], {"width": "full"})
- restored = Document.from_records(source._record, list(source))
- assert restored._record == source._record
- assert list(restored) == list(source)
+ def test_restores_the_content(self) -> None:
+ notebook = hosted(Document(fixture_cells(), {"width": "full"}))
+ # The saved revision precedes the current one. The content is
+ # what is restored, and the notebook carries the rest.
+ notebook.replace([cell("c1", "import marimo")], {"width": "full"})
+ document, cells = records(notebook)
+
+ restored = Document.restore(document, cells)
+
+ assert restored == notebook.document
+ assert document.saved_etag != restored.etag
@pytest.mark.parametrize(
"invalid", ["order", "notebook-id", "cell-etag", "document-etag"]
)
def test_rejects_inconsistent_records(self, invalid: str) -> None:
- source = Document(NOTEBOOK, fixture_cells(), {})
- document, cells = source._record, list(source)
+ document, cells = records(hosted(Document(fixture_cells(), {})))
if invalid == "order":
document = replace(document, order=())
elif invalid == "notebook-id":
@@ -357,7 +390,76 @@ class TestFromRecords:
else:
document = replace(document, app_config={"width": "full"})
with pytest.raises(ValueError):
- Document.from_records(document, cells)
+ Document.restore(document, cells)
+
+
+class TestNotebookRecords:
+ def test_stamps_the_notebook_id_and_carries_the_saved_state(
+ self,
+ ) -> None:
+ document = Document(fixture_cells(), {"width": "full"})
+ notebook = Notebook(
+ NOTEBOOK,
+ document,
+ Executions(),
+ ScriptedBackend(),
+ Stream(history=0),
+ )
+ record, cells = records(notebook)
+ assert record.notebook_id == NOTEBOOK
+ assert record.saved_etag is None
+ assert record.etag == document.etag
+ assert record.order == ("c1", "c3", "k7f2")
+ assert record.app_config == {"width": "full"}
+ assert [c.notebook_id for c in cells] == [NOTEBOOK] * 3
+ assert [(c.id, c.etag) for c in cells] == [
+ (c.id, c.etag) for c in document
+ ]
+
+ def test_marks_saved_state_separately(self) -> None:
+ notebook = Notebook(
+ NOTEBOOK,
+ Document(fixture_cells(), {}),
+ Executions(),
+ ScriptedBackend(),
+ Stream(history=0),
+ )
+ assert notebook.saved_etag is None
+
+ notebook.replace([cell("c1", "1")], {})
+ saved = notebook.mark_saved(notebook.document.etag)
+
+ assert saved.saved_etag == saved.etag
+ assert notebook.saved_etag == saved.etag
+
+ # A store may hold a revision other than the live one.
+ other = Notebook(
+ NOTEBOOK,
+ Document(fixture_cells(), {}),
+ Executions(),
+ ScriptedBackend(),
+ Stream(history=0),
+ )
+ behind = other.mark_saved(saved.etag)
+ assert behind.saved_etag == saved.etag != behind.etag
+
+ def test_a_stale_edit_names_the_cell_and_document_as_they_are(
+ self,
+ ) -> None:
+ document = Document(fixture_cells(), {})
+ notebook = hosted(document)
+ before, cells = records(notebook)
+ (_, c3, _) = cells
+
+ with pytest.raises(EditConflict) as raised:
+ notebook.edit(
+ [put("c3", "x = 22", "0000000000000000")], request_id="e"
+ )
+
+ assert raised.value.change == 0
+ assert raised.value.cell == c3
+ assert raised.value.document == before
+ assert notebook.document is document
class TestNotebook:
@@ -370,9 +472,7 @@ class TestNotebook:
lambda record, sink: make_notebook(
record,
sink,
- document=Document(
- NOTEBOOK, fixture_cells(), {"width": "full"}
- ),
+ document=Document(fixture_cells(), {"width": "full"}),
),
)
log.clear()
@@ -403,8 +503,8 @@ class TestNotebook:
notebook.replace(
[
- CellSource("c1", "import marimo as mo"),
- CellSource("c3", "x = 22"),
+ cell("c1", "import marimo as mo"),
+ cell("c3", "x = 22"),
],
{},
request_id="edit-1",
@@ -420,26 +520,25 @@ class TestNotebook:
notebook.replace(fixture_cells(), {})
log.clear()
- changed = notebook.replace(
- [CellSource("c1", "x = 22")], {}, saved=True
- )
+ response = notebook.replace([cell("c1", "x = 22")], {}, saved=True)
- assert changed.document is not None
- assert changed.document.saved_etag == changed.document.etag
+ assert response.document.saved_etag == response.document.etag
+ assert set(response.cells) == {"c1", "c3", "k7f2"}
+ assert response.cells["c3"] is None
assert names(log) == [
"cell",
"cell.removed",
"cell.removed",
"document",
]
- assert log[-1].data.document == changed.document # type: ignore[union-attr]
+ assert log[-1].data.document == response.document # type: ignore[union-attr]
def test_mark_saved_records_the_revision_that_was_written(
self, notebook: Notebook, log: list[Event]
) -> None:
notebook.replace(fixture_cells(), {})
- written = notebook.document._record.etag
- notebook.replace([CellSource("c1", "x = 22")], {})
+ written = notebook.document.etag
+ notebook.replace([cell("c1", "x = 22")], {})
log.clear()
document = notebook.mark_saved(written, request_id="save-1")
@@ -491,7 +590,7 @@ class TestAnalysis:
) -> None:
host.update_project(project())
analyzer = ScriptedAnalyzer()
- document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})
+ document = Document(fixture_cells(), {"width": "full"})
notebook = await add_notebook(
host,
record(),
@@ -499,8 +598,8 @@ class TestAnalysis:
document=document,
analyzer=analyzer,
)
- snapshot, result = await analyzer.next_request()
- assert snapshot == document.snapshot()
+ analyzed, result = await analyzer.next_request()
+ assert analyzed is document
assert notebook.analysis is None
log.clear()
@@ -511,7 +610,7 @@ class TestAnalysis:
assert request_ids(log) == [UNSET]
assert notebook.analysis == protocol.Analysis(
notebook_id=NOTEBOOK,
- document_etag=snapshot.document.etag,
+ document_etag=document.etag,
cells=cell_analyses(document),
)
assert names(host.events(notebook_id="n1")) == [
@@ -529,7 +628,7 @@ class TestAnalysis:
) -> None:
host.update_project(project())
analyzer = ScriptedAnalyzer()
- document = Document(NOTEBOOK, fixture_cells(), {})
+ document = Document(fixture_cells(), {})
notebook = await add_notebook(
host,
record(),
@@ -539,35 +638,37 @@ class TestAnalysis:
)
first, result = await analyzer.next_request()
first_analysis = cell_analyses(document)
- notebook.replace([CellSource("c1", "1")], {}, request_id="edit-1")
+ notebook.replace([cell("c1", "1")], {}, request_id="edit-1")
notebook.replace(
- [CellSource("c1", "2", name="named", config=HIDDEN)],
+ [cell("c1", "2", name="named", config=HIDDEN)],
{"width": "full"},
request_id="edit-2",
)
assert len(analyzer.requests) == 1
- assert first.document.etag != document._record.etag
- assert first.cells[0].code == "import marimo as mo"
+ # The analyzer holds the revision it was given.
+ assert first is document
+ assert first.etag != notebook.document.etag
+ assert next(iter(first)).code == "import marimo as mo"
log.clear()
result.set_result(first_analysis)
latest, result = await analyzer.next_request()
assert names(log) == []
- assert latest == document.snapshot()
+ assert latest is notebook.document
- result.set_result(cell_analyses(document))
+ result.set_result(cell_analyses(latest))
await asyncio.sleep(0)
assert names(log) == ["analysis"]
assert request_ids(log) == ["edit-2"]
assert notebook.analysis is not None
- assert notebook.analysis.document_etag == latest.document.etag
+ assert notebook.analysis.document_etag == latest.etag
async def test_an_edit_is_analyzed_under_its_request_key(
self, host: Host, log: list[Event]
) -> None:
host.update_project(project())
analyzer = ScriptedAnalyzer()
- document = Document(NOTEBOOK, fixture_cells(), {})
+ document = Document(fixture_cells(), {})
notebook = await add_notebook(
host,
record(),
@@ -581,11 +682,11 @@ class TestAnalysis:
log.clear()
notebook.edit([put("c9", "z = 1", None)], request_id="edit-1")
- snapshot, result = await analyzer.next_request()
- assert snapshot == document.snapshot()
- assert [c.id for c in snapshot.cells] == ["c1", "c3", "k7f2", "c9"]
+ analyzed, result = await analyzer.next_request()
+ assert analyzed is notebook.document
+ assert ids(analyzed) == ["c1", "c3", "k7f2", "c9"]
- result.set_result(cell_analyses(document))
+ result.set_result(cell_analyses(analyzed))
await asyncio.sleep(0)
assert names(log) == ["cell", "document", "analysis"]
assert request_ids(log) == ["edit-1"] * 3
@@ -595,7 +696,7 @@ class TestAnalysis:
) -> None:
host.update_project(project())
analyzer = ScriptedAnalyzer()
- document = Document(NOTEBOOK, fixture_cells(), {})
+ document = Document(fixture_cells(), {})
notebook = await add_notebook(
host,
record(),
@@ -606,14 +707,14 @@ class TestAnalysis:
first, result = await analyzer.next_request()
result.set_result(cell_analyses(document))
await asyncio.sleep(0)
- notebook.replace([CellSource("c1", "1")], {})
+ notebook.replace([cell("c1", "1")], {})
_, result = await analyzer.next_request()
assert notebook.analysis is not None
assert (
notebook.analysis.document_etag
- == first.document.etag
- != document._record.etag
+ == first.etag
+ != notebook.document.etag
)
assert names(host.events(notebook_id="n1")) == [
"notebook",
@@ -622,7 +723,7 @@ class TestAnalysis:
"analysis",
"ready",
]
- result.set_result(cell_analyses(document))
+ result.set_result(cell_analyses(notebook.document))
await asyncio.sleep(0)
@pytest.mark.parametrize("edit_while_running", [False, True])
@@ -631,7 +732,7 @@ class TestAnalysis:
) -> None:
host.update_project(project())
analyzer = ScriptedAnalyzer()
- document = Document(NOTEBOOK, fixture_cells(), {})
+ document = Document(fixture_cells(), {})
notebook = await add_notebook(
host,
record(),
@@ -641,18 +742,18 @@ class TestAnalysis:
)
_, result = await analyzer.next_request()
if edit_while_running:
- notebook.replace([CellSource("c1", "1")], {})
+ notebook.replace([cell("c1", "1")], {})
log.clear()
result.set_exception(RuntimeError("compiler failed"))
await asyncio.sleep(0)
assert names(log) == []
assert notebook.analysis is None
if not edit_while_running:
- notebook.replace([CellSource("c1", "1")], {})
- snapshot, result = await analyzer.next_request()
- assert snapshot == document.snapshot()
+ notebook.replace([cell("c1", "1")], {})
+ analyzed, result = await analyzer.next_request()
+ assert analyzed is notebook.document
log.clear()
- result.set_result(cell_analyses(document))
+ result.set_result(cell_analyses(analyzed))
await asyncio.sleep(0)
assert names(log) == ["analysis"]
@@ -661,10 +762,10 @@ class TestAnalysis:
) -> None:
started, cancelled = asyncio.Event(), asyncio.Event()
result = asyncio.get_running_loop().create_future()
- document = Document(NOTEBOOK, fixture_cells(), {})
+ document = Document(fixture_cells(), {})
class Analyzer:
- async def analyze(self, _snapshot):
+ async def analyze(self, _document):
started.set()
try:
return await asyncio.shield(result)
@@ -676,10 +777,12 @@ class TestAnalysis:
host.add_notebook(
record(),
lambda _, sink: Notebook(
+ NOTEBOOK,
document,
Executions(),
ScriptedBackend(),
sink,
+ saved_etag=document.etag,
analyzer=Analyzer(),
),
)
@@ -692,17 +795,3 @@ class TestAnalysis:
await asyncio.sleep(0)
assert names(log) == []
assert "n1" not in host.notebooks
-
-
-def test_snapshot_preserves_order_metadata_and_nested_configuration() -> None:
- document = Document(NOTEBOOK, fixture_cells(), {"nested": {"items": [1]}})
- snapshot = document.snapshot()
- assert snapshot.cells == tuple(document)
- assert snapshot.document == document._record
- document._record.app_config["nested"]["items"].append(2)
- document.replace([CellSource("c1", "42", name="renamed")], {})
- assert snapshot.document.app_config == {"nested": {"items": [1]}}
- assert snapshot.cells[0].code == "import marimo as mo"
- assert snapshot.cells[-1].config == HIDDEN
- snapshot.document.app_config["another"] = True
- assert document._record.app_config == {}
diff --git a/tests/_server/host/test_host_analysis.py b/tests/_server/host/test_host_analysis.py
index 3651ccdee9..e5e502f967 100644
--- a/tests/_server/host/test_host_analysis.py
+++ b/tests/_server/host/test_host_analysis.py
@@ -12,17 +12,16 @@ import pytest
from marimo._ast.cell import CellImpl
from marimo._ast.compiler import compile_cell
from marimo._core import protocol
-from marimo._core.document import CellSource, Document, DocumentSnapshot
+from marimo._core.document import Document, DocumentCell
from marimo._server.host.analysis import CellAnalyzer, HostAnalyzer
from marimo._types.ids import CellId_t
-def snapshot(codes: dict[str, str]) -> DocumentSnapshot:
+def snapshot(codes: dict[str, str]) -> Document:
return Document(
- protocol.NotebookId("n1"),
- [CellSource(cid, code) for cid, code in codes.items()],
+ [DocumentCell(cid, code) for cid, code in codes.items()],
{},
- ).snapshot()
+ )
def analyze(
@@ -161,38 +160,41 @@ def test_compilation_cache_uses_identity_and_code_hash(
monkeypatch.setattr("marimo._server.host.analysis.compile_cell", compiler)
analyzer = CellAnalyzer()
document = Document(
- protocol.NotebookId("n1"),
[
- CellSource("a", "x = 1"),
- CellSource("b", "y = x"),
- CellSource("bad", "def (:"),
+ DocumentCell("a", "x = 1"),
+ DocumentCell("b", "y = x"),
+ DocumentCell("bad", "def (:"),
],
{},
)
- analyzer(document.snapshot())
+ analyzer(document)
assert compiler.call_count == 3
# Names, configuration, and order are visible without recompiling code.
- document.replace(
+ document, _ = document.replace(
[
- CellSource("b", "y = x", name="renamed"),
- CellSource("a", "x = 1"),
- CellSource("bad", "def (:"),
+ DocumentCell("b", "y = x", name="renamed"),
+ DocumentCell("a", "x = 1"),
+ DocumentCell("bad", "def (:"),
],
{"width": "full"},
)
- analyzer(document.snapshot())
+ analyzer(document)
assert compiler.call_count == 3
# An unchanged cell loses its reference when its provider changes.
- document.replace([CellSource("a", "z = 1"), CellSource("b", "y = x")], {})
- assert analyzer(document.snapshot())[protocol.CellId("b")].refs == ()
+ document, _ = document.replace(
+ [DocumentCell("a", "z = 1"), DocumentCell("b", "y = x")], {}
+ )
+ assert analyzer(document)[protocol.CellId("b")].refs == ()
assert compiler.call_count == 4
- document.replace([CellSource("b", "y = x")], {})
- analyzer(document.snapshot())
- document.replace([CellSource("a", "z = 1"), CellSource("c", "y = x")], {})
- analyzer(document.snapshot())
+ document, _ = document.replace([DocumentCell("b", "y = x")], {})
+ analyzer(document)
+ document, _ = document.replace(
+ [DocumentCell("a", "z = 1"), DocumentCell("c", "y = x")], {}
+ )
+ analyzer(document)
assert compiler.call_count == 6
diff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.py
index 72edbdc281..0a069e1f06 100644
--- a/tests/_server/host/test_host_api.py
+++ b/tests/_server/host/test_host_api.py
@@ -1749,8 +1749,9 @@ async def test_save_writes_the_file_and_reports_the_saved_revision(
async def test_edits_during_a_save_remain_unsaved(
harness: Harness, monkeypatch: pytest.MonkeyPatch
) -> None:
- document = (await harness.host.notebook(harness.notebook_id)).document
- written = document._record.etag
+ notebook = await harness.host.notebook(harness.notebook_id)
+ document = notebook.document
+ written = document.etag
started = asyncio.Event()
release = threading.Event()
loop = asyncio.get_running_loop()
diff --git a/tests/_server/host/test_host_bridge.py b/tests/_server/host/test_host_bridge.py
index 84eafe940b..ab8868743e 100644
--- a/tests/_server/host/test_host_bridge.py
+++ b/tests/_server/host/test_host_bridge.py
@@ -28,7 +28,7 @@ if TYPE_CHECKING:
from pathlib import Path
from typing import Any
- from marimo._core.document import CellSource
+ from marimo._core.document import DocumentCell
from marimo._session.consumer import SessionConsumer
@@ -80,15 +80,16 @@ async def test_an_adopted_document_is_saved_as_far_as_the_file_goes(
for name in ("saved.py", "edited.py"):
record = bridge.index.notebook_for(str(tmp_path / name))
assert record is not None
- document = (await bridge.host.notebook(record.id)).document
- assert document is not None
- documents[name] = document._record
+ notebook = await bridge.host.notebook(record.id)
+ documents[name] = (notebook.saved_etag, notebook.document.etag)
# A session showing the file as it is on disk is saved.
- assert documents["saved.py"].saved_etag == documents["saved.py"].etag
+ saved, current = documents["saved.py"]
+ assert saved == current
# One with an edit the file lacks is not, and names the file's revision.
- assert documents["edited.py"].saved_etag != documents["edited.py"].etag
- assert documents["edited.py"].saved_etag == documents["saved.py"].etag
+ saved, current = documents["edited.py"]
+ assert saved != current
+ assert saved == documents["saved.py"][1]
bridge.close()
@@ -143,7 +144,7 @@ async def test_delete_during_adoption_preserves_the_file_and_session(
async def paused_load(
file: Path,
- ) -> tuple[list[CellSource], dict[str, Any]] | None:
+ ) -> tuple[list[DocumentCell], dict[str, Any]] | None:
started.set()
await release.wait()
return await load(file)
@@ -402,8 +403,9 @@ async def test_editor_transactions_reach_the_host_document(
bridge.host.subscribe(events.append, notebook_id=record.id)
# The document comes from the session, ids included.
- document = (await bridge.host.notebook(record.id)).document
- assert document.order == ["Hbol"]
+ notebook = await bridge.host.notebook(record.id)
+ document = notebook.document
+ assert [c.id for c in document] == ["Hbol"]
# A frontend edit reaches the host document, and the app config as
# the session reports it comes along.
@@ -419,10 +421,10 @@ async def test_editor_transactions_reach_the_host_document(
NotebookDocumentTransactionNotification(transaction=applied)
)
- cell = document.cell("Hbol")
+ cell = notebook.document.cell("Hbol")
assert cell is not None
assert cell.code == "x = 2"
- assert document._record.app_config == {"width": "full"}
+ assert notebook.document.app_config == {"width": "full"}
assert names(events)[-2:] == ["cell", "document"]
bridge.close()
@@ -447,7 +449,8 @@ async def test_host_edits_reach_the_session_as_one_transaction(
await bridge.open()
record = bridge.index.notebook_for(str(tmp_path / "a.py"))
assert record is not None
- document = (await bridge.host.notebook(record.id)).document
+ notebook = await bridge.host.notebook(record.id)
+ document = notebook.document
events: list[Event] = []
bridge.host.subscribe(events.append, notebook_id=record.id)
@@ -471,7 +474,7 @@ async def test_host_edits_reach_the_session_as_one_transaction(
assert notification.transaction.source == "host"
# The backend saw its own edit come back and mirrored nothing new.
assert names(events) == ["cell", "document"]
- assert document._record.etag == response.document.etag
+ assert notebook.document.etag == response.document.etag
assert "y = x" not in (tmp_path / "a.py").read_text()
bridge.close()
@@ -510,9 +513,8 @@ async def test_edit_response_includes_app_config_mirrored_from_the_session(
request_id="edit-1",
)
- current = notebook.document.snapshot().document
- assert current.app_config == {"width": "full"}
- assert response.document == current
+ assert response.document.app_config == {"width": "full"}
+ assert response.document.etag == notebook.document.etag
finally:
bridge.close()
@@ -529,7 +531,8 @@ async def test_a_new_session_replaces_a_read_without_host_edits(
await bridge.open()
record = bridge.index.notebook_for(str(path))
assert record is not None
- document = (await bridge.host.notebook(record.id)).document
+ notebook = await bridge.host.notebook(record.id)
+ document = notebook.document
events: list[Event] = []
bridge.host.subscribe(events.append, notebook_id=record.id)
@@ -539,8 +542,8 @@ async def test_a_new_session_replaces_a_read_without_host_edits(
session.document = AppFileManager(str(path)).app.cell_manager.document
await manager.event_bus.emit_session_created(session) # type: ignore[arg-type]
- assert [cell.code for cell in document] == ["x = 2"]
- assert document._record.saved_etag == document._record.etag
+ assert [cell.code for cell in notebook.document] == ["x = 2"]
+ assert notebook.saved_etag == notebook.document.etag
assert names(events)[-3:] == ["cell", "document", "runtime"]
assert session.notifications == []
bridge.close()
@@ -563,7 +566,8 @@ async def test_a_new_session_adopts_unsaved_host_edits(
await bridge.open()
record = bridge.index.notebook_for(str(tmp_path / "a.py"))
assert record is not None
- document = (await bridge.host.notebook(record.id)).document
+ notebook = await bridge.host.notebook(record.id)
+ document = notebook.document
session = FakeSession(str(tmp_path / "a.py"))
session.document = NotebookDocument(editor_cell(c) for c in document)
await bridge.edit(
@@ -582,9 +586,9 @@ async def test_a_new_session_adopts_unsaved_host_edits(
await manager.event_bus.emit_session_created(session) # type: ignore[arg-type]
assert [(c.id, c.code) for c in session.document.cells] == [
- (c.id, c.code) for c in document
+ (c.id, c.code) for c in notebook.document
]
- assert document._record.saved_etag != document._record.etag
+ assert notebook.saved_etag != notebook.document.etag
assert "unsaved" not in (tmp_path / "a.py").read_text()
bridge.close()
@@ -689,7 +693,8 @@ async def test_save_writes_the_cells_and_keeps_the_app_config(
await bridge.open()
record = bridge.index.notebook_for(str(path))
assert record is not None
- document = (await bridge.host.notebook(record.id)).document
+ notebook = await bridge.host.notebook(record.id)
+ document = notebook.document
(cell,) = document
events: list[Event] = []
bridge.host.subscribe(events.append, notebook_id=record.id)
@@ -734,9 +739,10 @@ async def test_saving_keeps_an_edit_made_while_the_file_is_written(
await bridge.open()
record = bridge.index.notebook_for(str(path))
assert record is not None
- document = (await bridge.host.notebook(record.id)).document
+ notebook = await bridge.host.notebook(record.id)
+ document = notebook.document
(cell,) = document
- written = document._record.etag
+ written = notebook.document.etag
started = asyncio.Event()
release = threading.Event()
@@ -764,7 +770,7 @@ async def test_saving_keeps_an_edit_made_while_the_file_is_written(
# The file has the snapshot; the host keeps the edit, unsaved.
assert saved.document.etag == edited.document.etag
assert saved.document.saved_etag == written
- assert document._record.saved_etag != document._record.etag
+ assert notebook.saved_etag != notebook.document.etag
assert "x = 1" in path.read_text()
assert "x = 2" not in path.read_text()
bridge.close()
@@ -786,7 +792,8 @@ async def test_save_with_a_session_writes_through_the_editors_file_manager(
await bridge.open()
record = bridge.index.notebook_for(str(path))
assert record is not None
- document = (await bridge.host.notebook(record.id)).document
+ notebook = await bridge.host.notebook(record.id)
+ document = notebook.document
(cell,) = document
# The editor wrote once, so its manager remembers what is on disk.
session.app_file_manager.save_from_cells(list(session.document.cells))
@@ -820,7 +827,7 @@ async def test_the_editor_saving_marks_the_host_document_saved(
manager: FakeManager, tmp_path: Path
) -> None:
from marimo._ast.cell import CellConfig
- from marimo._core.document import revision
+ from marimo._core.document import Document
from marimo._messaging.notebook import NotebookCell
from marimo._server.host.document import from_file_manager
from marimo._session.notebook import AppFileManager
@@ -833,23 +840,24 @@ async def test_the_editor_saving_marks_the_host_document_saved(
await bridge.open()
record = bridge.index.notebook_for(str(path))
assert record is not None
- document = (await bridge.host.notebook(record.id)).document
+ notebook = await bridge.host.notebook(record.id)
+ document = notebook.document
session = FakeSession(str(path))
session.app_file_manager = AppFileManager(str(path))
session.document = session.app_file_manager.app.cell_manager.document
manager.sessions["browser-1"] = session
await manager.event_bus.emit_session_created(session) # type: ignore[arg-type]
(cell,) = session.document.cells
- before = document._record.etag
+ before = notebook.document.etag
# The editor writes new content the host has not mirrored yet.
session.app_file_manager.save_from_cells(
[NotebookCell(CellId_t(cell.id), "x = 2", cell.name, CellConfig())]
)
- written = revision(*from_file_manager(session.app_file_manager))
- assert document._record.saved_etag == written
- assert document._record.etag == before != written
+ written = Document(*from_file_manager(session.app_file_manager)).etag
+ assert notebook.saved_etag == written
+ assert notebook.document.etag == before != written
# Once the session goes away, its writes are no longer the host's,
# and the file as the editor left it is what the host compares to.
@@ -879,7 +887,7 @@ async def test_save_refuses_to_overwrite_when_the_file_cannot_be_read(
record = bridge.index.notebook_for(str(path))
assert record is not None
notebook = await bridge.host.notebook(record.id)
- before = notebook.document.snapshot()
+ before = notebook.document
external = NOTEBOOK.replace("x = 1", "x = 2")
path.write_text(external)
@@ -891,7 +899,7 @@ async def test_save_refuses_to_overwrite_when_the_file_cannot_be_read(
with pytest.raises(Conflict, match="could not be read"):
await bridge.save(record.id, if_match=None, request_id="save-1")
assert path.read_text() == external
- assert notebook.document.snapshot() == before
+ assert notebook.document == before
finally:
bridge.close()
@@ -938,7 +946,8 @@ async def test_reloading_refuses_to_drop_an_edit_made_while_reading(
await bridge.open()
record = bridge.index.notebook_for(str(path))
assert record is not None
- document = (await bridge.host.notebook(record.id)).document
+ notebook = await bridge.host.notebook(record.id)
+ document = notebook.document
(cell,) = document
path.write_text(NOTEBOOK.replace("x = 1", "x = 2"))
@@ -972,5 +981,5 @@ async def test_reloading_refuses_to_drop_an_edit_made_while_reading(
with pytest.raises(EditConflict) as conflict:
await asyncio.wait_for(reloading, 5)
assert conflict.value.document == edited.document
- assert document.cell(cell.id).code == "x = 3" # type: ignore[union-attr]
+ assert notebook.document.cell(cell.id).code == "x = 3" # type: ignore[union-attr]
bridge.close()
diff --git a/tests/_server/host/test_host_document.py b/tests/_server/host/test_host_document.py
index f744d575a0..93082aa28b 100644
--- a/tests/_server/host/test_host_document.py
+++ b/tests/_server/host/test_host_document.py
@@ -7,7 +7,7 @@ import pytest
from marimo._ast.cell import CellConfig
from marimo._core import protocol
-from marimo._core.document import CellSource, Document
+from marimo._core.document import Document, DocumentCell
from marimo._messaging.notebook import (
NotebookCell,
NotebookDocument,
@@ -28,7 +28,7 @@ def test_deleting_all_cells_broadcasts_the_final_order() -> None:
session.document = NotebookDocument(
[NotebookCell(CellId_t("a"), "x = 1", "_", CellConfig())]
)
- document = Document(protocol.NotebookId("nb"), [], {})
+ document = Document([], {})
apply_to_session(session, document) # type: ignore[arg-type]
@@ -46,9 +46,7 @@ async def test_enabling_an_edited_cell_does_not_run_old_code() -> None:
session.document = NotebookDocument(
[NotebookCell(cell_id, old_code, "_", CellConfig(disabled=True))]
)
- document = Document(
- protocol.NotebookId("nb"), [CellSource(cell_id, new_code)], {}
- )
+ document = Document([DocumentCell(cell_id, new_code)], {})
with mocked_kernel_session(
configs={cell_id: CellConfig(disabled=True)}
@@ -84,7 +82,7 @@ async def test_deleted_or_disabled_cells_do_not_run_during_an_edit(
[]
if delete_dependent
else [
- CellSource(
+ DocumentCell(
second,
code,
config=protocol.CellConfig(
@@ -96,7 +94,7 @@ async def test_deleted_or_disabled_cells_do_not_run_during_an_edit(
)
]
)
- document = Document(protocol.NotebookId("nb"), cells, {})
+ document = Document(cells, {})
with mocked_kernel_session() as runtime:
await runtime.kernel.run(