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.

Serve a notebook's document from `marimo edit` without a kernel (#11217)

Trevor Manzbced101e3d3e
diff --git a/marimo/_core/__init__.py b/marimo/_core/__init__.py
index 0c91eb2a3c..41800b052c 100644
--- a/marimo/_core/__init__.py
+++ b/marimo/_core/__init__.py
@@ -1,6 +1,7 @@
# Copyright 2026 Marimo. All rights reserved.
-"""Types and state for the marimo host protocol.
+"""State and commands for marimo hosts.
-Hosts track projects and notebooks. Notebooks track runtimes, client
-attachments, and runs. State changes are published as events.
+A host catalogs notebooks and retains run history. A notebook brings
+its document, execution results, and runtime together. State changes
+are published as events described in `protocols/host/spec.md`.
"""
diff --git a/marimo/_core/backend.py b/marimo/_core/backend.py
index 92241ca044..1b90e43c2a 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 = host.add_notebook(record, backend)
+notebook = Notebook(document, Executions(), backend, sink)
runtime, _ = notebook.start() # Calls backend.start(runtime.id).
# The backend reports on that runtime through Notebook.observe.
@@ -134,7 +134,7 @@ class Produced:
@dataclass(frozen=True)
class Concluded:
- """An execution's current outcome; final once the execution is completed."""
+ """An execution outcome, final when the execution completes."""
execution_id: protocol.ExecutionId
outcome: protocol.Outcome
diff --git a/marimo/_core/document.py b/marimo/_core/document.py
new file mode 100644
index 0000000000..d1c9256333
--- /dev/null
+++ b/marimo/_core/document.py
@@ -0,0 +1,286 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Notebook cells, order, configuration, and revisions."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Callable, Mapping
+from copy import deepcopy
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal
+
+from msgspec.structs import replace
+
+from marimo._core import protocol
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator, Sequence
+
+Analyzer = Callable[[Mapping[str, str]], Mapping[str, protocol.Analysis]]
+"""Derives every cell's analysis from the cells' code, keyed by id in document order."""
+
+Policy = Literal["autorun", "lazy"]
+
+
+def etag(text: str) -> protocol.Etag:
+ """The first 16 hex characters of SHA-256 over the UTF-8 text."""
+ return protocol.Etag(hashlib.sha256(text.encode()).hexdigest()[:16])
+
+
+def code_hash(code: str) -> protocol.Etag:
+ return etag(code)
+
+
+def cell_etag(
+ code_hash: protocol.Etag, name: str, config: protocol.CellConfig
+) -> protocol.Etag:
+ """Over the code hash, the name, and the config values as JSON scalars."""
+ values = (
+ config.column,
+ config.disabled,
+ config.hide_code,
+ config.expand_output,
+ )
+ return etag("\n".join([code_hash, name, *(json.dumps(v) for v in values)]))
+
+
+def order_etag(order: Sequence[str]) -> protocol.Etag:
+ return etag(json.dumps(order, separators=(",", ":"), ensure_ascii=False))
+
+
+def app_config_etag(app_config: Mapping[str, Any]) -> protocol.Etag:
+ """Over the app config as canonical JSON."""
+ return etag(
+ json.dumps(
+ app_config,
+ sort_keys=True,
+ separators=(",", ":"),
+ ensure_ascii=False,
+ )
+ )
+
+
+def document_etag(
+ order_etag: protocol.Etag,
+ app_config_etag: protocol.Etag,
+ cell_etags: Sequence[protocol.Etag],
+) -> protocol.Etag:
+ return etag("\n".join([order_etag, app_config_etag, *cell_etags]))
+
+
+def default_config() -> protocol.CellConfig:
+ return protocol.CellConfig(
+ column=None, disabled=False, hide_code=False, expand_output=False
+ )
+
+
+@dataclass(frozen=True)
+class CellSource:
+ """Cell source and metadata supplied by a file or editor."""
+
+ id: str
+ code: str
+ name: str = "_"
+ config: protocol.CellConfig = field(default_factory=default_config)
+
+
+@dataclass(frozen=True)
+class Changed:
+ """Changed cells, removed cell IDs, and the updated document."""
+
+ cells: list[protocol.Cell]
+ """New cells, and cells whose etag or analysis changed."""
+ removed: list[str]
+ """Ids of cells that no longer exist."""
+ document: protocol.Document | None
+ """The document, when any of its fields changed."""
+
+ def __bool__(self) -> bool:
+ return bool(self.cells or self.removed or self.document)
+
+
+class Document:
+ """A notebook document with content-derived revisions.
+
+ Cell source uses newline line endings. Analysis covers all cells.
+ """
+
+ def __init__(
+ self,
+ notebook_id: protocol.NotebookId,
+ cells: Sequence[CellSource],
+ app_config: Mapping[str, Any],
+ *,
+ policy: Policy = "autorun",
+ analyzer: Analyzer | None = None,
+ saved: bool = True,
+ ) -> None:
+ self._id = notebook_id
+ self._analyzer = analyzer
+ self._policy: Policy = policy
+ 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()
+
+ @classmethod
+ def from_records(
+ cls,
+ document: protocol.Document,
+ cells: Sequence[protocol.Cell],
+ *,
+ analyzer: Analyzer | None = None,
+ ) -> Document:
+ """Restore a document from its protocol records.
+
+ Cell identities, order, and revisions must agree. Analysis is kept
+ unless an analyzer is supplied. The saved revision is preserved.
+ """
+ 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)
+ or set(document.order) != set(by_id)
+ ):
+ raise ValueError(
+ "document order must contain every cell exactly once"
+ )
+ if any(cell.notebook_id != document.id for cell in cells):
+ raise ValueError("cells must belong to the document")
+ restored = cls(
+ document.id,
+ [
+ CellSource(cell.id, cell.code, cell.name, cell.config)
+ for cell in (by_id[cell_id] for cell_id in document.order)
+ ],
+ document.app_config,
+ policy=document.policy,
+ analyzer=analyzer,
+ saved=False,
+ )
+ for cell in restored:
+ original = by_id[cell.id]
+ if (
+ cell.etag != original.etag
+ or cell.code_hash != original.code_hash
+ ):
+ raise ValueError("cell revisions must match their content")
+ if analyzer is None:
+ restored._cells[cell.id] = replace(
+ cell, analysis=original.analysis
+ )
+ current = restored._record
+ if (
+ current.etag != document.etag
+ or current.order_etag != document.order_etag
+ or current.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
+
+ @property
+ def notebook_id(self) -> protocol.NotebookId:
+ """The notebook this document belongs to."""
+ return self._id
+
+ @property
+ def _record(self) -> protocol.Document:
+ assert self._document is not None
+ return self._document
+
+ 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 order(self) -> list[str]:
+ return list(self._order)
+
+ def cell(self, cell_id: str) -> protocol.Cell | None:
+ return self._cells.get(cell_id)
+
+ def replace(
+ self, cells: Sequence[CellSource], app_config: Mapping[str, Any]
+ ) -> Changed:
+ """Replace cells and configuration and return what changed.
+
+ 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}
+ if self._analyzer is not None:
+ analyses = self._analyzer(
+ {cell_id: built[cell_id].code for cell_id in order}
+ )
+ for cell_id in order:
+ analysis = analyses.get(cell_id)
+ if analysis is not None:
+ built[cell_id] = replace(built[cell_id], analysis=analysis)
+ changed = [
+ built[cell_id]
+ for cell_id in order
+ if self._cells.get(cell_id) != built[cell_id]
+ ]
+ 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())
+
+ 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 set_policy(self, policy: Policy) -> protocol.Document | None:
+ self._policy = policy
+ return self._refresh()
+
+ def _build(self, source: CellSource) -> protocol.Cell:
+ code = source.code.replace("\r\n", "\n").replace("\r", "\n")
+ 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,
+ analysis=None,
+ )
+
+ 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(
+ id=self._id,
+ order=tuple(protocol.CellId(c) for c in self._order),
+ app_config=dict(self._app_config),
+ policy=self._policy,
+ 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
diff --git a/marimo/_core/executions.py b/marimo/_core/executions.py
index 547c2cdab2..cf3ca9d34f 100644
--- a/marimo/_core/executions.py
+++ b/marimo/_core/executions.py
@@ -5,7 +5,7 @@ from __future__ import annotations
from copy import deepcopy
from dataclasses import dataclass, field
-from typing import Literal
+from typing import TYPE_CHECKING, Literal
from msgspec.structs import replace
@@ -13,6 +13,9 @@ from marimo._core import backend as be, protocol
from marimo._core.errors import NoRuntime
from marimo._core.stream import utcnow
+if TYPE_CHECKING:
+ from collections.abc import Iterable, Mapping
+
@dataclass(frozen=True)
class CellExecution:
@@ -84,6 +87,57 @@ class Executions:
self._results: dict[protocol.ExecutionId, _Result] = {}
self._cells: dict[protocol.CellId, protocol.ExecutionId] = {}
+ @classmethod
+ def restore(
+ cls,
+ executions: Mapping[protocol.CellId, CellExecution],
+ *,
+ cells: Iterable[protocol.Cell],
+ ) -> Executions:
+ """Restore completed executions for cells in the document.
+
+ Execution and output IDs must be unique. Each output must belong
+ to its containing execution.
+ """
+ known = {cell.id for cell in cells}
+ restored = cls()
+ output_ids: set[protocol.ItemId] = set()
+ for cell_id, retained in deepcopy(dict(executions)).items():
+ execution = retained.execution
+ if execution.cell_id != cell_id:
+ raise ValueError(
+ "results must belong to their containing cell"
+ )
+ if cell_id not in known:
+ raise ValueError(
+ f"result for cell {cell_id} not in the document"
+ )
+ outputs = sorted(retained.outputs, key=lambda item: item.seq)
+ if execution.status != "completed":
+ raise ValueError(
+ "initial results must be completed executions"
+ )
+ if execution.outcome is None:
+ raise ValueError("initial results must have an outcome")
+ if execution.id in restored._results:
+ raise ValueError("initial execution ids must be unique")
+ if any(item.execution_id != execution.id for item in outputs):
+ raise ValueError(
+ "result outputs must belong to their execution"
+ )
+ if len({item.id for item in outputs}) != len(outputs):
+ raise ValueError("result output ids must be unique")
+ if output_ids.intersection(item.id for item in outputs):
+ raise ValueError(
+ "result output ids must be unique across cells"
+ )
+ output_ids.update(item.id for item in outputs)
+ restored._results[execution.id] = _Result(
+ execution, {item.id: item for item in outputs}
+ )
+ restored._cells[cell_id] = execution.id
+ return restored
+
# ---- reads ---------------------------------------------------------
def current(self, cell_id: protocol.CellId) -> CellExecution | None:
@@ -160,6 +214,19 @@ class Executions:
"""Stop tracking a released run."""
del self._runs[run_id]
+ def remove_cell(self, cell_id: protocol.CellId) -> list[Change]:
+ """Remove a deleted cell's result.
+
+ An active execution stays until its run completes.
+ """
+ execution_id = self._cells.get(cell_id)
+ if execution_id is None:
+ return []
+ if self._results[execution_id].execution.status == "completed":
+ return self._retire_execution(execution_id)
+ self._cells.pop(cell_id)
+ return []
+
def observe(
self, msg: be.Message, runtime: protocol.Runtime | None
) -> list[Change]:
@@ -374,21 +441,26 @@ class Executions:
result = self._results.get(execution.id)
if result is None:
self._results[execution.id] = _Result(execution)
+ if execution.cell_id is not None:
+ self._cells[execution.cell_id] = execution.id
else:
result.execution = execution
- if execution.cell_id is not None:
- self._cells[execution.cell_id] = execution.id
if execution.run_id is not None:
if (tracked := self._runs.get(execution.run_id)) is not None:
tracked.executions.add(execution.id)
return execution
- def _finish_run(self, tracked: _Run) -> list[Released]:
+ def _finish_run(self, tracked: _Run) -> list[Change]:
"""Release completed work that no cell retains."""
+ changes: list[Change] = []
for execution_id in list(tracked.executions):
- if self._results[execution_id].execution.cell_id is None:
+ execution = self._results[execution_id].execution
+ if execution.cell_id is None:
self._forget_result(execution_id)
- return self._prune_run(tracked)
+ elif self._cells.get(execution.cell_id) != execution_id:
+ changes.extend(self._remove_execution(execution_id))
+ changes.extend(self._prune_run(tracked))
+ return changes
def _prune_run(self, tracked: _Run) -> list[Released]:
if tracked.run.status != "completed" or tracked.executions:
@@ -436,7 +508,10 @@ class Executions:
def _forget_result(self, execution_id: protocol.ExecutionId) -> None:
result = self._results.pop(execution_id)
- if result.execution.cell_id is not None:
+ if (
+ result.execution.cell_id is not None
+ and self._cells.get(result.execution.cell_id) == execution_id
+ ):
del self._cells[result.execution.cell_id]
if result.execution.run_id is not None:
if (
diff --git a/marimo/_core/host.py b/marimo/_core/host.py
index e8434a47bb..4a66957d33 100644
--- a/marimo/_core/host.py
+++ b/marimo/_core/host.py
@@ -3,30 +3,39 @@
from __future__ import annotations
-from collections.abc import Mapping
+import asyncio
+import inspect
+from collections.abc import Awaitable, Callable, Mapping
from copy import deepcopy
from dataclasses import dataclass
from time import monotonic
from typing import TYPE_CHECKING
from marimo._core import protocol
-from marimo._core.backend import Backend
from marimo._core.errors import NotFound
from marimo._core.notebook import Notebook
from marimo._core.run_log import RetentionPolicy, RunLog
from marimo._core.stream import Event, Listener, Sink, Stream, message
if TYPE_CHECKING:
- from collections.abc import Callable, Collection, Iterator, Sequence
+ from collections.abc import Collection, Iterator, Sequence
from contextlib import AbstractContextManager
+NotebookInitializer = Callable[
+ [protocol.Notebook, Sink], Notebook | Awaitable[Notebook]
+]
+
+
@dataclass
-class _Entry:
- """A notebook and the run history kept for it."""
+class _NotebookEntry:
+ """A catalog entry, its run history, and the notebook once loaded."""
- notebook: Notebook
+ initialize: NotebookInitializer
log: RunLog
+ notebook: Notebook | None = None
+ task: asyncio.Task[Notebook] | None = None
+ sink: _NotebookSink | None = None
class _NotebookSink(Sink):
@@ -35,11 +44,15 @@ class _NotebookSink(Sink):
def __init__(self, stream: Stream, log: RunLog) -> None:
self._stream = stream
self._log = log
+ # Publish initial state only after the host accepts the notebook.
+ self.active = False
def deferred(self) -> AbstractContextManager[None]:
return self._stream.deferred()
def _append(self, event: Event) -> Event:
+ if not self.active:
+ return event
with self._stream.deferred():
removals = self._log.observe(event)
recorded = self._stream.append(event)
@@ -87,7 +100,7 @@ class Host:
# Lookups accept wire strings; stored objects carry branded IDs.
self._projects: dict[str, protocol.Project] = {}
self._records: dict[str, protocol.Notebook] = {}
- self._entries: dict[str, _Entry] = {}
+ self._entries: dict[str, _NotebookEntry] = {}
@property
def notebooks(self) -> Mapping[str, protocol.Notebook]:
@@ -110,27 +123,24 @@ class Host:
def add_notebook(
self,
record: protocol.Notebook,
- backend: Backend,
+ initialize: NotebookInitializer,
*,
request_id: str | None = None,
- ) -> Notebook:
- """Register a notebook and its backend."""
+ ) -> None:
+ """Register a notebook with its initializer."""
if record.id in self._records:
raise ValueError(f"notebook {record.id} is already in the catalog")
if record.project_id not in self._projects:
raise ValueError(
f"project {record.project_id} is not in the catalog"
)
- log = RunLog(lambda: self.clock())
- notebook = Notebook(
- record.id, backend, _NotebookSink(self._stream, log)
- )
self._records[record.id] = deepcopy(record)
- self._entries[record.id] = _Entry(notebook, log)
+ self._entries[record.id] = _NotebookEntry(
+ initialize, RunLog(lambda: self.clock())
+ )
self._stream.publish(
record, notebook_id=record.id, request_id=request_id
)
- return notebook
def update_notebook(
self, record: protocol.Notebook, *, request_id: str | None = None
@@ -153,14 +163,20 @@ class Host:
self, notebook_id: str, *, request_id: str | None = None
) -> None:
"""Remove a notebook, its runtime, attachments, and runs."""
- entry = self._entries.pop(notebook_id, None)
- if entry is None:
+ record = self._records.pop(notebook_id, None)
+ if record is None:
return
- record = self._records.pop(notebook_id)
+ entry = self._entries.pop(notebook_id)
+ if entry.task is not None:
+ entry.task.cancel()
+
with self._stream.deferred():
- entry.notebook._dispose(request_id=request_id)
+ if entry.notebook is not None:
+ entry.notebook._dispose(request_id=request_id)
for event in entry.log.clear():
self._stream.append(event)
+ if entry.sink is not None:
+ entry.sink.active = False
self._stream.remove(
"notebook",
record.id,
@@ -168,13 +184,71 @@ class Host:
request_id=request_id,
)
- def notebook(self, notebook_id: str) -> Notebook:
- """Return a notebook or raise `NotFound`."""
+ async def notebook(self, notebook_id: str) -> Notebook:
+ """Load a notebook on first access.
+
+ Concurrent callers share initialization. Failed loads can be retried.
+ Cancelling a caller leaves shared loading intact.
+ """
+ entry = self._entries.get(notebook_id)
+ if entry is None:
+ raise NotFound(f"no notebook {notebook_id}")
+ if entry.notebook is not None:
+ return entry.notebook
+ if entry.task is None:
+ entry.task = asyncio.create_task(
+ self._initialize(notebook_id, entry)
+ )
+ try:
+ return await asyncio.shield(entry.task)
+ except asyncio.CancelledError:
+ if self._entries.get(notebook_id) is not entry:
+ raise NotFound(f"no notebook {notebook_id}") from None
+ raise
+
+ def peek_notebook(self, notebook_id: str) -> Notebook | None:
+ """Return the notebook if loaded without initializing it."""
entry = self._entries.get(notebook_id)
if entry is None:
raise NotFound(f"no notebook {notebook_id}")
return entry.notebook
+ async def _initialize(
+ self, notebook_id: str, entry: _NotebookEntry
+ ) -> Notebook:
+ try:
+ sink = _NotebookSink(self._stream, entry.log)
+ result = entry.initialize(
+ deepcopy(self._records[notebook_id]), sink
+ )
+ notebook = await result if inspect.isawaitable(result) else result
+ if self._entries.get(notebook_id) is not entry:
+ raise NotFound(f"no notebook {notebook_id}")
+ if notebook.id != notebook_id:
+ raise ValueError(
+ "initialized notebook must match its catalog id"
+ )
+ entry.notebook = notebook
+
+ entry.sink = sink
+ sink.active = True
+ # The initial state joins the stream the way later changes do,
+ # so the run history sees every run from its first event.
+ with self._stream.deferred():
+ for event in notebook._snapshot():
+ assert event.kind is not None
+ body = getattr(event.data, event.kind)
+ sink.publish(
+ body,
+ notebook_id=notebook.id,
+ run_id=event.run_id,
+ )
+ if self._entries.get(notebook_id) is not entry:
+ raise NotFound(f"no notebook {notebook_id}")
+ return notebook
+ finally:
+ entry.task = None
+
def run(self, notebook_id: str, run_id: str) -> protocol.Run | None:
"""Return a run the host still retains, if any."""
entry = self._entries.get(notebook_id)
@@ -200,6 +274,8 @@ class Host:
Event("notebook", message(record), notebook_id=record.id)
)
entry = self._entries[record.id]
+ if entry.notebook is None:
+ continue
seen: set[tuple[str, str]] = set()
for event in [
*entry.notebook._snapshot(),
@@ -224,7 +300,11 @@ class Host:
A cursor requests the events after it. An unavailable cursor returns
`reset` and a snapshot.
"""
- scope = None if notebook_id is None else self.notebook(notebook_id).id
+ scope = None
+ if notebook_id is not None:
+ if notebook_id not in self._records:
+ raise NotFound(f"no notebook {notebook_id}")
+ scope = self._records[notebook_id].id
ready = Event("ready", id=self._stream.last_id)
if cursor is None:
events = self._snapshot(scope)
diff --git a/marimo/_core/notebook.py b/marimo/_core/notebook.py
index 82fad6444e..f44673fe15 100644
--- a/marimo/_core/notebook.py
+++ b/marimo/_core/notebook.py
@@ -3,6 +3,7 @@
from __future__ import annotations
+from dataclasses import dataclass
from typing import TYPE_CHECKING, Any
import msgspec
@@ -15,44 +16,74 @@ from marimo._core.ids import mint
from marimo._core.stream import Event, Kind, kind_of, message, utcnow
if TYPE_CHECKING:
- from collections.abc import Callable, Sequence
+ from collections.abc import Callable, Mapping, Sequence
- from marimo._core.executions import Change
+ from marimo._core.document import CellSource, Changed, Document
+ from marimo._core.executions import CellExecution, Change
from marimo._core.stream import Body, Sink
+@dataclass(frozen=True)
+class CellSnapshot:
+ """A cell and its retained execution, if any."""
+
+ cell: protocol.Cell
+ execution: CellExecution | None = None
+
+
+@dataclass(frozen=True)
+class NotebookSnapshot:
+ """A document and its cells with their completed executions.
+
+ Cells are in document order. Runtimes, attachments, and active work
+ are excluded. Restore with `Document.from_records` and
+ `Executions.restore` before constructing a notebook.
+ """
+
+ document: protocol.Document
+ cells: tuple[CellSnapshot, ...]
+
+
class Notebook:
- """A notebook with execution results, a runtime, and client attachments.
+ """A document, its execution results, and the runtime that produces them.
- Commands call the backend. Backend reports update state and reach
- the sink as notebook events. Change execution state through the
- notebook so each change reaches the sink.
+ 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.
"""
def __init__(
self,
- notebook_id: protocol.NotebookId,
+ document: Document,
+ executions: Executions,
backend: be.Backend,
sink: Sink,
) -> None:
- self._id = notebook_id
- self._backend = backend
- self._sink = sink
+ self._document = document
+ self._executions = executions
+ self.backend = backend
+ self.sink = sink
self._closed = False
self._runtime: protocol.Runtime | None = None
self._attachments: dict[str, protocol.Attachment] = {}
- self._executions = Executions()
self._replacement: protocol.Runtime | None = None
# Correlate runtime events with the pending start, stop, or restart.
self._runtime_request: str | None = None
+ @property
+ def document(self) -> Document:
+ """The document owned by this notebook; change it through the notebook."""
+ return self._document
+
@property
def executions(self) -> Executions:
+ """The execution results owned by this notebook."""
return self._executions
@property
def id(self) -> protocol.NotebookId:
- return self._id
+ return self.document.notebook_id
@property
def runtime(self) -> protocol.Runtime | None:
@@ -63,20 +94,56 @@ class Notebook:
if self._closed:
raise NotFound(f"no notebook {self.id}")
+ # ---- document ------------------------------------------------------
+
+ def replace(
+ self,
+ cells: Sequence[CellSource],
+ app_config: Mapping[str, object],
+ *,
+ request_id: str | None = None,
+ ) -> Changed:
+ """Replace the document and publish its changes."""
+ self._require_open()
+ changed = self.document.replace(cells, app_config)
+ self._publish_changed(changed, request_id)
+ return changed
+
+ def mark_saved(self, *, request_id: str | None = None) -> None:
+ """Mark the current document revision as saved."""
+ self._require_open()
+ document = self.document.mark_saved()
+ if document is not None:
+ self._publish(document, request_id)
+
+ def _publish_changed(
+ self, changed: Changed, request_id: str | None
+ ) -> None:
+ with self.sink.deferred():
+ for cell in changed.cells:
+ self._publish(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)
+
# ---- runtime -------------------------------------------------------
def start(
self, *, request_id: str | None = None
) -> tuple[protocol.Runtime, bool]:
"""Return the runtime and whether this call started it."""
- with self._sink.deferred():
+ with self.sink.deferred():
self._require_open()
if self._runtime is not None:
return self._runtime, False
runtime = self._new_runtime("starting", None, None)
self._runtime_request = request_id
self._set_runtime(runtime)
- self._backend.start(runtime.id)
+ self.backend.start(runtime.id)
return runtime, True
def stop(self, *, request_id: str | None = None) -> protocol.Runtime:
@@ -85,7 +152,7 @@ class Notebook:
The runtime stays until the backend reports its exit. A failed runtime
is removed immediately.
"""
- with self._sink.deferred():
+ with self.sink.deferred():
self._require_open()
runtime = self._require_runtime()
self._runtime_request = request_id
@@ -97,7 +164,7 @@ class Notebook:
if runtime.status == "failed":
self._end_runtime()
else:
- self._backend.stop(runtime.id)
+ self.backend.stop(runtime.id)
return terminating
def restart(self, *, request_id: str | None = None) -> protocol.Runtime:
@@ -105,7 +172,7 @@ class Notebook:
The replacement starts after the old runtime exits.
"""
- with self._sink.deferred():
+ with self.sink.deferred():
self._require_open()
runtime = self._require_runtime()
if runtime.status != "running":
@@ -117,7 +184,7 @@ class Notebook:
self._replacement = replacement
terminating = replace(runtime, status="terminating")
self._set_runtime(terminating)
- self._backend.stop(runtime.id)
+ self.backend.stop(runtime.id)
return replacement
# TODO: Remove once sessions start their runtime through `start`.
@@ -129,7 +196,7 @@ class Notebook:
Calls `attach` with a new runtime ID before delivering events.
"""
- with self._sink.deferred():
+ with self.sink.deferred():
self._require_open()
if self._runtime is not None:
if self._runtime.status != "failed":
@@ -166,7 +233,7 @@ class Notebook:
def run(self, code: str, *, request_id: str) -> protocol.Run:
"""Queue scratch code on a running, idle runtime."""
- with self._sink.deferred():
+ with self.sink.deferred():
self._require_open()
runtime = self._require_runtime()
if runtime.status != "running":
@@ -184,7 +251,7 @@ class Notebook:
completed_at=None,
)
self._apply(self.executions.begin(run, request_id))
- self._backend.run(run.id, code)
+ self.backend.run(run.id, code)
return run
def interrupt(self, run_id: str) -> protocol.Run:
@@ -195,7 +262,7 @@ class Notebook:
raise NotFound(f"notebook {self.id} has no run {run_id}.")
if run.status == "completed":
raise Conflict(f"run {run_id} has already ended.")
- self._backend.interrupt(run.id)
+ self.backend.interrupt(run.id)
return run
# ---- attachments ---------------------------------------------------
@@ -273,11 +340,11 @@ class Notebook:
if runtime.status == "terminating" and self._replacement is not None:
replacement, self._replacement = self._replacement, None
request_id = self._runtime_request
- with self._sink.deferred():
+ with self.sink.deferred():
self._end_runtime()
self._runtime_request = request_id
self._set_runtime(replacement)
- self._backend.start(replacement.id)
+ self.backend.start(replacement.id)
elif runtime.status == "terminating":
self._end_runtime()
else:
@@ -323,7 +390,7 @@ class Notebook:
def _snapshot(self) -> list[Event]:
"""Return current state as events in dependency order."""
- bodies: list[Body] = []
+ bodies: list[Body] = [*self.document, self.document._record]
if self._runtime is not None:
bodies.append(self._runtime)
bodies.extend(self._attachments.values())
@@ -361,7 +428,7 @@ class Notebook:
self._remove("runtime", runtime.id, request_id)
def _publish(self, body: Body, request_id: str | None) -> None:
- self._sink.publish(
+ self.sink.publish(
body,
notebook_id=self.id,
request_id=request_id,
@@ -373,7 +440,7 @@ class Notebook:
object_id: str,
request_id: str | None,
) -> None:
- self._sink.remove(
+ self.sink.remove(
kind,
object_id,
notebook_id=self.id,
@@ -383,16 +450,16 @@ class Notebook:
def _apply(self, changes: Sequence[Change]) -> None:
"""Publish changes and release completed runs."""
executions = self.executions
- with self._sink.deferred():
+ with self.sink.deferred():
for change in changes:
if isinstance(change, Released):
executions.release(change.run_id)
- self._backend.forget(change.run_id)
+ self.backend.forget(change.run_id)
continue
run_id = executions.run_id_of(change)
request_id = executions.request_id(run_id)
if isinstance(change, Removed):
- self._sink.remove(
+ self.sink.remove(
change.kind,
change.id,
notebook_id=self.id,
@@ -400,7 +467,7 @@ class Notebook:
request_id=request_id,
)
else:
- self._sink.publish(
+ self.sink.publish(
change,
notebook_id=self.id,
run_id=run_id,
diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.py
index a9bd562811..2a313322b9 100644
--- a/marimo/_core/protocol.py
+++ b/marimo/_core/protocol.py
@@ -798,7 +798,7 @@ class Document(Struct, frozen=True):
order_etag: Annotated[
Etag,
Meta(
- description="Identifies the order alone. Its text is the cell ids in order. Editing a cell does not change it."
+ description="Identifies the order alone. Its text is the cell IDs in order as a JSON array, with no whitespace and strings carrying only the escapes JSON requires. Editing a cell does not change it."
),
]
policy: Annotated[
diff --git a/marimo/_core/stream.py b/marimo/_core/stream.py
index ad7b02af6a..90adb0ea05 100644
--- a/marimo/_core/stream.py
+++ b/marimo/_core/stream.py
@@ -28,6 +28,8 @@ Body: TypeAlias = (
protocol.Host
| protocol.Project
| protocol.Notebook
+ | protocol.Document
+ | protocol.Cell
| protocol.Runtime
| protocol.Attachment
| protocol.Run
@@ -44,6 +46,8 @@ Kind: TypeAlias = Literal[
"host",
"project",
"notebook",
+ "document",
+ "cell",
"runtime",
"attachment",
"run",
diff --git a/marimo/_server/host/analysis.py b/marimo/_server/host/analysis.py
new file mode 100644
index 0000000000..dc382b33a2
--- /dev/null
+++ b/marimo/_server/host/analysis.py
@@ -0,0 +1,110 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Cell definitions, references, and syntax errors.
+
+The kernel reports errors involving multiple cells, such as cycles
+and multiple definitions.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from marimo._ast.compiler import compile_cell
+from marimo._core import protocol
+from marimo._types.ids import CellId_t
+
+if TYPE_CHECKING:
+ from collections.abc import Mapping
+
+ from marimo._ast.cell import CellImpl
+
+SOURCE = "marimo"
+
+
+class Analyzer:
+ """Incremental analysis for one document."""
+
+ def __init__(self) -> None:
+ self._codes: dict[str, str] = {}
+ self._compiled: dict[str, CellImpl] = {}
+ self._syntax: dict[str, protocol.Error] = {}
+
+ def __call__(
+ self, codes: Mapping[str, str]
+ ) -> dict[str, protocol.Analysis]:
+ self._update(codes)
+ definers: dict[str, int] = {}
+ for cell in self._compiled.values():
+ for name in cell.defs:
+ definers[name] = definers.get(name, 0) + 1
+ result: dict[str, protocol.Analysis] = {}
+ for cell_id in codes:
+ compiled = self._compiled.get(cell_id)
+ if compiled is None:
+ result[cell_id] = protocol.Analysis(
+ defs=(), refs=(), errors=(self._syntax[cell_id],)
+ )
+ continue
+ result[cell_id] = protocol.Analysis(
+ defs=tuple(sorted(compiled.defs)),
+ refs=tuple(
+ sorted(
+ name
+ for name in compiled.refs
+ if definers.get(name, 0) > (name in compiled.defs)
+ )
+ ),
+ errors=(),
+ )
+ return result
+
+ def _update(self, codes: Mapping[str, str]) -> None:
+ """Forget cells that are gone or changed, then compile what is new."""
+ for cell_id in list(self._codes):
+ if codes.get(cell_id) == self._codes[cell_id]:
+ continue
+ del self._codes[cell_id]
+ self._syntax.pop(cell_id, None)
+ self._compiled.pop(cell_id, None)
+ for cell_id, code in codes.items():
+ if cell_id in self._codes:
+ continue
+ try:
+ self._compiled[cell_id] = compile_cell(code, CellId_t(cell_id))
+ except (SyntaxError, ValueError) as error:
+ self._syntax[cell_id] = _syntax_error(code, error)
+ self._codes[cell_id] = code
+
+
+def analyze(codes: Mapping[str, str]) -> dict[str, protocol.Analysis]:
+ """Analyze a document once."""
+ return Analyzer()(codes)
+
+
+def _syntax_error(code: str, e: Exception) -> protocol.Error:
+ where = None
+ if isinstance(e, SyntaxError) and e.lineno is not None:
+ line = e.lineno - 1
+ character = _utf16(code, line, (e.offset or 1) - 1)
+ where = protocol.Range(
+ start=protocol.Position(line=line, character=character),
+ end=protocol.Position(line=line, character=character),
+ )
+ message = e.msg if isinstance(e, SyntaxError) else str(e)
+ return protocol.Error(
+ kind="invalid-syntax",
+ message=message,
+ source=SOURCE,
+ severity="error",
+ range=where,
+ name=None,
+ traceback=None,
+ related=(),
+ )
+
+
+def _utf16(code: str, line: int, column: int) -> int:
+ """Convert a source column to UTF-16 code units."""
+ lines = code.split("\n")
+ text = lines[line] if line < len(lines) else ""
+ return len(text[:column].encode("utf-16-le")) // 2
diff --git a/marimo/_server/host/api.py b/marimo/_server/host/api.py
index 09145c94ca..62c1392031 100644
--- a/marimo/_server/host/api.py
+++ b/marimo/_server/host/api.py
@@ -155,8 +155,10 @@ def _context(request: Request) -> HostContext:
return context # type: ignore[no-any-return]
-def _notebook(request: Request) -> Notebook:
- return _context(request).bridge.host.notebook(request.path_params["id"])
+async def _notebook(request: Request) -> Notebook:
+ return await _context(request).bridge.host.notebook(
+ request.path_params["id"]
+ )
def _record(request: Request) -> protocol.Notebook:
@@ -366,7 +368,7 @@ async def _decode(request: Request, kind: type[_Body]) -> _Body:
async def _events(request: Request) -> Response:
"""Stream catalog snapshots and updates.
- `Last-Event-ID` resumes from a cursor; `types` filters event kinds.
+ `Last-Event-ID` resumes from a cursor. `types` filters event kinds.
"""
context = _context(request)
cursor = _cursor(request)
@@ -384,9 +386,11 @@ async def _notebook_events(request: Request) -> Response:
"""Stream notebook events, attaching the client until disconnect."""
context = _context(request)
try:
- notebook = _notebook(request)
+ notebook = await _notebook(request)
except NotFound as e:
return problem(404, "not-found", str(e))
+ except Conflict as e:
+ return problem(409, "conflict", str(e))
cursor = _cursor(request)
if isinstance(cursor, Response):
return cursor
@@ -571,10 +575,10 @@ async def _update_notebook(request: Request) -> Response:
@_mutation("notebook.delete")
async def _delete_notebook(request: Request) -> Response:
- """Delete the notebook and file; return 409 while a runtime exists."""
+ """Delete the notebook and its file if it has no runtime."""
context = _context(request)
key = request.headers["Idempotency-Key"]
- await context.bridge.delete(_notebook(request).id, request_id=key)
+ await context.bridge.delete(_record(request).id, request_id=key)
return _reply(204, None)
@@ -612,9 +616,9 @@ def _open_quietly(browser: str, url: str) -> None:
@_mutation("runtime.start")
async def _start_runtime(request: Request) -> Response:
- """Start a runtime: 202 if created, 200 if already present."""
+ """Start a runtime and return 202, or 200 if it already exists."""
key = request.headers["Idempotency-Key"]
- notebook = _notebook(request)
+ notebook = await _notebook(request)
await _decode(request, protocol.StartRuntimeRequest)
runtime, created = notebook.start(request_id=key)
return _reply(202 if created else 200, runtime)
@@ -624,7 +628,7 @@ async def _start_runtime(request: Request) -> Response:
async def _stop_runtime(request: Request) -> Response:
"""Request shutdown and return 202 with the runtime marked terminating."""
key = request.headers["Idempotency-Key"]
- notebook = _notebook(request)
+ notebook = await _notebook(request)
runtime = notebook.stop(request_id=key)
return _reply(202, runtime)
@@ -633,7 +637,7 @@ async def _stop_runtime(request: Request) -> Response:
async def _restart_runtime(request: Request) -> Response:
"""Return 202 with the replacement runtime in its starting state."""
key = request.headers["Idempotency-Key"]
- notebook = _notebook(request)
+ notebook = await _notebook(request)
runtime = notebook.restart(request_id=key)
return _reply(202, runtime)
@@ -643,9 +647,9 @@ async def _restart_runtime(request: Request) -> Response:
@_mutation("runtime.run")
async def _run(request: Request) -> Response:
- """Queue a run and return 202; stream results through notebook events."""
+ """Queue a run and return 202. Results arrive through notebook events."""
key = request.headers["Idempotency-Key"]
- notebook = _notebook(request)
+ notebook = await _notebook(request)
body = await _decode(request, protocol.RunRequest)
if body.code is msgspec.UNSET or body.cells is not msgspec.UNSET:
return problem(
@@ -657,8 +661,8 @@ async def _run(request: Request) -> Response:
@_mutation("runtime.run")
async def _interrupt(request: Request) -> Response:
- """Request a run interruption: 202 if active, 409 if completed."""
- notebook = _notebook(request)
+ """Interrupt an active run and return 202, or 409 if it has completed."""
+ notebook = await _notebook(request)
run_id = request.path_params["run_id"]
try:
interrupted = notebook.interrupt(run_id)
diff --git a/marimo/_server/host/bridge.py b/marimo/_server/host/bridge.py
index b8904b1355..1c801e5e0d 100644
--- a/marimo/_server/host/bridge.py
+++ b/marimo/_server/host/bridge.py
@@ -4,14 +4,19 @@
from __future__ import annotations
import asyncio
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
from marimo import _loggers
+from marimo._config.manager import ScriptConfigReader
from marimo._core import protocol
+from marimo._core.document import CellSource, Document
from marimo._core.errors import Conflict, NotFound
+from marimo._core.executions import Executions
from marimo._core.host import Host
+from marimo._core.notebook import Notebook
from marimo._runtime.commands import RenameNotebookCommand
from marimo._server.host import OPERATIONS
+from marimo._server.host.analysis import Analyzer
from marimo._server.host.backend import SessionBackend
from marimo._server.host.index import WorkspaceIndex
from marimo._session.events import SessionEventListener
@@ -20,35 +25,46 @@ from marimo._session.notebook.storage import rename_no_replace
if TYPE_CHECKING:
from pathlib import Path
+ from marimo._ast.cell import CellConfig
+ from marimo._config.manager import MarimoConfigManager
from marimo._core.backend import Message
- from marimo._core.stream import Event
+ from marimo._core.document import Policy
+ from marimo._core.stream import Event, Sink
from marimo._server.session_manager import SessionManager
+ from marimo._session.notebook import AppFileManager
from marimo._session.session import Session
LOGGER = _loggers.marimo_logger()
+# TODO: Remove once sessions consume host-owned notebooks.
class SessionBridge(SessionEventListener):
"""Connect a host's notebook catalog to a session manager."""
- def __init__(self, manager: SessionManager) -> None:
+ def __init__(
+ self,
+ manager: SessionManager,
+ config_manager: MarimoConfigManager | None = None,
+ ) -> None:
self._manager = manager
+ self._config_manager = config_manager
self._files_lock = asyncio.Lock()
+ self._adopting: dict[protocol.NotebookId, Session] = {}
self.host = Host(operations=OPERATIONS)
self._backends: dict[protocol.NotebookId, SessionBackend] = {}
self.index = WorkspaceIndex(
- self.host, manager.workspace, self._make_backend
+ self.host, manager.workspace, self._initialize_notebook
)
self._unsubscribe = self.host.subscribe(
self._forget_backend, types={"notebook"}
)
- def open(self) -> None:
+ async def open(self) -> None:
"""Index notebooks, adopt sessions, and subscribe to session events."""
self.index.refresh()
- for session in list(self._manager.sessions.values()):
- self._adopt(session)
self._manager.event_bus.subscribe(self)
+ for session in list(self._manager.sessions.values()):
+ await self._adopt(session)
def close(self) -> None:
self._manager.event_bus.unsubscribe(self)
@@ -59,6 +75,80 @@ class SessionBridge(SessionEventListener):
async with self._files_lock:
await self.index.refresh_async()
+ async def _initialize_notebook(
+ self, record: protocol.Notebook, sink: Sink
+ ) -> Notebook:
+ """Read the document and construct its notebook."""
+ async with self._files_lock:
+ file = self.index.file_of(record.id)
+ loaded = None if file is None else await self._load(file)
+ session = self._adopting.get(record.id)
+ if session is None:
+ for candidate in self._manager.sessions.values():
+ candidate_record = self.index.notebook_for(
+ candidate.app_file_manager.path
+ )
+ if (
+ candidate_record is not None
+ and candidate_record.id == record.id
+ ):
+ session = candidate
+ break
+ if session is not None:
+ cells, app_config = _from_session(session)
+ else:
+ if loaded is None:
+ raise Conflict("The notebook document could not be loaded")
+ cells, app_config = loaded
+ document = Document(
+ record.id,
+ cells,
+ app_config,
+ policy=self._policy(file, session),
+ analyzer=Analyzer(),
+ saved=session is None,
+ )
+ if session is not None and loaded is not None:
+ document.mark_saved(Document(record.id, *loaded)._record.etag)
+ backend = self._make_backend(record.id)
+ return Notebook(document, Executions(), backend, sink)
+
+ async def _load(
+ self, file: Path
+ ) -> tuple[list[CellSource], dict[str, Any]] | None:
+ """Read a notebook file, or return `None` if it cannot be loaded."""
+ try:
+ return await asyncio.to_thread(self._read, str(file))
+ except Exception as e:
+ LOGGER.warning("Could not load %s: %s", file, e)
+ return None
+
+ def _read(self, path: str) -> tuple[list[CellSource], dict[str, Any]]:
+ from marimo._server.app_defaults import AppDefaults
+ from marimo._session.notebook import AppFileManager
+
+ defaults = (
+ None
+ if self._config_manager is None
+ else AppDefaults.from_config_manager(self._config_manager)
+ )
+ return _from_file_manager(AppFileManager(path, defaults=defaults))
+
+ def _policy(self, file: Path | None, session: Session | None) -> Policy:
+ config_manager = (
+ session.config_manager
+ if session is not None
+ else self._config_manager
+ )
+ if config_manager is None:
+ return "autorun"
+ if session is None:
+ config_manager = config_manager.with_partial(
+ ScriptConfigReader(None if file is None else str(file))
+ )
+ policy = config_manager.get_config()["runtime"]["on_cell_change"]
+ return "lazy" if policy == "lazy" else "autorun"
+
def _project_path(self, path: Path) -> Path:
root = self.index.root
if root is None:
@@ -107,7 +197,7 @@ class SessionBridge(SessionEventListener):
) -> protocol.Notebook:
"""Update a notebook's file and label, preserving its runtime."""
async with self._files_lock:
- self.host.notebook(notebook_id)
+ self.host.peek_notebook(notebook_id)
if target is not None:
await self._move(notebook_id, target, request_id=request_id)
if name is not None:
@@ -119,8 +209,10 @@ class SessionBridge(SessionEventListener):
) -> None:
"""Remove a notebook without a runtime and its backing file."""
async with self._files_lock:
- notebook = self.host.notebook(notebook_id)
- if notebook.runtime is not None:
+ notebook = self.host.peek_notebook(notebook_id)
+ if notebook_id in self._adopting or (
+ notebook is not None and notebook.runtime is not None
+ ):
raise Conflict("The notebook has a runtime")
file = self.index.file_of(notebook_id)
if file is not None:
@@ -184,11 +276,12 @@ class SessionBridge(SessionEventListener):
def observe(message: Message) -> None:
try:
- notebook = self.host.notebook(notebook_id)
+ notebook = self.host.peek_notebook(notebook_id)
except NotFound:
# Sessions can report shutdown after their catalog removal.
return
- notebook.observe(message)
+ if notebook is not None:
+ notebook.observe(message)
backend = SessionBackend(
notebook_id,
@@ -203,7 +296,7 @@ class SessionBridge(SessionEventListener):
if event.name == "notebook.removed" and event.notebook_id is not None:
self._backends.pop(event.notebook_id, None)
- def _adopt(self, session: Session) -> None:
+ async def _adopt(self, session: Session) -> None:
path = session.app_file_manager.path
notebook = self.index.notebook_for(path)
if notebook is None and path is not None:
@@ -211,13 +304,17 @@ class SessionBridge(SessionEventListener):
if notebook is None:
LOGGER.debug("Not publishing session for %s", path)
return
+ if self._adopting.setdefault(notebook.id, session) is not session:
+ return
+ try:
+ loaded = await self.host.notebook(notebook.id)
+ finally:
+ self._adopting.pop(notebook.id, None)
backend = self._backends[notebook.id]
if backend.session is not None:
return
try:
- self.host.notebook(notebook.id).adopt(
- lambda runtime_id: backend.adopt(runtime_id, session)
- )
+ loaded.adopt(lambda runtime_id: backend.adopt(runtime_id, session))
except Conflict:
LOGGER.debug("Not publishing a second session for %s", path)
return
@@ -225,7 +322,7 @@ class SessionBridge(SessionEventListener):
# Session events
async def on_session_created(self, session: Session) -> None:
- self._adopt(session)
+ await self._adopt(session)
async def on_session_notebook_renamed(
self, session: Session, old_path: str | None
@@ -236,6 +333,33 @@ class SessionBridge(SessionEventListener):
return
if notebook is None:
# Add notebooks to the catalog when first saved.
- self._adopt(session)
+ await self._adopt(session)
return
self.index.moved(notebook.id, path)
+
+
+def _from_session(session: Session) -> tuple[list[CellSource], dict[str, Any]]:
+ cells = [
+ CellSource(cell.id, cell.code, cell.name, _config(cell.config))
+ for cell in session.document.cells
+ ]
+ return cells, session.app_file_manager.app.config.asdict_difference()
+
+
+def _from_file_manager(
+ manager: AppFileManager,
+) -> tuple[list[CellSource], dict[str, Any]]:
+ cells = [
+ CellSource(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()
+
+
+def _config(config: CellConfig) -> protocol.CellConfig:
+ return protocol.CellConfig(
+ column=config.column,
+ disabled=config.disabled,
+ hide_code=config.hide_code,
+ expand_output=config.expand_output,
+ )
diff --git a/marimo/_server/host/index.py b/marimo/_server/host/index.py
index e6e5b0bed7..a36282f687 100644
--- a/marimo/_server/host/index.py
+++ b/marimo/_server/host/index.py
@@ -7,7 +7,6 @@ Notebook IDs persist across rescans and recorded file moves.
from __future__ import annotations
import asyncio
-from collections.abc import Callable
from datetime import datetime, timezone
from pathlib import Path
from typing import TYPE_CHECKING
@@ -20,15 +19,12 @@ from marimo._server.host import OPERATIONS
from marimo._server.workspace import flatten_files
if TYPE_CHECKING:
- from marimo._core.backend import Backend
- from marimo._core.host import Host
+ from marimo._core.host import Host, NotebookInitializer
from marimo._server.models.files import FileInfo
from marimo._server.workspace import NotebookWorkspace
_TRUNCATED = "The scan stopped at its depth, file count, or time limit"
-MakeBackend = Callable[[protocol.NotebookId], "Backend"]
-
class WorkspaceIndex:
"""A host project and its indexed notebook files."""
@@ -37,11 +33,11 @@ class WorkspaceIndex:
self,
host: Host,
workspace: NotebookWorkspace,
- make_backend: MakeBackend,
+ initialize: NotebookInitializer,
) -> None:
self._host = host
+ self._initialize = initialize
self._workspace = workspace
- self._make_backend = make_backend
self._root = _root_of(workspace)
self.project_id = mint(protocol.ProjectId, "proj")
self._ids: dict[Path, protocol.NotebookId] = {}
@@ -96,7 +92,8 @@ class WorkspaceIndex:
continue
if notebook.id in seen or self._exists(notebook):
continue
- if self._host.notebook(notebook.id).runtime is not None:
+ loaded = self._host.peek_notebook(notebook.id)
+ if loaded is not None and loaded.runtime is not None:
self._host.update_notebook(
replace(notebook, path=None, updated_at=None)
)
@@ -215,8 +212,9 @@ class WorkspaceIndex:
if notebook_id in self._host.notebooks:
self._host.update_notebook(record, request_id=request_id)
else:
- backend = self._make_backend(notebook_id)
- self._host.add_notebook(record, backend, request_id=request_id)
+ self._host.add_notebook(
+ record, self._initialize, request_id=request_id
+ )
return record
def _exists(self, notebook: protocol.Notebook) -> bool:
diff --git a/marimo/_server/host/lifespan.py b/marimo/_server/host/lifespan.py
index 008667ba3a..93ad3cf930 100644
--- a/marimo/_server/host/lifespan.py
+++ b/marimo/_server/host/lifespan.py
@@ -31,8 +31,8 @@ async def host(app: Starlette) -> AsyncIterator[None]:
yield
return
- bridge = SessionBridge(state.session_manager)
- bridge.open()
+ bridge = SessionBridge(state.session_manager, state.config_manager)
+ await bridge.open()
token = secrets.token_urlsafe(32)
server = state.server.config
url = host_url(server.host, server.port, state.base_url)
diff --git a/marimo/_server/host/translate.py b/marimo/_server/host/translate.py
index f878736999..16c5f0caff 100644
--- a/marimo/_server/host/translate.py
+++ b/marimo/_server/host/translate.py
@@ -3,13 +3,13 @@
from __future__ import annotations
-import hashlib
import html
import json
import re
from dataclasses import dataclass, field
from marimo._core import backend as be, protocol
+from marimo._core.document import code_hash
from marimo._messaging.cell_output import CellChannel
from marimo._messaging.errors import (
Error,
@@ -134,7 +134,7 @@ class RunTranslator:
None
if execution.cell_id == SCRATCH_CELL_ID
else execution.cell_id,
- hashlib.sha256(code.encode()).hexdigest(),
+ code_hash(code),
code if execution.cell_id == SCRATCH_CELL_ID else None,
caused_by=parent.id if parent is not None else None,
),
diff --git a/protocols/host/conformance/contract.py b/protocols/host/conformance/contract.py
index f4b98878e4..28a1bce3c3 100644
--- a/protocols/host/conformance/contract.py
+++ b/protocols/host/conformance/contract.py
@@ -212,7 +212,11 @@ def document_state(
for key in ("column", "disabled", "hide_code", "expand_output")
)
assert cell["etag"] == etag("\n".join(parts))
- assert document["order_etag"] == etag("\n".join(document["order"]))
+ assert document["order_etag"] == etag(
+ json.dumps(
+ document["order"], separators=(",", ":"), ensure_ascii=False
+ )
+ )
canonical = json.dumps(
document["app_config"],
sort_keys=True,
diff --git a/protocols/host/fixtures/edit-response.json b/protocols/host/fixtures/edit-response.json
index 89fed4614c..97c14f559e 100644
--- a/protocols/host/fixtures/edit-response.json
+++ b/protocols/host/fixtures/edit-response.json
@@ -11,9 +11,9 @@
"app_title": "Forecasts"
},
"policy": "autorun",
- "etag": "82eabd9627d6bdf4",
- "saved_etag": "0129d119bfb96bf9",
- "order_etag": "389ebf709589e5d6",
+ "etag": "949c0dd20bc77042",
+ "saved_etag": "e59d9c2af02f5814",
+ "order_etag": "162e15055422ed71",
"app_config_etag": "1d79ec53fdad1a23"
},
"cells": {
diff --git a/protocols/host/fixtures/edits.sse b/protocols/host/fixtures/edits.sse
index 3b1beb6fbf..771fc655b7 100644
--- a/protocols/host/fixtures/edits.sse
+++ b/protocols/host/fixtures/edits.sse
@@ -12,9 +12,9 @@ data: {"id":"k7f2","request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2
id: 113
event: document
-data: {"document":{"id":"n1","order":["c1","c2","c3"],"app_config":{"width":"full","app_title":"Forecasts"},"policy":"autorun","etag":"82eabd9627d6bdf4","saved_etag":"0129d119bfb96bf9","order_etag":"389ebf709589e5d6","app_config_etag":"1d79ec53fdad1a23"},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}
+data: {"document":{"id":"n1","order":["c1","c2","c3"],"app_config":{"width":"full","app_title":"Forecasts"},"policy":"autorun","etag":"949c0dd20bc77042","saved_etag":"e59d9c2af02f5814","order_etag":"162e15055422ed71","app_config_etag":"1d79ec53fdad1a23"},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}
id: 114
event: document
-data: {"document":{"id":"n1","order":["c1","c2","c3"],"app_config":{"width":"full","app_title":"Forecasts"},"policy":"autorun","etag":"82eabd9627d6bdf4","saved_etag":"82eabd9627d6bdf4","order_etag":"389ebf709589e5d6","app_config_etag":"1d79ec53fdad1a23"},"request_id":"save-9b1c6d2e","time":"2026-10-01T09:21:02Z"}
+data: {"document":{"id":"n1","order":["c1","c2","c3"],"app_config":{"width":"full","app_title":"Forecasts"},"policy":"autorun","etag":"949c0dd20bc77042","saved_etag":"949c0dd20bc77042","order_etag":"162e15055422ed71","app_config_etag":"1d79ec53fdad1a23"},"request_id":"save-9b1c6d2e","time":"2026-10-01T09:21:02Z"}
diff --git a/protocols/host/fixtures/notebook-events.sse b/protocols/host/fixtures/notebook-events.sse
index f7b2812ce5..16ab8c787a 100644
--- a/protocols/host/fixtures/notebook-events.sse
+++ b/protocols/host/fixtures/notebook-events.sse
@@ -11,7 +11,7 @@ event: cell
data: {"cell":{"id":"k7f2","notebook_id":"n1","code":"y = x * 2","name":"_","config":{"column":null,"disabled":false,"hide_code":true,"expand_output":false},"etag":"f199b5f48ae0aabb","code_hash":"db2b9ee97e1ecf4c","analysis":{"defs":["y"],"refs":["x"],"errors":[]}}}
event: document
-data: {"document":{"id":"n1","order":["c1","c3","k7f2"],"app_config":{"width":"full"},"policy":"autorun","etag":"0129d119bfb96bf9","saved_etag":"0129d119bfb96bf9","order_etag":"b205774f616b44e3","app_config_etag":"283513048dfeb45b"}}
+data: {"document":{"id":"n1","order":["c1","c3","k7f2"],"app_config":{"width":"full"},"policy":"autorun","etag":"e59d9c2af02f5814","saved_etag":"e59d9c2af02f5814","order_etag":"b9c412c2d7d63161","app_config_etag":"283513048dfeb45b"}}
event: runtime
data: {"runtime":{"id":"r1","notebook_id":"n1","status":"running","message":null,"marimo_version":"0.25.0","started_at":"2026-10-01T09:14:02Z"}}
diff --git a/protocols/host/fixtures/problems/edit-conflict.json b/protocols/host/fixtures/problems/edit-conflict.json
index 1f4c3e8e36..d73bd124f3 100644
--- a/protocols/host/fixtures/problems/edit-conflict.json
+++ b/protocols/host/fixtures/problems/edit-conflict.json
@@ -38,9 +38,9 @@
"app_title": "Forecasts"
},
"policy": "autorun",
- "etag": "82eabd9627d6bdf4",
- "saved_etag": "0129d119bfb96bf9",
- "order_etag": "389ebf709589e5d6",
+ "etag": "949c0dd20bc77042",
+ "saved_etag": "e59d9c2af02f5814",
+ "order_etag": "162e15055422ed71",
"app_config_etag": "1d79ec53fdad1a23"
}
}
diff --git a/protocols/host/openapi.yaml b/protocols/host/openapi.yaml
index d19c2e47db..ef1b779b78 100644
--- a/protocols/host/openapi.yaml
+++ b/protocols/host/openapi.yaml
@@ -1368,7 +1368,7 @@ components:
description: Identifies the document as last written to the host's store, computed the same way over that state. Equal to `etag` when every accepted change has been persisted. Null when nothing has been persisted, which is the case for a scratch copy.
order_etag:
$ref: '#/components/schemas/Etag'
- description: Identifies the order alone. Its text is the cell ids in order. Editing a cell does not change it.
+ description: Identifies the order alone. Its text is the cell IDs in order as a JSON array, with no whitespace and strings carrying only the escapes JSON requires. Editing a cell does not change it.
app_config_etag:
$ref: '#/components/schemas/Etag'
description: Identifies the app config alone. Its text is the app config as canonical JSON, with keys sorted by code point, no whitespace, and strings carrying only the escapes JSON requires.
diff --git a/tests/_core/conftest.py b/tests/_core/conftest.py
index 79b686ec1d..5c871002bd 100644
--- a/tests/_core/conftest.py
+++ b/tests/_core/conftest.py
@@ -3,13 +3,17 @@
from __future__ import annotations
+from copy import deepcopy
+
import pytest
from marimo._core import backend as be, protocol
+from marimo._core.document import Analyzer, Document, code_hash
+from marimo._core.executions import CellExecution, Executions
from marimo._core.host import Host
-from marimo._core.notebook import Notebook
+from marimo._core.notebook import CellSnapshot, Notebook, NotebookSnapshot
from marimo._core.run_log import RetentionPolicy
-from marimo._core.stream import Event
+from marimo._core.stream import Event, Sink, Stream
OPERATIONS = ["notebook.create", "runtime.start", "runtime.run"]
@@ -66,6 +70,93 @@ def record(
)
+def make_notebook(
+ record: protocol.Notebook,
+ sink: Sink,
+ backend: ScriptedBackend | None = None,
+ *,
+ document: Document | None = None,
+) -> Notebook:
+ return Notebook(
+ document or Document(record.id, [], {}),
+ Executions(),
+ backend or ScriptedBackend(),
+ sink,
+ )
+
+
+def snapshot_of(
+ document: Document,
+ executions: dict[str, CellExecution] | None = None,
+) -> NotebookSnapshot:
+ """A snapshot of the document with executions retained by cell id."""
+ return NotebookSnapshot(
+ document._record,
+ tuple(
+ CellSnapshot(cell, (executions or {}).get(cell.id))
+ for cell in document
+ ),
+ )
+
+
+def capture(notebook: Notebook) -> NotebookSnapshot:
+ """The snapshot a host would prepare from the notebook's state."""
+ return deepcopy(
+ NotebookSnapshot(
+ notebook.document._record,
+ tuple(
+ CellSnapshot(cell, notebook.executions.current(cell.id))
+ for cell in notebook.document
+ ),
+ )
+ )
+
+
+def restore(
+ snapshot: NotebookSnapshot,
+ backend: ScriptedBackend | None = None,
+ *,
+ analyzer: Analyzer | None = None,
+ sink: Sink | None = None,
+) -> Notebook:
+ """Build a notebook from a snapshot, one core at a time."""
+ document = Document.from_records(
+ snapshot.document,
+ [entry.cell for entry in snapshot.cells],
+ analyzer=analyzer,
+ )
+ executions = Executions.restore(
+ {
+ entry.cell.id: entry.execution
+ for entry in snapshot.cells
+ if entry.execution is not None
+ },
+ cells=document,
+ )
+ return Notebook(
+ document,
+ executions,
+ backend or ScriptedBackend(),
+ sink if sink is not None else Stream(history=0),
+ )
+
+
+async def add_notebook(
+ host: Host,
+ record: protocol.Notebook,
+ backend: ScriptedBackend,
+ *,
+ document: Document | None = None,
+) -> Notebook:
+ host.add_notebook(
+ record,
+ lambda current, sink: make_notebook(
+ current, sink, backend, document=document
+ ),
+ )
+ return await host.notebook(record.id)
+
+
@pytest.fixture
def host() -> Host:
return Host(operations=OPERATIONS)
@@ -77,9 +168,9 @@ def backend() -> ScriptedBackend:
@pytest.fixture
-def notebook(host: Host, backend: ScriptedBackend) -> Notebook:
+async def notebook(host: Host, backend: ScriptedBackend) -> Notebook:
host.update_project(project())
- return host.add_notebook(record(), backend)
+ return await add_notebook(host, record(), backend)
@pytest.fixture
@@ -105,7 +196,7 @@ class Clock:
return self.now
-def host_at(clock: Clock, history: int = 1000) -> tuple[Host, Notebook]:
+async def host_at(clock: Clock, history: int = 1000) -> tuple[Host, Notebook]:
host = Host(
operations=[],
history=history,
@@ -113,7 +204,7 @@ def host_at(clock: Clock, history: int = 1000) -> tuple[Host, Notebook]:
retention=RetentionPolicy(ephemeral_seconds=10),
)
host.update_project(project())
- notebook = host.add_notebook(record(), ScriptedBackend())
+ notebook = await add_notebook(host, record(), ScriptedBackend())
notebook.adopt(lambda _: None)
notebook.observe(be.Running(runtime_id_of(notebook)))
return host, notebook
@@ -161,3 +252,38 @@ def fold(events: list[Event], initial: dict | None = None) -> dict:
body = getattr(event.data, event.kind)
state[event.kind, body.id] = body
return state
+
+
+def retained_execution(
+ cell_id: str | None = "c1", run_id: str | None = None
+) -> CellExecution:
+ """A completed execution with one console item, as a store retains it."""
+ execution_id = protocol.ExecutionId("restored")
+ return CellExecution(
+ protocol.Execution(
+ id=execution_id,
+ run_id=None if run_id is None else protocol.RunId(run_id),
+ runtime_id=None,
+ caused_by=None,
+ cell_id=None if cell_id is None else protocol.CellId(cell_id),
+ code="42" if cell_id is None else None,
+ code_hash=code_hash("42"),
+ bindings=(),
+ status="completed",
+ outcome=protocol.ValueOutcome(
+ protocol.DisplayData(mimetype="text/plain", data="42")
+ ),
+ stale=False if cell_id is not None else None,
+ started_at=None,
+ completed_at=None,
+ ),
+ (
+ protocol.Console(
+ execution_id,
+ protocol.ItemId("restored-output"),
+ "stdout",
+ 0,
+ "hello",
+ ),
+ ),
+ )
diff --git a/tests/_core/test_executions.py b/tests/_core/test_executions.py
index ab6c9a0611..f30d162532 100644
--- a/tests/_core/test_executions.py
+++ b/tests/_core/test_executions.py
@@ -4,11 +4,20 @@
from __future__ import annotations
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.errors import NoRuntime
-from marimo._core.executions import Change, Executions, Released, Removed
+from marimo._core.executions import (
+ CellExecution,
+ Change,
+ Executions,
+ Released,
+ Removed,
+)
from marimo._core.stream import kind_of, utcnow
+from tests._core.conftest import retained_execution
NOTEBOOK = protocol.NotebookId("n1")
RUNTIME = protocol.Runtime(
@@ -233,6 +242,92 @@ def test_planning_does_not_scan_unrelated_cells(
assert sum(isinstance(c, protocol.Execution) for c in changes) == 1000
+def test_removing_a_cell_drops_its_result_or_disowns_active_work() -> None:
+ executions = Executions()
+ executions.begin(run("r1"), "request")
+ executions.observe(planned("r1", ("e1", "a"), ("e2", "b")), RUNTIME)
+ complete(executions, "e1")
+ executions.observe(
+ be.Status(protocol.ExecutionId("e2"), "running"), RUNTIME
+ )
+ assert describe(executions.remove_cell(protocol.CellId("a"))) == [
+ "execution.removed e1"
+ ]
+ # Active work stays tracked, but no longer belongs to a cell.
+ assert executions.remove_cell(protocol.CellId("b")) == []
+ assert executions.remove_cell(protocol.CellId("never")) == []
+ assert executions.current(protocol.CellId("b")) is None
+ complete(executions, "e2")
+ done = executions.observe(
+ be.Done(protocol.RunId("r1"), "succeeded"), RUNTIME
+ )
+ assert describe(done) == ["run r1", "execution.removed e2", "released r1"]
+
+
+def test_restored_executions_are_current_until_replaced() -> None:
+ document = Document(NOTEBOOK, [CellSource("c1", "42")], {})
+ retained = retained_execution(run_id="old-run")
+ executions = Executions.restore(
+ {protocol.CellId("c1"): retained}, cells=document
+ )
+ assert executions.current(protocol.CellId("c1")) == retained
+ assert describe(executions._records()) == [
+ "execution restored",
+ "console restored-output",
+ ]
+ executions.begin(run("r1"), "request")
+ changes = executions.observe(planned("r1", ("e1", "c1")), RUNTIME)
+ assert describe(changes) == [
+ "console.removed restored-output",
+ "execution.removed restored",
+ "execution e1",
+ ]
+ assert executions.current(protocol.CellId("c1")) is None
+
+
+ ("invalid", "message"),
+ [
+ ("scratch", "containing cell"),
+ ("other-cell", "containing cell"),
+ ("missing-cell", "not in the document"),
+ ("unfinished", "completed"),
+ ("no-outcome", "outcome"),
+ ("output-owner", "belong to their execution"),
+ ("duplicate-output", "unique"),
+ ],
+)
+def test_restore_rejects_inconsistent_executions(
+ invalid: str, message: str
+) -> None:
+ document = Document(NOTEBOOK, [CellSource("c1", "42")], {})
+ retained = retained_execution()
+ execution, outputs = retained.execution, retained.outputs
+ key = protocol.CellId("c1")
+ if invalid == "scratch":
+ retained = retained_execution(cell_id=None, run_id="previous-run")
+ elif invalid == "other-cell":
+ retained = CellExecution(
+ replace(execution, cell_id=protocol.CellId("c2")), outputs
+ )
+ elif invalid == "missing-cell":
+ key = protocol.CellId("missing")
+ retained = CellExecution(replace(execution, cell_id=key), outputs)
+ elif invalid == "unfinished":
+ retained = CellExecution(replace(execution, status="running"), outputs)
+ elif invalid == "no-outcome":
+ retained = CellExecution(replace(execution, outcome=None), outputs)
+ elif invalid == "output-owner":
+ retained = CellExecution(
+ execution,
+ (replace(outputs[0], execution_id=protocol.ExecutionId("other")),),
+ )
+ else:
+ retained = CellExecution(execution, outputs * 2)
+ with pytest.raises(ValueError, match=message):
+ Executions.restore({key: retained}, cells=document)
+
+
def test_current_result_keeps_its_outputs_as_the_execution_changes() -> None:
executions = Executions()
cell_id = protocol.CellId("a")
diff --git a/tests/_core/test_host.py b/tests/_core/test_host.py
index 4633f4d8f0..ab99ae03ba 100644
--- a/tests/_core/test_host.py
+++ b/tests/_core/test_host.py
@@ -3,6 +3,7 @@
from __future__ import annotations
+import asyncio
from typing import TYPE_CHECKING
import pytest
@@ -12,13 +13,15 @@ from msgspec.structs import replace
from marimo._core import backend as be, protocol
from marimo._core.errors import NotFound
from marimo._core.host import Host
-from marimo._core.stream import Event
+from marimo._core.stream import Event, Sink
from tests._core.conftest import (
Clock,
ScriptedBackend,
+ add_notebook,
finish,
fold,
host_at,
+ make_notebook,
names,
plan,
project,
@@ -94,9 +97,9 @@ def test_replacing_a_cell_result_updates_history_before_delivery(
assert snapshots == [{("run", replacement.id), ("execution", "new")}]
-def test_catalog_snapshot_and_replay_exclude_runs(host: Host) -> None:
+async def test_catalog_snapshot_and_replay_exclude_runs(host: Host) -> None:
host.update_project(project())
- notebook = host.add_notebook(record(), ScriptedBackend())
+ notebook = await add_notebook(host, record(), ScriptedBackend())
notebook.start()
notebook.observe(be.Running(runtime_id_of(notebook)))
run = notebook.run("1", request_id="r1")
@@ -126,10 +129,10 @@ def test_catalog_snapshot_and_replay_exclude_runs(host: Host) -> None:
assert names(host.events(cursor)) == ["attachment", "ready"]
-def test_a_notebook_stream_sees_only_its_notebook(host: Host) -> None:
+async def test_a_notebook_stream_sees_only_its_notebook(host: Host) -> None:
host.update_project(project())
- first = host.add_notebook(record("n1", "a.py"), ScriptedBackend())
- second = host.add_notebook(record("n2", "b.py"), ScriptedBackend())
+ first = await add_notebook(host, record("n1", "a.py"), ScriptedBackend())
+ second = await add_notebook(host, record("n2", "b.py"), ScriptedBackend())
first.start()
first.observe(be.Running(runtime_id_of(first)))
run = first.run("1", request_id="r1")
@@ -144,6 +147,7 @@ def test_a_notebook_stream_sees_only_its_notebook(host: Host) -> None:
events = host.events(notebook_id="n1")
assert names(events) == [
"notebook",
+ "document",
"runtime",
"run",
"execution",
@@ -155,6 +159,7 @@ def test_a_notebook_stream_sees_only_its_notebook(host: Host) -> None:
live = host.events(0, notebook_id="n1")
assert names(live) == [
"notebook",
+ "document",
"runtime",
"runtime",
"run",
@@ -167,10 +172,10 @@ def test_a_notebook_stream_sees_only_its_notebook(host: Host) -> None:
host.events(notebook_id="n3")
-def test_resume_replays_or_resets() -> None:
+async def test_resume_replays_or_resets() -> None:
small = Host(operations=[], history=2)
small.update_project(project())
- small.add_notebook(record(), ScriptedBackend())
+ await add_notebook(small, record(), ScriptedBackend())
cursor = small.events()[-1].id
assert cursor is not None
@@ -183,9 +188,9 @@ def test_resume_replays_or_resets() -> None:
assert names(small.events(10**6))[0] == "reset"
-def test_types_filter_keeps_ready_and_reset(host: Host) -> None:
+async def test_types_filter_keeps_ready_and_reset(host: Host) -> None:
host.update_project(project())
- host.add_notebook(record(), ScriptedBackend())
+ await add_notebook(host, record(), ScriptedBackend())
assert names(host.events(types={"notebook"})) == ["notebook", "ready"]
assert names(host.events(10**6, types={"notebook"})) == [
"reset",
@@ -194,9 +199,9 @@ def test_types_filter_keeps_ready_and_reset(host: Host) -> None:
]
-def test_subscribe_filters_the_live_stream(host: Host) -> None:
+async def test_subscribe_filters_the_live_stream(host: Host) -> None:
host.update_project(project())
- notebook = host.add_notebook(record(), ScriptedBackend())
+ notebook = await add_notebook(host, record(), ScriptedBackend())
catalog: list[Event] = []
mine: list[Event] = []
runtimes: list[Event] = []
@@ -215,9 +220,11 @@ def test_subscribe_filters_the_live_stream(host: Host) -> None:
assert names(runtimes) == ["runtime", "runtime"]
-def test_removing_a_notebook_removes_what_it_owns_first(host: Host) -> None:
+async def test_removing_a_notebook_removes_what_it_owns_first(
+ host: Host,
+) -> None:
host.update_project(project())
- notebook = host.add_notebook(record(), ScriptedBackend())
+ notebook = await add_notebook(host, record(), ScriptedBackend())
notebook.start()
notebook.observe(be.Running(runtime_id_of(notebook)))
notebook.attach()
@@ -237,14 +244,14 @@ def test_removing_a_notebook_removes_what_it_owns_first(host: Host) -> None:
assert getattr(log[-1].data, "request_id", None) == "req-del"
assert "n1" not in host.notebooks
with pytest.raises(NotFound):
- host.notebook(notebook.id)
+ (await host.notebook(notebook.id))
host.remove_notebook("n1") # Repeated removal is a no-op.
-def test_updating_a_notebook_publishes_only_changes(host: Host) -> None:
+async def test_updating_a_notebook_publishes_only_changes(host: Host) -> None:
host.update_project(project())
backend = ScriptedBackend()
- notebook = host.add_notebook(record(), backend)
+ notebook = await add_notebook(host, record(), backend)
notebook.start()
notebook.observe(be.Running(runtime_id_of(notebook)))
run = notebook.run("1", request_id="run")
@@ -259,7 +266,7 @@ def test_updating_a_notebook_publishes_only_changes(host: Host) -> None:
host.update_notebook(moved, request_id="req-mv")
assert host.notebooks[notebook.id] == moved
- assert host.notebook("n1") is notebook
+ assert (await host.notebook("n1")) is notebook
assert notebook.runtime is runtime
assert backend.calls == []
assert host.events(notebook_id="n1", types={"run"})[
@@ -322,16 +329,18 @@ def test_removed_notebook_handles_cannot_be_reused(
assert notebook.runtime is None
-def test_catalog_requires_the_project(host: Host) -> None:
+async def test_catalog_requires_the_project(host: Host) -> None:
with pytest.raises(ValueError, match="project"):
- host.add_notebook(record(), ScriptedBackend())
+ await add_notebook(host, record(), ScriptedBackend())
host.update_project(project())
- host.add_notebook(record(), ScriptedBackend())
+ await add_notebook(host, record(), ScriptedBackend())
with pytest.raises(ValueError, match="already"):
- host.add_notebook(record(), ScriptedBackend())
+ await add_notebook(host, record(), ScriptedBackend())
-def test_catalog_updates_do_not_share_mutable_records(host: Host) -> None:
+async def test_catalog_updates_do_not_share_mutable_records(
+ host: Host,
+) -> None:
source = project()
host.update_project(source)
with pytest.raises(AttributeError):
@@ -351,7 +360,7 @@ def test_catalog_updates_do_not_share_mutable_records(host: Host) -> None:
]
original = record()
- host.add_notebook(original, ScriptedBackend())
+ await add_notebook(host, original, ScriptedBackend())
with pytest.raises(AttributeError):
original.name = "caller mutation"
original = replace(original, name="caller mutation", operations=())
@@ -368,12 +377,121 @@ def test_catalog_updates_do_not_share_mutable_records(host: Host) -> None:
)
+async def test_initializer_receives_current_record_and_runs_once(
+ host: Host,
+) -> None:
+ host.update_project(project())
+ calls = []
+
+ def initialize(current: protocol.Notebook, sink: Sink) -> Notebook:
+ calls.append(current)
+ return make_notebook(current, sink)
+
+ host.add_notebook(record(), initialize)
+ moved = replace(record(), path="renamed.py", name="renamed")
+ host.update_notebook(moved)
+ assert host.peek_notebook("n1") is None
+ assert names(host.events()) == ["host", "project", "notebook", "ready"]
+ assert calls == []
+
+ notebook = await host.notebook("n1")
+ assert calls == [moved]
+ assert await host.notebook("n1") is notebook
+ host.update_notebook(replace(moved, name="Another name"))
+ assert await host.notebook("n1") is notebook
+ assert calls == [moved]
+
+
+async def test_concurrent_callers_share_initialization_despite_cancellation(
+ host: Host,
+) -> None:
+ host.update_project(project())
+ entered = asyncio.Event()
+ release = asyncio.Event()
+ calls = []
+
+ async def initialize(current: protocol.Notebook, sink: Sink) -> Notebook:
+ calls.append(current)
+ entered.set()
+ await release.wait()
+ return make_notebook(current, sink)
+
+ host.add_notebook(record(), initialize)
+ first = asyncio.create_task(host.notebook("n1"))
+ await entered.wait()
+ second = asyncio.create_task(host.notebook("n1"))
+ first.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await first
+ release.set()
+ notebook = await second
+ assert calls == [record()]
+ assert await host.notebook("n1") is notebook
+
+
+async def test_initialization_failure_can_be_retried(host: Host) -> None:
+ host.update_project(project())
+ attempts = 0
+
+ def initialize(current: protocol.Notebook, sink: Sink) -> Notebook:
+ nonlocal attempts
+ attempts += 1
+ if attempts == 1:
+ raise OSError("unreadable")
+ return make_notebook(current, sink)
+
+ host.add_notebook(record(), initialize)
+ with pytest.raises(OSError, match="unreadable"):
+ await host.notebook("n1")
+ assert host.peek_notebook("n1") is None
+ assert names(host.events(notebook_id="n1")) == ["notebook", "ready"]
+ notebook = await host.notebook("n1")
+ assert await host.notebook("n1") is notebook
+ assert attempts == 2
+
+
+async def test_removed_entry_cannot_be_resurrected_by_its_initializer(
+ host: Host,
+) -> None:
+ host.update_project(project())
+ entered = asyncio.Event()
+ release = asyncio.Event()
+
+ async def initialize(current: protocol.Notebook, sink: Sink) -> Notebook:
+ entered.set()
+ try:
+ await release.wait()
+ except asyncio.CancelledError:
+ pass # Even a loader that finishes after cancellation cannot register.
+ return make_notebook(current, sink)
+
+ host.add_notebook(record(), initialize)
+ pending = asyncio.create_task(host.notebook("n1"))
+ await entered.wait()
+ host.remove_notebook("n1")
+ host.add_notebook(record(), make_notebook)
+ with pytest.raises(NotFound):
+ await pending
+ assert host.peek_notebook("n1") is None
+ assert (await host.notebook("n1")).id == "n1"
+
+
+async def test_initializer_cannot_return_another_notebook(host: Host) -> None:
+ host.update_project(project())
+ host.add_notebook(
+ record(), lambda _, sink: make_notebook(record("n2"), sink)
+ )
+ with pytest.raises(ValueError, match="catalog id"):
+ await host.notebook("n1")
+ assert host.peek_notebook("n1") is None
+
+
@pytest.mark.parametrize("history", [2, 1000])
-def test_expiration_converges_for_live_replay_and_snapshot(
+async def test_expiration_converges_for_live_replay_and_snapshot(
history: int,
) -> None:
clock = Clock()
- host, notebook = host_at(clock, history)
+ host, notebook = await host_at(clock, history)
run = notebook.run("code", request_id="request")
execution = plan(notebook, run, "e")
item = protocol.Console(
@@ -436,11 +554,11 @@ def test_expiration_converges_for_live_replay_and_snapshot(
assert live == []
-def test_cell_results_outlive_ephemeral_members_and_old_runs_are_removed() -> (
+async def test_cell_results_outlive_ephemeral_members_and_old_runs_are_removed() -> (
None
):
clock = Clock()
- host, notebook = host_at(clock)
+ host, notebook = await host_at(clock)
run = notebook.run("code", request_id="first")
ephemeral = plan(notebook, run, "scratch")
cell = plan(notebook, run, "cell", "a")
@@ -465,8 +583,10 @@ def test_cell_results_outlive_ephemeral_members_and_old_runs_are_removed() -> (
assert set(state) == {("run", replacement.id), ("execution", current)}
-def test_run_survives_until_its_last_cell_execution_is_replaced() -> None:
- host, notebook = host_at(Clock())
+async def test_run_survives_until_its_last_cell_execution_is_replaced() -> (
+ None
+):
+ host, notebook = await host_at(Clock())
original = notebook.run("code", request_id="original")
first = plan(notebook, original, "first", "a")
second = plan(notebook, original, "second", "b")
@@ -499,11 +619,11 @@ def test_run_survives_until_its_last_cell_execution_is_replaced() -> None:
]
-def test_stopping_starts_expiry_for_active_work_without_extending_old_results() -> (
+async def test_stopping_starts_expiry_for_active_work_without_extending_old_results() -> (
None
):
clock = Clock()
- host, notebook = host_at(clock)
+ host, notebook = await host_at(clock)
done = notebook.run("code", request_id="done")
execution = plan(notebook, done, "done")
finish(notebook, execution)
@@ -523,9 +643,11 @@ def test_stopping_starts_expiry_for_active_work_without_extending_old_results()
assert fold(host.events(notebook_id=notebook.id)) == {}
-def test_repeated_expiration_releases_runs_and_request_correlations() -> None:
+async def test_repeated_expiration_releases_runs_and_request_correlations() -> (
+ None
+):
clock = Clock()
- host, notebook = host_at(clock, history=2)
+ host, notebook = await host_at(clock, history=2)
for index in range(100):
run = notebook.run("code", request_id=f"request-{index}")
execution = plan(notebook, run, str(index))
@@ -535,14 +657,14 @@ def test_repeated_expiration_releases_runs_and_request_correlations() -> None:
host.expire()
assert fold(host.events(notebook_id=notebook.id)) == {}
assert (
- len({call[1] for call in notebook._backend.calls if call[0] == "run"})
+ len({call[1] for call in notebook.backend.calls if call[0] == "run"})
== 100
)
-def test_removal_listeners_can_read_snapshots() -> None:
+async def test_removal_listeners_can_read_snapshots() -> None:
clock = Clock()
- host, notebook = host_at(clock)
+ host, notebook = await host_at(clock)
run = notebook.run("code", request_id="request")
execution = plan(notebook, run, "execution")
notebook.observe(
@@ -564,11 +686,11 @@ def test_removal_listeners_can_read_snapshots() -> None:
assert [set(state) for state in snapshots] == [set(), set(), set()]
-def test_expiration_does_not_scan_unrelated_outputs(
+async def test_expiration_does_not_scan_unrelated_outputs(
monkeypatch: pytest.MonkeyPatch,
) -> None:
clock = Clock()
- host, notebook = host_at(clock, history=2)
+ host, notebook = await host_at(clock, history=2)
run = notebook.run("code", request_id="request")
for index in range(1000):
execution = plan(notebook, run, str(index))
@@ -597,9 +719,9 @@ def test_expiration_does_not_scan_unrelated_outputs(
assert fold(host.events(notebook_id=notebook.id)) == {}
-def test_completed_scratch_runs_belong_to_the_host() -> None:
+async def test_completed_scratch_runs_belong_to_the_host() -> None:
clock = Clock()
- host, notebook = host_at(clock)
+ host, notebook = await host_at(clock)
run = notebook.run("code", request_id="request")
execution = plan(notebook, run, "scratch")
notebook.observe(
@@ -622,10 +744,10 @@ def test_completed_scratch_runs_belong_to_the_host() -> None:
("execution", execution),
("console", "out"),
}
- assert notebook._backend.calls.count(("forget", run.id)) == 1
+ assert notebook.backend.calls.count(("forget", run.id)) == 1
with pytest.raises(NotFound):
notebook.interrupt(run.id)
clock.now = 10
host.expire()
assert fold(host.events(notebook_id=notebook.id)) == {}
- assert notebook._backend.calls.count(("forget", run.id)) == 1
+ assert notebook.backend.calls.count(("forget", run.id)) == 1
diff --git a/tests/_core/test_notebook.py b/tests/_core/test_notebook.py
index 4d9ae64c85..f041f29179 100644
--- a/tests/_core/test_notebook.py
+++ b/tests/_core/test_notebook.py
@@ -3,6 +3,8 @@
from __future__ import annotations
+from copy import deepcopy
+
import msgspec
import pytest
from dirty_equals import IsDatetime
@@ -11,11 +13,15 @@ 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.errors import Conflict, NoRuntime, NotFound
+from marimo._core.executions import CellExecution
from marimo._core.host import Host
from marimo._core.notebook import Notebook
from marimo._core.protocol import (
+ Analysis,
AttachmentMessage,
+ CellId,
Console,
ConsoleMessage,
Custom,
@@ -43,13 +49,19 @@ from marimo._core.stream import Event
from tests._core.conftest import (
Clock,
ScriptedBackend,
+ capture,
finish,
fold,
host_at,
names,
plan,
+ project,
+ record,
request_ids,
+ restore,
+ retained_execution,
runtime_id_of,
+ snapshot_of,
)
@@ -215,6 +227,7 @@ class TestStop:
assert isinstance(interrupted.execution.outcome, InterruptedOutcome)
assert names(host.events(notebook_id=notebook.id)) == [
"notebook",
+ "document",
"run",
"execution",
"console",
@@ -261,6 +274,7 @@ class TestStop:
assert request_ids(log) == ["stop", "stop"]
assert names(host.events(notebook_id=notebook.id)) == [
"notebook",
+ "document",
"run",
"execution",
"console",
@@ -401,6 +415,7 @@ class TestAdoption:
assert notebook.runtime.marimo_version == "0.26.0"
assert names(host.events(notebook_id=notebook.id)) == [
"notebook",
+ "document",
"runtime",
"run",
"execution",
@@ -1028,11 +1043,11 @@ def _attachment_ids(notebook: Notebook) -> set[str]:
@pytest.mark.parametrize("cleanup", ["expire", "replace", "clear"])
-def test_outputs_follow_their_execution_through_updates_and_removal(
+async def test_outputs_follow_their_execution_through_updates_and_removal(
cleanup: str,
) -> None:
clock = Clock()
- host, notebook = host_at(clock)
+ host, notebook = await host_at(clock)
run = notebook.run("code", request_id="request")
first = plan(notebook, run, "first", "a" if cleanup != "expire" else None)
second = plan(
@@ -1117,3 +1132,201 @@ def test_outputs_follow_their_execution_through_updates_and_removal(
for event, state in zip(live, snapshots, strict=True)
if event.name.endswith(".removed")
)
+
+
[email protected]("run_id", [None, "previous-run"])
+async def test_initial_results_are_published_and_replaced_by_live_execution(
+ run_id: str | None,
+) -> None:
+ retained = retained_execution(run_id=run_id)
+ snapshot = snapshot_of(
+ Document(record().id, [CellSource("c1", "42")], {}),
+ {"c1": retained},
+ )
+ host = Host(operations=[])
+ host.update_project(project())
+ host.add_notebook(record(), lambda _, sink: restore(snapshot, sink=sink))
+ live: list[Event] = []
+ host.subscribe(live.append, notebook_id=record().id)
+ notebook = await host.notebook(record().id)
+ assert notebook.runtime is None
+ expected = {
+ ("execution", retained.execution.id): retained.execution,
+ ("console", retained.outputs[0].id): retained.outputs[0],
+ }
+ assert fold(live) == fold(host.events(notebook_id=notebook.id)) == expected
+ assert names(live) == ["cell", "document", "execution", "console"]
+
+ notebook.start()
+ notebook.observe(be.Running(runtime_id_of(notebook)))
+ run = notebook.run("42", request_id="run")
+ execution_id = plan(notebook, run, "new", cell="c1")
+ state = fold(host.events(notebook_id=notebook.id))
+ assert set(state) == {("run", run.id), ("execution", execution_id)}
+ assert fold(live) == state
+
+
+async def test_current_cell_results_can_seed_another_notebook() -> None:
+ _, notebook = await host_at(Clock())
+ notebook.replace([CellSource("c1", "code")], {})
+ run = notebook.run("code", request_id="request")
+ execution = plan(notebook, run, "cell", "c1")
+ notebook.observe(
+ be.Produced(Console(execution, ItemId("out"), "stdout", 0, "x"))
+ )
+ finish(notebook, execution)
+ notebook.observe(be.Done(run.id, "succeeded"))
+ snapshot = capture(notebook)
+ restored = restore(snapshot)
+ assert capture(restored) == snapshot
+ assert fold(restored._snapshot()) == {
+ key: value
+ for key, value in fold(notebook._snapshot()).items()
+ if key[0] != "run"
+ }
+
+
[email protected]("saved", [False, True])
+def test_snapshot_round_trip_preserves_revisions_outputs_and_analysis(
+ saved: bool,
+) -> None:
+ document = Document(
+ record().id,
+ [CellSource("c1", "42")],
+ {"width": "full"},
+ policy="lazy",
+ saved=saved,
+ analyzer=lambda _: {"c1": Analysis(defs=(), refs=(), errors=())},
+ )
+ # The output belongs to the previous source, and the saved revision can
+ # precede the current one. Neither is rewritten during restoration.
+ document.replace([CellSource("c1", "43")], {"width": "full"})
+ seed = retained_execution(run_id="historical-run")
+ retained = CellExecution(
+ seed.execution,
+ (
+ *seed.outputs,
+ Display(
+ execution_id=seed.execution.id,
+ id=ItemId("display"),
+ seq=1,
+ mimetype="application/json",
+ data='{"values": [1, 2]}',
+ ),
+ replace(seed.outputs[0], id=ItemId("last"), seq=2),
+ ),
+ )
+ snapshot = snapshot_of(document, {"c1": retained})
+ original = deepcopy(snapshot)
+ backend = ScriptedBackend()
+ notebook = restore(snapshot, backend)
+ assert capture(notebook) == original
+ assert capture(restore(capture(notebook), backend)) == original
+ assert backend.calls == []
+ outputs = [
+ e for e in notebook._snapshot() if e.kind in ("console", "display")
+ ]
+ assert [getattr(e.data, e.kind).seq for e in outputs] == [0, 1, 2]
+ # Restoration copies its input, and capture returns detached data.
+ snapshot.document.app_config["width"] = "medium"
+ capture(notebook).document.app_config["width"] = "columns"
+ assert capture(notebook) == original
+
+
+async def test_edits_preserve_results_and_deletion_removes_them() -> None:
+ retained = retained_execution()
+ snapshot = snapshot_of(
+ Document(record().id, [CellSource("c1", "42")], {}),
+ {"c1": retained},
+ )
+ host = Host(operations=[])
+ host.update_project(project())
+ host.add_notebook(record(), lambda _, sink: restore(snapshot, sink=sink))
+ notebook = await host.notebook(record().id)
+ notebook.replace([CellSource("c1", "43")], {})
+ assert notebook.executions.current(CellId("c1")) == retained
+ assert (
+ next(iter(notebook.document)).code_hash != retained.execution.code_hash
+ )
+ live: list[Event] = []
+ host.subscribe(live.append, notebook_id=notebook.id)
+ notebook.replace([], {})
+ assert capture(notebook).cells == ()
+ assert fold(host.events(notebook_id=notebook.id)) == {}
+ assert names(live) == [
+ "console.removed",
+ "execution.removed",
+ "cell.removed",
+ "document",
+ ]
+
+
+async def test_snapshot_excludes_live_work_and_cleans_up_deleted_active_cells() -> (
+ None
+):
+ _, notebook = await host_at(Clock())
+ notebook.replace([CellSource("c1", "code")], {})
+ notebook.attach()
+ run = notebook.run("code", request_id="request")
+ execution = plan(notebook, run, "active", "c1")
+ notebook.observe(
+ be.Produced(Console(execution, ItemId("out"), "stdout", 0, "x"))
+ )
+ snapshot = capture(notebook)
+ assert snapshot.cells[0].execution is None
+ restored = restore(snapshot)
+ assert names(restored._snapshot()) == ["cell", "document"]
+ notebook.replace([], {})
+ finish(notebook, execution)
+ notebook.observe(be.Done(run.id, "succeeded"))
+ assert capture(notebook).cells == ()
+ assert fold(notebook._snapshot()) == {}
+
+
+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")], {})
+ run = notebook.run("42", request_id="run")
+ execution = plan(notebook, run, "result", "c1")
+ notebook.observe(
+ be.Produced(Console(execution, ItemId("out"), "stdout", 0, "hello"))
+ )
+ finish(notebook, execution)
+ notebook.observe(be.Done(run.id, "succeeded"))
+ retained = notebook.executions._records()
+
+ notebook.replace([CellSource("c1", "43")], {})
+ assert notebook.executions._records() == retained
+
+ live: list[Event] = []
+ host.subscribe(live.append, notebook_id=notebook.id)
+ notebook.replace([], {})
+ assert list(notebook.document) == []
+ assert fold(host.events(notebook_id=notebook.id)) == {}
+ assert names(live) == [
+ "console.removed",
+ "execution.removed",
+ "run.removed",
+ "cell.removed",
+ "document",
+ ]
+
+
+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")], {})
+ run = notebook.run("42", request_id="run")
+ execution = plan(notebook, run, "result", "c1")
+ notebook.replace([], {})
+ notebook.observe(
+ be.Produced(Console(execution, ItemId("out"), "stdout", 0, "hello"))
+ )
+ finish(notebook, execution)
+ notebook.observe(be.Done(run.id, "succeeded"))
+ assert list(notebook.document) == []
+ assert fold(notebook._snapshot()) == {}
+ assert fold(host.events(notebook_id=notebook.id)) == {}
diff --git a/tests/_core/test_notebook_document.py b/tests/_core/test_notebook_document.py
new file mode 100644
index 0000000000..c47702f5c1
--- /dev/null
+++ b/tests/_core/test_notebook_document.py
@@ -0,0 +1,339 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""The document's etags, change reporting, and publication order."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+from msgspec.structs import replace
+
+from marimo._core import protocol
+from marimo._core.document import (
+ CellSource,
+ Document,
+ app_config_etag,
+ cell_etag,
+ code_hash,
+ document_etag,
+ order_etag,
+)
+from marimo._core.host import Host
+from marimo._core.notebook import Notebook
+from marimo._core.stream import Event
+from tests._core.conftest import make_notebook, names, project, record
+
+if TYPE_CHECKING:
+ from collections.abc import Mapping
+
+NOTEBOOK = protocol.NotebookId("n1")
+HIDDEN = protocol.CellConfig(
+ column=None, disabled=False, hide_code=True, expand_output=False
+)
+
+
+def fixture_cells() -> list[CellSource]:
+ """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),
+ ]
+
+
+def defs_only(codes: Mapping[str, str]) -> dict[str, protocol.Analysis]:
+ """An analyzer that reports an error on every cell defining `x`."""
+ out = {}
+ definers = [cell_id for cell_id, code in codes.items() if "x =" in code]
+ for cell_id, code in codes.items():
+ errors = []
+ if cell_id in definers and len(definers) > 1:
+ errors.append(
+ protocol.Error(
+ kind="multiple-definitions",
+ message="x is defined twice",
+ source="marimo",
+ severity="error",
+ range=None,
+ name=None,
+ traceback=None,
+ related=[],
+ )
+ )
+ out[cell_id] = protocol.Analysis(
+ defs=[code.split(" =")[0]] if " =" in code else [],
+ refs=[],
+ errors=errors,
+ )
+ return out
+
+
+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
+
+ document.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
+
+ def test_match_the_values_pinned_in_the_fixtures(self) -> None:
+ document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})
+
+ c1, c3, k7f2 = document
+ assert (c3.code_hash, c3.etag) == (
+ "0f71456db2ea83f4",
+ "5cf78587dcf22d8d",
+ )
+ assert (k7f2.code_hash, k7f2.etag) == (
+ "db2b9ee97e1ecf4c",
+ "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"
+
+ def test_are_derived_from_their_parts(self) -> None:
+ hashed = code_hash("x = 21")
+ assert cell_etag(hashed, "_", HIDDEN) != cell_etag(
+ hashed,
+ "_",
+ protocol.CellConfig(
+ column=None,
+ disabled=False,
+ hide_code=False,
+ expand_output=False,
+ ),
+ )
+ assert cell_etag(hashed, "named", HIDDEN) != cell_etag(
+ hashed, "_", HIDDEN
+ )
+ assert order_etag(["a", "b"]) != order_etag(["b", "a"])
+ assert app_config_etag({"b": 1, "a": 2}) == app_config_etag(
+ {"a": 2, "b": 1}
+ )
+ assert document_etag(
+ order_etag(["a"]), app_config_etag({}), [hashed]
+ ) != (document_etag(order_etag(["a"]), app_config_etag({}), []))
+
+ 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")
+
+
+class TestReplace:
+ def test_reports_new_changed_and_removed_cells(self) -> None:
+ document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})
+ before = document._record
+
+ changed = document.replace(
+ [
+ CellSource("c1", "import marimo as mo"),
+ CellSource("new", "z = 3"),
+ CellSource("k7f2", "y = x * 3", config=HIDDEN),
+ ],
+ {"width": "full"},
+ )
+
+ assert [cell.id for cell 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
+
+ def test_a_change_that_changes_nothing_reports_nothing(self) -> None:
+ document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})
+
+ assert not document.replace(fixture_cells(), {"width": "full"})
+
+ def test_an_app_config_change_moves_only_its_etag(self) -> None:
+ document = Document(NOTEBOOK, fixture_cells(), {})
+ before = document._record
+
+ changed = document.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
+
+
+class TestAnalysis:
+ def test_reruns_over_the_whole_document(self) -> None:
+ document = Document(
+ NOTEBOOK,
+ [CellSource("a", "x = 1"), CellSource("b", "y = 2")],
+ {},
+ analyzer=defs_only,
+ )
+ a, _ = document
+ assert a.analysis == protocol.Analysis(defs=["x"], refs=[], errors=[])
+
+ changed = document.replace(
+ [CellSource("a", "x = 1"), CellSource("b", "x = 2")], {}
+ )
+
+ # Both cells re-emit: b because its code changed, a because its
+ # analysis gained an error while its etag stayed put.
+ assert [cell.id for cell in changed.cells] == ["a", "b"]
+ new_a = changed.cells[0]
+ assert new_a.etag == a.etag
+ assert new_a.analysis is not None
+ assert [e.kind for e in new_a.analysis.errors] == [
+ "multiple-definitions"
+ ]
+
+ def test_is_null_without_an_analyzer(self) -> None:
+ document = Document(NOTEBOOK, fixture_cells(), {})
+ assert all(cell.analysis is None for cell in document)
+
+
+class TestFromRecords:
+ def test_preserves_imported_analysis_and_saved_revision(self) -> None:
+ source = Document(
+ NOTEBOOK,
+ fixture_cells(),
+ {"width": "full"},
+ policy="lazy",
+ analyzer=lambda codes: {
+ cell_id: protocol.Analysis(defs=(), refs=(), errors=())
+ for cell_id in codes
+ },
+ )
+ # 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)
+ assert next(iter(restored)).analysis is not None
+
+ @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)
+ if invalid == "order":
+ document = replace(document, order=())
+ elif invalid == "notebook-id":
+ cells[0] = replace(
+ cells[0], notebook_id=protocol.NotebookId("other")
+ )
+ elif invalid == "cell-etag":
+ cells[0] = replace(cells[0], code="different source")
+ else:
+ document = replace(document, app_config={"width": "full"})
+ with pytest.raises(ValueError):
+ Document.from_records(document, cells)
+
+ def test_analyzer_is_injected_for_restoration_and_later_edits(
+ self,
+ ) -> None:
+ observed: list[dict[str, str]] = []
+
+ def analyze(codes: Mapping[str, str]) -> dict[str, protocol.Analysis]:
+ observed.append(dict(codes))
+ return {
+ cell_id: protocol.Analysis(defs=(), refs=(), errors=())
+ for cell_id in codes
+ }
+
+ source = Document(NOTEBOOK, [CellSource("c1", "42")], {})
+ document = Document.from_records(
+ source._record, list(source), analyzer=analyze
+ )
+ document.replace([CellSource("c1", "43")], {})
+ assert observed == [{"c1": "42"}, {"c1": "43"}]
+ assert next(iter(document)).analysis is not None
+
+
+class TestNotebook:
+ async def test_initialization_publishes_cells_then_the_document(
+ self, host: Host, log: list[Event]
+ ) -> None:
+ host.update_project(project())
+ host.add_notebook(
+ record(),
+ lambda record, sink: make_notebook(
+ record,
+ sink,
+ document=Document(
+ NOTEBOOK, fixture_cells(), {"width": "full"}
+ ),
+ ),
+ )
+ log.clear()
+ await host.notebook(NOTEBOOK)
+
+ assert names(log) == ["cell", "cell", "cell", "document"]
+ snapshot = host.events(notebook_id="n1")
+ assert names(snapshot) == [
+ "notebook",
+ "cell",
+ "cell",
+ "cell",
+ "document",
+ "ready",
+ ]
+ assert names(host.events(notebook_id="n1", types={"document"})) == [
+ "document",
+ "ready",
+ ]
+ # The catalog does not carry the document.
+ assert "cell" not in names(host.events())
+
+ def test_replace_publishes_what_changed(
+ self, notebook: Notebook, log: list[Event]
+ ) -> None:
+ notebook.replace(fixture_cells(), {})
+ log.clear()
+
+ notebook.replace(
+ [
+ CellSource("c1", "import marimo as mo"),
+ CellSource("c3", "x = 22"),
+ ],
+ {},
+ request_id="edit-1",
+ )
+
+ assert names(log) == ["cell", "cell.removed", "document"]
+ assert all(e.data.request_id == "edit-1" for e in log) # type: ignore[union-attr]
+ assert log[1].data.id == "k7f2" # type: ignore[union-attr]
diff --git a/tests/_core/test_protocol.py b/tests/_core/test_protocol.py
index d3bb582005..d8f4c6fe4d 100644
--- a/tests/_core/test_protocol.py
+++ b/tests/_core/test_protocol.py
@@ -99,7 +99,7 @@ def assert_content_hashes(value: Any) -> None:
assert value["etag"] == content_hash("\n".join(parts))
if "order_etag" in value:
assert value["order_etag"] == content_hash(
- "\n".join(value["order"])
+ canonical_json(value["order"])
)
assert value["app_config_etag"] == content_hash(
canonical_json(value["app_config"])
diff --git a/tests/_server/host/conftest.py b/tests/_server/host/conftest.py
index d2d18198d7..cdefd250af 100644
--- a/tests/_server/host/conftest.py
+++ b/tests/_server/host/conftest.py
@@ -32,10 +32,15 @@ class FakeSession:
self.exit_info: Any = None
self.app_file_manager = MagicMock()
self.app_file_manager.path = path
+ self.app_file_manager.app.config.asdict_difference.return_value = {}
self.document = MagicMock()
self.document.cell_ids = []
self.document.cells = []
self.session_view = MagicMock()
+ self.config_manager = MagicMock()
+ self.config_manager.get_config.return_value = {
+ "runtime": {"on_cell_change": "autorun"}
+ }
def connect_consumer(
self, consumer: SessionConsumer, *, main: bool
diff --git a/tests/_server/host/test_host_analysis.py b/tests/_server/host/test_host_analysis.py
new file mode 100644
index 0000000000..a6733fa25e
--- /dev/null
+++ b/tests/_server/host/test_host_analysis.py
@@ -0,0 +1,86 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""The host's analyzer reports each cell's names and syntax errors."""
+
+from __future__ import annotations
+
+import pytest
+
+from marimo._core import protocol
+from marimo._server.host.analysis import Analyzer, analyze
+
+
+def test_refs_are_names_other_cells_define() -> None:
+ analyses = analyze(
+ {
+ "a": "import marimo as mo\nprint(len(x))",
+ "b": "x = 21",
+ "c": "y = x * 2",
+ }
+ )
+ assert analyses["a"].defs == ("mo",)
+ assert analyses["a"].refs == ("x",)
+ assert analyses["b"] == protocol.Analysis(defs=("x",), refs=(), errors=())
+ assert analyses["c"].refs == ("x",)
+
+
+def test_a_name_defined_twice_is_a_ref_for_neither_definer() -> None:
+ analyses = analyze({"a": "x = 1", "b": "x = 2\ny = x", "c": "z = x"})
+ assert analyses["b"].refs == ()
+ assert analyses["c"].refs == ("x",)
+ # Cross-cell errors come from the kernel at run time for now.
+ assert all(analyses[cell_id].errors == () for cell_id in "abc")
+
+
+def test_syntax_errors_leave_the_cell_without_names() -> None:
+ analyses = analyze({"a": "def (:", "b": "x = 1"})
+
+ (error,) = analyses["a"].errors
+ assert error.kind == "invalid-syntax"
+ assert error.source == "marimo"
+ assert error.range is not None
+ assert error.range.start.line == 0
+ assert analyses["a"].defs == ()
+ assert analyses["a"].refs == ()
+ assert analyses["b"].errors == ()
+
+
+def test_positions_count_utf16_code_units() -> None:
+ analyses = analyze({"a": "s = '😀'; def (:"})
+
+ (error,) = analyses["a"].errors
+ assert error.range is not None
+ # Python reports the error at `def`, code point 9. The emoji before it
+ # is one code point but two UTF-16 units, so LSP sees it at 10.
+ assert error.range.start.character == 10
+
+
+def test_an_analyzer_kept_between_edits_matches_a_fresh_one() -> None:
+ analyzer = Analyzer()
+ steps = [
+ {"a": "x = 1", "b": "y = x"},
+ {"a": "x = 1", "b": "y = x", "c": "x = 2"},
+ {"a": "x = 1", "b": "y = x", "c": "z = y"},
+ {"a": "x = 1", "b": "y = x\nw = z", "c": "z = y"},
+ {"b": "y = x\nw = z", "c": "z = y"},
+ {"b": "def (:", "c": "z = y"},
+ ]
+ for codes in steps:
+ assert analyzer(codes) == analyze(codes), codes
+
+
+def test_analyzer_retries_after_an_unexpected_compiler_failure(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ analyzer = Analyzer()
+ analyzer({"a": "x = 1"})
+ codes = {"a": "y = 2", "b": "z = y"}
+
+ def fail(*_args: object, **_kwargs: object) -> None:
+ raise RuntimeError("compiler failed")
+
+ with monkeypatch.context() as patch:
+ patch.setattr("marimo._server.host.analysis.compile_cell", fail)
+ with pytest.raises(RuntimeError, match="compiler failed"):
+ analyzer(codes)
+
+ assert analyzer(codes) == analyze(codes)
diff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.py
index 82d4a33b79..4b64c2b822 100644
--- a/tests/_server/host/test_host_api.py
+++ b/tests/_server/host/test_host_api.py
@@ -25,7 +25,7 @@ from marimo._server.host.index import WorkspaceIndex
from marimo._server.main import create_starlette_app
from marimo._server.models.home import MarimoFile
from marimo._server.workspace import FixedFilesWorkspace, SingleFileWorkspace
-from tests._core.conftest import ScriptedBackend, runtime_id_of
+from tests._core.conftest import ScriptedBackend, make_notebook, runtime_id_of
from tests._server.host.drive import (
PORT,
finished,
@@ -84,17 +84,24 @@ class Harness:
body=b"{}",
)
assert response.status == 202, response.body
- self.host.notebook(self.notebook_id).observe(
+ (await self.host.notebook(self.notebook_id)).observe(
be.Running(
- runtime_id_of(self.host.notebook(self.notebook_id)), "0.25.0"
+ runtime_id_of(await self.host.notebook(self.notebook_id)),
+ "0.25.0",
)
)
return self.notebook_id
@pytest.fixture
-def harness(tmp_path: Path, request: pytest.FixtureRequest) -> Harness:
- (tmp_path / "forecasts.py").write_text("import marimo\n")
+def harness(
+ tmp_path: Path,
+ request: pytest.FixtureRequest,
+ monkeypatch: pytest.MonkeyPatch,
+) -> Harness:
+ (tmp_path / "forecasts.py").write_text(
+ "import marimo\napp = marimo.App()\n"
+ )
workspace = FixedFilesWorkspace(
[MarimoFile(name="forecasts.py", path=str(tmp_path / "forecasts.py"))],
directory=str(tmp_path),
@@ -111,7 +118,10 @@ def harness(tmp_path: Path, request: pytest.FixtureRequest) -> Harness:
harness.backends[notebook_id] = backend
return backend
- bridge.index = WorkspaceIndex(bridge.host, workspace, make)
+ monkeypatch.setattr(bridge, "_make_backend", make)
+ bridge.index = WorkspaceIndex(
+ bridge.host, workspace, bridge._initialize_notebook
+ )
bridge.index.refresh()
app.state.host_context = HostContext(
bridge=bridge,
@@ -341,7 +351,7 @@ async def test_an_empty_update_is_a_400_problem(harness: Harness) -> None:
async def test_head_on_a_stream_is_a_405_and_attaches_nothing(
harness: Harness,
) -> None:
- notebook = harness.host.notebook(harness.notebook_id)
+ notebook = await harness.host.notebook(harness.notebook_id)
before = len(notebook._attachments)
response = await finished(
harness.app, "HEAD", f"/notebooks/{notebook.id}/events", headers=AUTH
@@ -378,7 +388,7 @@ async def test_the_catalog_stream_sends_a_snapshot_then_changes(
assert "id" not in response.records[0]
cursor = int(response.records[-1]["id"])
- notebook = harness.host.notebook(harness.notebook_id)
+ notebook = await harness.host.notebook(harness.notebook_id)
notebook.start()
await wait_for(response, lambda r: r.names()[-1] == "runtime")
live = response.records[-1]
@@ -440,7 +450,7 @@ async def test_types_and_cursors_apply_to_the_stream(harness: Harness) -> None:
cursor = first.records[-1]["id"]
disconnect()
- harness.host.notebook(harness.notebook_id).start()
+ (await harness.host.notebook(harness.notebook_id)).start()
resumed, _, disconnect = request(
harness.app,
"GET",
@@ -458,18 +468,30 @@ async def test_types_and_cursors_apply_to_the_stream(harness: Harness) -> None:
async def test_a_notebook_stream_attaches_the_client(harness: Harness) -> None:
- notebook = harness.host.notebook(harness.notebook_id)
+ notebook = await harness.host.notebook(harness.notebook_id)
response, task, disconnect = request(
harness.app, "GET", f"/notebooks/{notebook.id}/events", headers=AUTH
)
await wait_for(response, until_ready)
- assert response.names() == ["notebook", "attachment", "ready"]
- assert response.records[1]["data"]["attachment"]["kind"] == "client"
+ # An empty notebook loads with marimo's one default cell.
+ assert response.names() == [
+ "notebook",
+ "cell",
+ "document",
+ "attachment",
+ "ready",
+ ]
+ assert response.records[2]["data"]["document"]["order"] == [
+ response.records[1]["data"]["cell"]["id"]
+ ]
+ assert response.records[3]["data"]["attachment"]["kind"] == "client"
disconnect()
await asyncio.wait_for(task, 5)
assert [e.name for e in harness.host.events(notebook_id=notebook.id)] == [
"notebook",
+ "cell",
+ "document",
"ready",
]
@@ -557,7 +579,7 @@ async def test_a_reconnect_with_one_identity_attaches_fresh(
async def test_custom_events_use_their_own_sse_kind(
harness: Harness,
) -> None:
- notebook = harness.host.notebook(harness.notebook_id)
+ notebook = await harness.host.notebook(harness.notebook_id)
path = f"/notebooks/{notebook.id}/events"
custom, custom_task, disconnect_custom = request(
harness.app, "GET", path, headers=AUTH, query="types=custom"
@@ -622,19 +644,19 @@ async def test_runtime_lifecycle_over_http(harness: Harness) -> None:
assert restart.status == 409
assert restart.json()["type"].endswith("/conflict")
- harness.host.notebook(nid).observe(
- be.Running(runtime_id_of(harness.host.notebook(nid)), "0.25.0")
+ (await harness.host.notebook(nid)).observe(
+ be.Running(runtime_id_of(await harness.host.notebook(nid)), "0.25.0")
)
restart = await finished(app, "POST", path + "/restart", headers=key("k4"))
assert restart.status == 202
assert restart.json()["status"] == "starting"
assert restart.json()["id"] != started.json()["id"]
- harness.host.notebook(nid).observe(
- be.Exited(runtime_id_of(harness.host.notebook(nid)))
+ (await harness.host.notebook(nid)).observe(
+ be.Exited(runtime_id_of(await harness.host.notebook(nid)))
)
- harness.host.notebook(nid).observe(
- be.Running(runtime_id_of(harness.host.notebook(nid)), "0.25.0")
+ (await harness.host.notebook(nid)).observe(
+ be.Running(runtime_id_of(await harness.host.notebook(nid)), "0.25.0")
)
stopped = await finished(app, "DELETE", path, headers=key("k5"))
assert stopped.status == 202
@@ -642,8 +664,8 @@ async def test_runtime_lifecycle_over_http(harness: Harness) -> None:
assert stopped.json()["id"] != started.json()["id"]
assert stopped.json()["id"] == restart.json()["id"]
- harness.host.notebook(nid).observe(
- be.Exited(runtime_id_of(harness.host.notebook(nid)))
+ (await harness.host.notebook(nid)).observe(
+ be.Exited(runtime_id_of(await harness.host.notebook(nid)))
)
gone = await finished(app, "DELETE", path, headers=key("k6"))
assert gone.status == 409
@@ -652,7 +674,7 @@ async def test_runtime_lifecycle_over_http(harness: Harness) -> None:
async def test_slow_restart_keeps_its_receipt(harness: Harness) -> None:
nid = await harness.running()
- notebook = harness.host.notebook(nid)
+ notebook = await harness.host.notebook(nid)
path = f"/notebooks/{nid}/runtime/restart"
accepted = await finished(
harness.app, "POST", path, headers=key("restart")
@@ -702,7 +724,7 @@ async def test_lifecycle_receipts_expire_after_terminal_events(
nid = harness.notebook_id
if operation != "start":
await harness.running()
- notebook = harness.host.notebook(nid)
+ notebook = await harness.host.notebook(nid)
context = harness.app.state.host_context
listeners = list(harness.host._stream._listeners)
method = {"start": "PUT", "stop": "DELETE", "restart": "POST"}[operation]
@@ -758,7 +780,7 @@ async def test_stop_settles_superseded_lifecycle_receipts(
nid = harness.notebook_id
if operation != "start":
await harness.running()
- notebook = harness.host.notebook(nid)
+ notebook = await harness.host.notebook(nid)
context = harness.app.state.host_context
listeners = list(harness.host._stream._listeners)
path = f"/notebooks/{nid}/runtime"
@@ -811,7 +833,7 @@ async def test_synchronous_lifecycle_completion(
nid = harness.notebook_id
if operation != "start":
await harness.running()
- notebook = harness.host.notebook(nid)
+ notebook = await harness.host.notebook(nid)
if operation == "failed-stop":
notebook.observe(be.Exited(runtime_id_of(notebook), "failed"))
backend = harness.backend()
@@ -875,7 +897,7 @@ async def test_noop_and_rejected_lifecycle_requests_release_their_listeners(
async def test_run_filter_over_http(harness: Harness) -> None:
nid = await harness.running()
- notebook = harness.host.notebook(nid)
+ notebook = await harness.host.notebook(nid)
first = notebook.run("1", request_id="first")
notebook.observe(
be.Planned(
@@ -923,7 +945,7 @@ async def test_interrupting_an_unstarted_run_after_shutdown(
)
assert accepted.status == 202
run_id = accepted.json()["id"]
- notebook = harness.host.notebook(nid)
+ notebook = await harness.host.notebook(nid)
runtime_id = runtime_id_of(notebook)
notebook.stop()
notebook.observe(be.Exited(runtime_id))
@@ -968,7 +990,7 @@ async def test_scratch_runs_over_http(harness: Harness) -> None:
assert repeated.status == 202
assert repeated.body == accepted.body
assert harness.backend().calls.count(("run", run_id, "3 * 3")) == 1
- notebook = harness.host.notebook(nid)
+ notebook = await harness.host.notebook(nid)
notebook.observe(
be.Planned(run_id, (be.PlannedExecution("e1", None, "hash", "3 * 3"),))
)
@@ -1025,7 +1047,7 @@ async def test_request_receipts_expire_independently_of_results(
harness: Harness, cell_id: str | None
) -> None:
nid = await harness.running()
- notebook = harness.host.notebook(nid)
+ notebook = await harness.host.notebook(nid)
path = f"/notebooks/{nid}/runtime/runs"
body = b'{"code":"42"}'
accepted = await finished(
@@ -1290,7 +1312,7 @@ async def test_open_selects_the_notebook_outside_the_working_directory(
async def test_operations_the_host_does_not_offer_are_501(
harness: Harness,
) -> None:
- notebook = harness.host.notebook(harness.notebook_id)
+ notebook = await harness.host.notebook(harness.notebook_id)
host = Host(operations=[])
[project] = [
e.data.project
@@ -1298,7 +1320,7 @@ async def test_operations_the_host_does_not_offer_are_501(
if isinstance(e.data, ProjectMessage)
]
host.update_project(project)
- host.add_notebook(harness.host.notebooks[notebook.id], harness.backend())
+ host.add_notebook(harness.host.notebooks[notebook.id], make_notebook)
harness.bridge.host = host
response = await finished(
harness.app,
@@ -1380,3 +1402,121 @@ async def test_symlink_escape_has_no_filesystem_side_effects(
assert [n.path for n in harness.host.notebooks.values()] == [
"forecasts.py"
]
+
+
+NOTEBOOK = """import marimo
+
+__generated_with = "0.0.0"
+app = marimo.App(width="full")
+
+
+def _():
+ x = 21
+ return (x,)
+
+
[email protected](hide_code=True)
+def _(x):
+ y = x * 2
+ return
+
+
+if __name__ == "__main__":
+ app.run()
+"""
+
+
+async def test_the_notebook_stream_carries_cells_then_the_document(
+ harness: Harness,
+) -> None:
+ (harness.root / "forecasts.py").write_text(NOTEBOOK)
+ response, _, disconnect = request(
+ harness.app,
+ "GET",
+ f"/notebooks/{harness.notebook_id}/events",
+ headers=AUTH,
+ )
+ await wait_for(response, until_ready)
+ disconnect()
+
+ assert response.names() == [
+ "notebook",
+ "cell",
+ "cell",
+ "document",
+ "attachment",
+ "ready",
+ ]
+ first, second = (r["data"]["cell"] for r in response.records[1:3])
+ document = response.records[3]["data"]["document"]
+ assert first["code"] == "x = 21"
+ assert first["analysis"] == {"defs": ["x"], "refs": [], "errors": []}
+ assert second["code"] == "y = x * 2"
+ assert second["config"]["hide_code"] is True
+ assert second["analysis"]["refs"] == ["x"]
+ assert document["order"] == [first["id"], second["id"]]
+ assert document["app_config"] == {"width": "full"}
+ assert document["policy"] == "autorun"
+ assert document["saved_etag"] == document["etag"]
+ assert all(
+ c["notebook_id"] == harness.notebook_id for c in (first, second)
+ )
+
+ # A filtered stream is a snapshot of the document alone, and a second
+ # connection reuses the loaded document.
+ response, _, disconnect = request(
+ harness.app,
+ "GET",
+ f"/notebooks/{harness.notebook_id}/events",
+ headers=AUTH,
+ query="types=cell,document",
+ )
+ await wait_for(response, until_ready)
+ disconnect()
+ assert response.names() == ["cell", "cell", "document", "ready"]
+ assert response.records[2]["data"]["document"] == document
+
+
+async def test_an_unreadable_notebook_stays_in_the_catalog_and_can_retry(
+ harness: Harness,
+) -> None:
+ file = harness.root / "forecasts.py"
+ file.write_text("print('not a notebook')\n")
+ notebook_id = harness.notebook_id
+
+ response = await finished(
+ harness.app,
+ "GET",
+ f"/notebooks/{notebook_id}/events",
+ headers=AUTH,
+ )
+ assert response.status == 409
+ assert harness.host.peek_notebook(notebook_id) is None
+ assert notebook_id in harness.host.notebooks
+ assert harness.backends == {}
+
+ file.write_text(NOTEBOOK)
+ notebook = await harness.host.notebook(notebook_id)
+ assert [cell.code for cell in notebook.document] == [
+ "x = 21",
+ "y = x * 2",
+ ]
+
+
+async def test_deleting_an_unreadable_notebook_does_not_initialize_it(
+ harness: Harness,
+) -> None:
+ file = harness.root / "forecasts.py"
+ file.write_text("print('not a notebook')\n")
+ notebook_id = harness.notebook_id
+ response = await finished(
+ harness.app,
+ "DELETE",
+ f"/notebooks/{notebook_id}",
+ headers=key("delete-unreadable"),
+ )
+ assert response.status == 204
+ assert notebook_id not in harness.host.notebooks
+ assert not file.exists()
+ assert harness.backends == {}
diff --git a/tests/_server/host/test_host_bridge.py b/tests/_server/host/test_host_bridge.py
index ded6f6051a..7b96cbfc11 100644
--- a/tests/_server/host/test_host_bridge.py
+++ b/tests/_server/host/test_host_bridge.py
@@ -3,10 +3,12 @@
from __future__ import annotations
+import asyncio
from typing import TYPE_CHECKING
import pytest
+from marimo._config.manager import MarimoConfigManager
from marimo._core import protocol
from marimo._core.errors import Conflict
from marimo._core.stream import Event
@@ -24,7 +26,10 @@ from tests._server.host.conftest import FakeManager, FakeSession
if TYPE_CHECKING:
from pathlib import Path
+ from typing import Any
+ from marimo._config.manager import UserConfigStore
+ from marimo._core.document import CellSource, Policy
from marimo._session.consumer import SessionConsumer
@@ -36,6 +41,130 @@ def prepare(manager: FakeManager, root: Path, *names: str) -> None:
manager.workspace = FixedFilesWorkspace(files, directory=str(root))
+NOTEBOOK = """import marimo
+
+__generated_with = "0.0.0"
+app = marimo.App()
+
+def _():
+ x = 1
+ return (x,)
+"""
+
+
+ ("server_policy", "script_policy", "expected"),
+ [
+ ("autorun", None, "autorun"),
+ ("lazy", None, "lazy"),
+ ("autorun", "lazy", "lazy"),
+ ("lazy", "autorun", "autorun"),
+ ],
+)
+async def test_initial_policy_inherits_server_config_with_script_overrides(
+ manager: FakeManager,
+ tmp_path: Path,
+ user_config_manager: UserConfigStore,
+ server_policy: Policy,
+ script_policy: Policy | None,
+ expected: Policy,
+) -> None:
+ prepare(manager, tmp_path, "a.py")
+ path = tmp_path / "a.py"
+ header = (
+ "# /// script\n"
+ "# [tool.marimo.runtime]\n"
+ f'# on_cell_change = "{script_policy}"\n'
+ "# ///\n"
+ if script_policy is not None
+ else ""
+ )
+ path.write_text(header + NOTEBOOK)
+ config = MarimoConfigManager(user_config_manager).with_overrides(
+ {"runtime": {"on_cell_change": server_policy}}
+ )
+ bridge = SessionBridge(manager, config) # type: ignore[arg-type]
+ await bridge.open()
+ record = bridge.index.notebook_for(str(path))
+ assert record is not None
+
+ notebook = await bridge.host.notebook(record.id)
+
+ assert notebook.document._record.policy == expected
+ assert notebook.runtime is None
+ assert manager.starts == []
+ bridge.close()
+
+
+async def test_initial_policy_uses_the_adopted_sessions_effective_config(
+ manager: FakeManager,
+ tmp_path: Path,
+ user_config_manager: UserConfigStore,
+) -> None:
+ prepare(manager, tmp_path, "a.py")
+ path = tmp_path / "a.py"
+ path.write_text(NOTEBOOK)
+ config = MarimoConfigManager(user_config_manager).with_overrides(
+ {"runtime": {"on_cell_change": "autorun"}}
+ )
+ session = FakeSession(str(path))
+ session.config_manager = config.with_overrides(
+ {"runtime": {"on_cell_change": "lazy"}}
+ )
+ manager.sessions["browser"] = session
+ bridge = SessionBridge(manager, config) # type: ignore[arg-type]
+
+ await bridge.open()
+
+ record = bridge.index.notebook_for(str(path))
+ assert record is not None
+ notebook = await bridge.host.notebook(record.id)
+ assert notebook.document._record.policy == "lazy"
+ assert notebook.runtime is not None
+ bridge.close()
+
+
+async def test_an_adopted_document_is_saved_as_far_as_the_file_goes(
+ manager: FakeManager, tmp_path: Path
+) -> None:
+ from marimo._messaging.notebook import SetCode, Transaction
+ from marimo._session.notebook import AppFileManager
+
+ prepare(manager, tmp_path, "saved.py", "edited.py")
+ sessions = {}
+ for name in ("saved.py", "edited.py"):
+ path = tmp_path / name
+ path.write_text(NOTEBOOK)
+ session = FakeSession(str(path))
+ session.document = AppFileManager(str(path)).app.cell_manager.document
+ session.app_file_manager.app.config.asdict_difference.return_value = {}
+ sessions[name] = manager.sessions[name] = session
+ edited = sessions["edited.py"].document
+ edited.apply(
+ Transaction(
+ changes=(SetCode(edited.cell_ids[0], "x = 2"),), source="frontend"
+ )
+ )
+ bridge = SessionBridge(manager) # type: ignore[arg-type]
+ await bridge.open()
+
+ documents = {}
+ 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
+
+ # A session showing the file as it is on disk is saved.
+ assert documents["saved.py"].saved_etag == documents["saved.py"].etag
+ # 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
+ bridge.close()
+
+
async def test_sessions_present_and_created_are_adopted(
manager: FakeManager, tmp_path: Path
) -> None:
@@ -44,11 +173,11 @@ async def test_sessions_present_and_created_are_adopted(
manager.sessions["browser-1"] = existing
bridge = SessionBridge(manager) # type: ignore[arg-type]
- bridge.open()
+ await bridge.open()
a = bridge.index.notebook_for(str(tmp_path / "a.py"))
assert a is not None
- runtime = bridge.host.notebook(a.id).runtime
+ runtime = (await bridge.host.notebook(a.id)).runtime
assert runtime is not None
assert runtime.status == "running"
assert existing.consumers[0][1] is False
@@ -57,7 +186,7 @@ async def test_sessions_present_and_created_are_adopted(
await manager.event_bus.emit_session_created(created) # type: ignore[arg-type]
b = bridge.index.notebook_for(str(tmp_path / "b.py"))
assert b is not None
- assert bridge.host.notebook(b.id).runtime is not None
+ assert (await bridge.host.notebook(b.id)).runtime is not None
unknown = FakeSession(str(tmp_path.parent / "elsewhere.py"))
await manager.event_bus.emit_session_created(unknown) # type: ignore[arg-type]
@@ -65,15 +194,72 @@ async def test_sessions_present_and_created_are_adopted(
bridge.close()
+async def test_delete_during_adoption_preserves_the_file_and_session(
+ manager: FakeManager,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ prepare(manager, tmp_path, "a.py")
+ path = tmp_path / "a.py"
+ path.write_text(NOTEBOOK)
+ bridge = SessionBridge(manager) # type: ignore[arg-type]
+ await bridge.open()
+ record = bridge.index.notebook_for(str(path))
+ assert record is not None
+ session = FakeSession(str(path))
+ started, release, deleting = (
+ asyncio.Event(),
+ asyncio.Event(),
+ asyncio.Event(),
+ )
+ load = bridge._load
+
+ async def paused_load(
+ file: Path,
+ ) -> tuple[list[CellSource], dict[str, Any]] | None:
+ started.set()
+ await release.wait()
+ return await load(file)
+
+ async def delete() -> None:
+ deleting.set()
+ await bridge.delete(record.id, request_id="delete")
+
+ monkeypatch.setattr(bridge, "_load", paused_load)
+ adoption = asyncio.create_task(
+ manager.event_bus.emit_session_created(session) # type: ignore[arg-type]
+ )
+ await asyncio.wait_for(started.wait(), 5)
+ deletion = asyncio.create_task(delete())
+ try:
+ # Queue deletion on the file lock before initialization finishes.
+ await asyncio.wait_for(deleting.wait(), 5)
+ release.set()
+ with pytest.raises(Conflict, match="runtime"):
+ await asyncio.wait_for(deletion, 5)
+ await asyncio.wait_for(adoption, 5)
+
+ notebook = await bridge.host.notebook(record.id)
+ assert notebook.runtime is not None
+ assert notebook.runtime.status == "running"
+ assert path.read_text() == NOTEBOOK
+ assert bridge._backends[record.id].session is session
+ assert not session.closed
+ finally:
+ release.set()
+ await asyncio.gather(adoption, deletion, return_exceptions=True)
+ bridge.close()
+
+
async def test_a_subscriber_can_stop_an_adopted_session(
manager: FakeManager, tmp_path: Path
) -> None:
prepare(manager, tmp_path, "a.py")
bridge = SessionBridge(manager) # type: ignore[arg-type]
- bridge.open()
+ await bridge.open()
record = bridge.index.notebook_for(str(tmp_path / "a.py"))
assert record is not None
- notebook = bridge.host.notebook(record.id)
+ notebook = await bridge.host.notebook(record.id)
session = FakeSession(str(tmp_path / "a.py"))
manager.sessions["browser"] = session
@@ -105,10 +291,10 @@ async def test_failed_adoption_detaches_without_closing_the_session(
) -> None:
prepare(manager, tmp_path, "a.py")
bridge = SessionBridge(manager) # type: ignore[arg-type]
- bridge.open()
+ await bridge.open()
record = bridge.index.notebook_for(str(tmp_path / "a.py"))
assert record is not None
- notebook = bridge.host.notebook(record.id)
+ notebook = await bridge.host.notebook(record.id)
session = FakeSession(str(tmp_path / "a.py"))
connect = session.connect_consumer
@@ -148,7 +334,7 @@ async def test_a_rename_keeps_the_notebook_id(
) -> None:
prepare(manager, tmp_path, "a.py")
bridge = SessionBridge(manager) # type: ignore[arg-type]
- bridge.open()
+ await bridge.open()
notebook = bridge.index.notebook_for(str(tmp_path / "a.py"))
assert notebook is not None
(tmp_path / "a.py").rename(tmp_path / "renamed.py")
@@ -172,10 +358,10 @@ async def test_session_updates_after_catalog_removal_are_ignored(
session = FakeSession(str(tmp_path / "a.py"))
manager.sessions["browser"] = session
bridge = SessionBridge(manager) # type: ignore[arg-type]
- bridge.open()
+ await bridge.open()
record = bridge.index.notebook_for(str(tmp_path / "a.py"))
assert record is not None
- notebook = bridge.host.notebook(record.id)
+ notebook = await bridge.host.notebook(record.id)
bridge.index.forget(record.id)
cursor = bridge.host.events()[-1].id
assert cursor is not None
@@ -202,7 +388,7 @@ async def test_removed_runs_release_backend_translation_state(
bridge = SessionBridge(manager) # type: ignore[arg-type]
now = 0.0
bridge.host.clock = lambda: now
- bridge.open()
+ await bridge.open()
record = bridge.index.notebook_for(str(tmp_path / "a.py"))
assert record is not None
backend = bridge._backends[record.id]
@@ -242,10 +428,10 @@ async def test_failed_session_move_preserves_the_notebook(
session = FakeSession(str(source))
manager.sessions["browser"] = session
bridge = SessionBridge(manager) # type: ignore[arg-type]
- bridge.open()
+ await bridge.open()
notebook = bridge.index.notebook_for(str(source))
assert notebook is not None
- runtime = bridge.host.notebook(notebook.id).runtime
+ runtime = (await bridge.host.notebook(notebook.id)).runtime
async def rename(_session_id: str, _path: str) -> tuple[bool, str | None]:
return False, "The notebook is busy"
@@ -256,5 +442,5 @@ async def test_failed_session_move_preserves_the_notebook(
assert source.exists()
assert not target.exists()
assert bridge.host.notebooks[notebook.id].path == "a.py"
- assert bridge.host.notebook(notebook.id).runtime is runtime
+ assert (await bridge.host.notebook(notebook.id)).runtime is runtime
bridge.close()
diff --git a/tests/_server/host/test_host_execution.py b/tests/_server/host/test_host_execution.py
index 9d415096b2..44f461b67c 100644
--- a/tests/_server/host/test_host_execution.py
+++ b/tests/_server/host/test_host_execution.py
@@ -4,12 +4,12 @@
from __future__ import annotations
import asyncio
-import hashlib
import json
from typing import TYPE_CHECKING
import pytest
+from marimo._core.document import code_hash
from marimo._server.host.bridge import SessionBridge
from marimo._server.host.context import HostContext
from marimo._server.main import create_starlette_app
@@ -63,7 +63,7 @@ async def live_host(
app = create_starlette_app(base_url="", enable_auth=True)
get_starlette_server_state_init(session_manager=manager).apply(app.state)
bridge = SessionBridge(manager)
- bridge.open()
+ await bridge.open()
app.state.host_context = HostContext(
bridge=bridge, token="execution-test", port=PORT
)
@@ -100,7 +100,7 @@ async def test_move_preserves_the_running_notebook(
) -> None:
app, notebook_id, events = live_host
host = app.state.host_context.bridge.host
- runtime = host.notebook(notebook_id).runtime
+ runtime = (await host.notebook(notebook_id)).runtime
source, target = tmp_path / "notebook.py", tmp_path / "moved.py"
session = next(iter(app.state.session_manager.sessions.values()))
cells = list(session.app_file_manager.app.cell_manager.codes())
@@ -120,7 +120,7 @@ async def test_move_preserves_the_running_notebook(
assert not source.exists()
assert list(AppFileManager(str(target)).app.cell_manager.codes()) == cells
assert session.app_file_manager.path == str(target)
- assert host.notebook(notebook_id).runtime == runtime
+ assert (await host.notebook(notebook_id)).runtime == runtime
accepted = await finished(
app,
@@ -709,8 +709,8 @@ async def test_a_fixed_cell_replaces_its_failed_compilation(
and r["data"]["execution"]["status"] == "completed"
]
assert [(e["code_hash"], e["outcome"]["kind"]) for e in executions] == [
- (hashlib.sha256(b"if !!!").hexdigest(), "error"),
- (hashlib.sha256(b"x = 42").hexdigest(), "value"),
+ (code_hash("if !!!"), "error"),
+ (code_hash("x = 42"), "value"),
]
assert len({e["id"] for e in executions}) == 2
runs = [
@@ -828,9 +828,7 @@ async def test_awaited_commands_join_the_enclosing_run(
assert root["outcome"]["kind"] == "value"
assert "42" in root["outcome"]["display"]["data"]
assert child["outcome"]["kind"] == "error"
- assert (
- child["code_hash"] == hashlib.sha256(child_code.encode()).hexdigest()
- )
+ assert child["code_hash"] == code_hash(child_code)
assert all(e["run_id"] == accepted.json()["id"] for e in executions)
diff --git a/tests/_server/host/test_host_index.py b/tests/_server/host/test_host_index.py
index 936a19eeba..e653ad779b 100644
--- a/tests/_server/host/test_host_index.py
+++ b/tests/_server/host/test_host_index.py
@@ -16,7 +16,12 @@ from marimo._core.stream import Event
from marimo._server.host.index import WorkspaceIndex
from marimo._server.models.home import MarimoFile
from marimo._server.workspace import FixedFilesWorkspace
-from tests._core.conftest import ScriptedBackend, names, runtime_id_of
+from tests._core.conftest import (
+ ScriptedBackend,
+ make_notebook,
+ names,
+ runtime_id_of,
+)
def workspace(root: Path, *names: str) -> FixedFilesWorkspace:
@@ -37,7 +42,7 @@ def test_refresh_publishes_the_project_and_its_notebooks(
index = WorkspaceIndex(
host,
workspace(tmp_path, "a.py", "sub/b.py"),
- lambda _: ScriptedBackend(),
+ make_notebook,
)
index.refresh()
@@ -61,9 +66,7 @@ def test_refresh_publishes_the_project_and_its_notebooks(
def test_ids_survive_a_rescan_and_a_move(tmp_path: Path) -> None:
host = Host(operations=[])
- index = WorkspaceIndex(
- host, workspace(tmp_path, "a.py"), lambda _: ScriptedBackend()
- )
+ index = WorkspaceIndex(host, workspace(tmp_path, "a.py"), make_notebook)
index.refresh()
(notebook,) = host.notebooks.values()
log: list[Event] = []
@@ -84,10 +87,10 @@ def test_ids_survive_a_rescan_and_a_move(tmp_path: Path) -> None:
assert index.file_of(notebook.id) == tmp_path / "b.py"
-def test_a_deleted_file_leaves_the_catalog(tmp_path: Path) -> None:
+async def test_a_deleted_file_leaves_the_catalog(tmp_path: Path) -> None:
host = Host(operations=[])
ws = workspace(tmp_path, "a.py", "b.py")
- index = WorkspaceIndex(host, ws, lambda _: ScriptedBackend())
+ index = WorkspaceIndex(host, ws, make_notebook)
index.refresh()
removed = index.notebook_for(str(tmp_path / "b.py"))
assert removed is not None
@@ -99,7 +102,7 @@ def test_a_deleted_file_leaves_the_catalog(tmp_path: Path) -> None:
assert [n.path for n in host.notebooks.values()] == ["a.py"]
with pytest.raises(NotFound):
- host.notebook(removed.id)
+ (await host.notebook(removed.id))
(tmp_path / "b.py").write_text("import marimo\n")
recreated = index.ensure(str(tmp_path / "b.py"))
@@ -110,9 +113,7 @@ def test_a_deleted_file_leaves_the_catalog(tmp_path: Path) -> None:
def test_ensure_admits_a_file_the_listing_missed(tmp_path: Path) -> None:
host = Host(operations=[])
- index = WorkspaceIndex(
- host, workspace(tmp_path, "a.py"), lambda _: ScriptedBackend()
- )
+ index = WorkspaceIndex(host, workspace(tmp_path, "a.py"), make_notebook)
index.refresh()
(tmp_path / "c.py").write_text("")
@@ -127,14 +128,18 @@ def test_ensure_admits_a_file_the_listing_missed(tmp_path: Path) -> None:
assert admitted.id in host.notebooks
-def test_deleted_file_keeps_its_runtime_until_stopped(tmp_path: Path) -> None:
+async def test_deleted_file_keeps_its_runtime_until_stopped(
+ tmp_path: Path,
+) -> None:
host = Host(operations=[])
ws = workspace(tmp_path, "a.py")
backend = ScriptedBackend()
- index = WorkspaceIndex(host, ws, lambda _: backend)
+ index = WorkspaceIndex(
+ host, ws, lambda record, sink: make_notebook(record, sink, backend)
+ )
index.refresh()
(record,) = host.notebooks.values()
- notebook = host.notebook(record.id)
+ notebook = await host.notebook(record.id)
notebook.start()
notebook.observe(be.Running(runtime_id_of(notebook)))
runtime = notebook.runtime
diff --git a/tests/_server/host/test_host_record.py b/tests/_server/host/test_host_record.py
index 2b67e2bed2..42e039b85b 100644
--- a/tests/_server/host/test_host_record.py
+++ b/tests/_server/host/test_host_record.py
@@ -21,6 +21,7 @@ from marimo._server.main import create_starlette_app
from marimo._utils.lifespans import Lifespans
from tests._core.conftest import (
ScriptedBackend,
+ add_notebook,
project,
record,
runtime_id_of,
@@ -139,7 +140,7 @@ async def test_idle_host_expires_results_and_stops_maintenance(
now = 0.0
host.clock = context.clock = lambda: now
host.update_project(project())
- notebook = host.add_notebook(record(), ScriptedBackend())
+ notebook = await add_notebook(host, record(), ScriptedBackend())
notebook.adopt(lambda _: None)
notebook.observe(be.Running(runtime_id_of(notebook)))
headers = {
diff --git a/tests/_server/host/test_host_translate.py b/tests/_server/host/test_host_translate.py
index d32572c8d4..1d285ecaf2 100644
--- a/tests/_server/host/test_host_translate.py
+++ b/tests/_server/host/test_host_translate.py
@@ -3,8 +3,6 @@
from __future__ import annotations
-import hashlib
-
import pytest
from dirty_equals import IsStr
from inline_snapshot import snapshot
@@ -17,6 +15,7 @@ from marimo._core.backend import (
Produced,
Status,
)
+from marimo._core.document import code_hash
from marimo._core.protocol import (
Console,
DisplayData,
@@ -91,7 +90,7 @@ def test_a_run_that_prints_and_shows_a_value() -> None:
PlannedExecution(
id=ExecutionId("r1-1"),
cell_id=None,
- code_hash=hashlib.sha256(b"3 * 3").hexdigest(),
+ code_hash=code_hash("3 * 3"),
code="3 * 3",
caused_by=None,
),