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.

Publish a document's analysis as it becomes available (#11256)

Trevor Manz94736376074b
diff --git a/marimo/_core/analysis.py b/marimo/_core/analysis.py
new file mode 100644
index 0000000000..0a6d2b05bc
--- /dev/null
+++ b/marimo/_core/analysis.py
@@ -0,0 +1,31 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Document analysis for the host API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+from marimo._core import protocol
+
+if TYPE_CHECKING:
+ from collections.abc import Mapping
+
+ from marimo._core.document import DocumentSnapshot
+
+
+class Analyzer(Protocol):
+ """Analysis of a document's cells.
+
+ One instance belongs to one notebook. Calls are serialized, allowing
+ implementations to cache compilation by cell ID and code hash.
+ Results cover every cell in the snapshot, including syntax errors.
+ Unexpected failures raise; they are not document diagnostics.
+
+ Implementations must keep the event loop responsive. After cancelling
+ a call, the notebook retires the instance: worker code may still run.
+ """
+
+ async def analyze(
+ self, snapshot: DocumentSnapshot
+ ) -> Mapping[protocol.CellId, protocol.CellAnalysis]:
+ """Analyze a detached snapshot without modifying it."""
diff --git a/marimo/_core/document.py b/marimo/_core/document.py
index 978af39f68..8732dbfe62 100644
--- a/marimo/_core/document.py
+++ b/marimo/_core/document.py
@@ -5,20 +5,14 @@ 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."""
+ from collections.abc import Iterator, Mapping, Sequence
Policy = Literal["autorun", "lazy"]
@@ -108,12 +102,20 @@ def revision(
)
+@dataclass(frozen=True)
+class DocumentSnapshot:
+ """A detached document record and its cells in document order."""
+
+ document: protocol.Document
+ cells: tuple[protocol.Cell, ...]
+
+
@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."""
+ """New cells, and cells whose etag changed."""
removed: list[str]
"""Ids of cells that no longer exist."""
document: protocol.Document | None
@@ -126,7 +128,7 @@ class Changed:
class Document:
"""A notebook document with content-derived revisions.
- Cell source uses newline line endings. Analysis covers all cells.
+ Cell source uses newline line endings.
"""
def __init__(
@@ -136,11 +138,9 @@ class Document:
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] = []
@@ -156,13 +156,11 @@ class Document:
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.
+ Cell identities, order, and revisions must agree. The saved
+ revision is preserved.
"""
document, cells = deepcopy((document, cells))
by_id = {cell.id: cell for cell in cells}
@@ -183,7 +181,6 @@ class Document:
],
document.app_config,
policy=document.policy,
- analyzer=analyzer,
saved=False,
)
for cell in restored:
@@ -193,10 +190,6 @@ class Document:
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
@@ -230,6 +223,10 @@ class Document:
def cell(self, cell_id: str) -> protocol.Cell | None:
return self._cells.get(cell_id)
+ def snapshot(self) -> DocumentSnapshot:
+ """Capture one revision without sharing mutable configuration."""
+ return deepcopy(DocumentSnapshot(self._record, tuple(self)))
+
def replace(
self, cells: Sequence[CellSource], app_config: Mapping[str, Any]
) -> Changed:
@@ -241,14 +238,6 @@ class Document:
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
@@ -282,7 +271,6 @@ class Document:
config=source.config,
etag=cell_etag(hashed, source.name, source.config),
code_hash=hashed,
- analysis=None,
)
def _refresh(self) -> protocol.Document | None:
diff --git a/marimo/_core/notebook.py b/marimo/_core/notebook.py
index 0b1aaed6f8..c458cddd61 100644
--- a/marimo/_core/notebook.py
+++ b/marimo/_core/notebook.py
@@ -3,6 +3,8 @@
from __future__ import annotations
+import asyncio
+import logging
from typing import TYPE_CHECKING, Any
import msgspec
@@ -17,11 +19,20 @@ from marimo._core.stream import Event, Kind, kind_of, message, utcnow
if TYPE_CHECKING:
from collections.abc import Callable, Mapping, Sequence
- from marimo._core.document import CellSource, Changed, Document
+ from marimo._core.analysis import Analyzer
+ from marimo._core.document import (
+ CellSource,
+ Changed,
+ Document,
+ DocumentSnapshot,
+ )
from marimo._core.executions import Change
from marimo._core.stream import Body, Sink
+LOGGER = logging.getLogger(__name__)
+
+
class Notebook:
"""A document, its execution results, and the runtime that produces them.
@@ -29,6 +40,10 @@ class Notebook:
Commands call the backend and publish changes through the sink.
Change the document and executions through the notebook so each
change reaches the sink.
+
+ With an analyzer, the notebook requests analysis of each document
+ revision and publishes the result when that revision is still
+ current. The previous analysis stays until then.
"""
def __init__(
@@ -37,17 +52,26 @@ class Notebook:
executions: Executions,
backend: be.Backend,
sink: Sink,
+ *,
+ analyzer: Analyzer | None = None,
) -> None:
self._document = document
self._executions = executions
self.backend = backend
self.sink = sink
+ self._analyzer = analyzer
self._closed = False
self._runtime: protocol.Runtime | None = None
self._attachments: dict[str, protocol.Attachment] = {}
self._replacement: protocol.Runtime | None = None
# Correlate runtime events with the pending start, stop, or restart.
self._runtime_request: str | None = None
+ self._analysis: protocol.Analysis | None = None
+ self._analysis_task: asyncio.Task[None] | None = None
+ # Whether the document changed during analysis, and that request.
+ self._reanalyze = False
+ self._reanalyze_request: str | None = None
+ self._request_analysis(None)
@property
def document(self) -> Document:
@@ -68,6 +92,11 @@ class Notebook:
"""The current runtime, if any."""
return self._runtime
+ @property
+ def analysis(self) -> protocol.Analysis | None:
+ """The latest analysis, which may describe an earlier revision."""
+ return self._analysis
+
def _require_open(self) -> None:
if self._closed:
raise NotFound(f"no notebook {self.id}")
@@ -85,6 +114,8 @@ class Notebook:
self._require_open()
changed = self.document.replace(cells, app_config)
self._publish_changed(changed, request_id)
+ if changed.document is not None:
+ self._request_analysis(request_id)
return changed
def mark_saved(self, *, request_id: str | None = None) -> None:
@@ -108,6 +139,49 @@ class Notebook:
if changed.document is not None:
self._publish(changed.document, request_id)
+ # ---- analysis ------------------------------------------------------
+
+ def _request_analysis(self, request_id: str | None) -> None:
+ """Analyze the current revision, or after the one in progress."""
+ if self._analyzer is None or self._closed:
+ return
+ if self._analysis_task is not None:
+ self._reanalyze, self._reanalyze_request = True, request_id
+ return
+ self._analysis_task = asyncio.create_task(
+ self._analyze(self.document.snapshot(), request_id)
+ )
+
+ async def _analyze(
+ self, snapshot: DocumentSnapshot, request_id: str | None
+ ) -> None:
+ assert self._analyzer is not None
+ try:
+ while not self._closed:
+ etag = snapshot.document.etag
+ try:
+ cells = await self._analyzer.analyze(snapshot)
+ except Exception:
+ LOGGER.exception("Could not analyze document %s", etag)
+ else:
+ if not self._closed and etag == self.document._record.etag:
+ self._analysis = protocol.Analysis(
+ notebook_id=self.id,
+ document_etag=etag,
+ cells={
+ cid: analysis
+ for cid, analysis in cells.items()
+ },
+ )
+ self._publish(self._analysis, request_id)
+ if not self._reanalyze or self._closed:
+ return
+ request_id = self._reanalyze_request
+ self._reanalyze, self._reanalyze_request = False, None
+ snapshot = self.document.snapshot()
+ finally:
+ self._analysis_task = None
+
# ---- runtime -------------------------------------------------------
def start(
@@ -280,7 +354,7 @@ class Notebook:
# ---- backend updates -----------------------------------------------
def observe(self, msg: be.Message) -> None:
- """Apply a backend update and publish the resulting state changes."""
+ """Apply a backend report and publish what changed."""
if self._closed:
return
match msg:
@@ -369,6 +443,8 @@ class Notebook:
def _snapshot(self) -> list[Event]:
"""Return current state as events in dependency order."""
bodies: list[Body] = [*self.document, self.document._record]
+ if self._analysis is not None:
+ bodies.append(self._analysis)
if self._runtime is not None:
bodies.append(self._runtime)
bodies.extend(self._attachments.values())
@@ -397,6 +473,8 @@ class Notebook:
The host publishes `notebook.removed` after disposing of this state.
"""
self._closed = True
+ if self._analysis_task is not None:
+ self._analysis_task.cancel()
self._apply(self.executions.interrupt())
self._apply(self.executions.clear())
for attachment_id in list(self._attachments):
diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.py
index f06910286d..b917016c5c 100644
--- a/marimo/_core/protocol.py
+++ b/marimo/_core/protocol.py
@@ -279,6 +279,7 @@ ObjectType: TypeAlias = Annotated[
"project",
"notebook",
"document",
+ "analysis",
"cell",
"runtime",
"attachment",
@@ -289,7 +290,7 @@ ObjectType: TypeAlias = Annotated[
"custom",
],
Meta(
- description="The kinds a stream carries, and the values `types` accepts. The\ncatalog stream carries host, project, notebook, runtime, and\nattachment. A notebook's stream carries notebook, document, cell,\nruntime, attachment, run, execution, console, display, and custom.\nCustom events describe occurrences rather than object state.\n"
+ description="The kinds a stream carries, and the values `types` accepts. The\ncatalog stream carries host, project, notebook, runtime, and\nattachment. A notebook's stream carries notebook, document,\nanalysis, cell, runtime, attachment, run, execution, console,\ndisplay, and custom. Custom events describe occurrences rather\nthan object state.\n"
),
]
@@ -637,11 +638,63 @@ class AttachmentMessage(Struct, frozen=True):
) = UNSET
+class Cell(Struct, frozen=True):
+ code: Annotated[
+ str,
+ Meta(
+ description="The cell's source code, with newline line endings. A host normalizes other line endings when it loads a file."
+ ),
+ ]
+ code_hash: Annotated[
+ Etag,
+ Meta(
+ description="Identifies the code alone. Its text is `code`. Unchanged by renaming the cell or editing its config. Compare with an execution's `code_hash` to tell whether a result came from the current code."
+ ),
+ ]
+ config: CellConfig
+ etag: Annotated[
+ Etag,
+ Meta(
+ description="Identifies code, name, and config together, and is the precondition for editing the cell. Its text is `code_hash`, `name`, and the config values `column`, `disabled`, `hide_code`, and `expand_output` in that order, each written as a JSON scalar such as `null`, `0`, or `true`."
+ ),
+ ]
+ id: CellId
+ name: Annotated[
+ str,
+ Meta(
+ description="The cell's name. `_` for an anonymous cell; otherwise a Python identifier, unique within the notebook."
+ ),
+ ]
+ notebook_id: NotebookId
+
+
class CellEtags(Struct, frozen=True):
code_hash: Etag
etag: Etag
+class CellMessage(Struct, frozen=True):
+ cell: Cell
+ request_id: (
+ Annotated[
+ str,
+ Meta(
+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did, and on snapshots unless that request's work is still in progress."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ time: (
+ Annotated[
+ datetime,
+ Meta(
+ description="When the host made this change. Present on live and replayed events; omitted on snapshots."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
Change: TypeAlias = Annotated[
PutCell | DeleteCell | SetOrder | SetAppConfig,
Meta(description="One change to the document, tagged on `kind`."),
@@ -840,6 +893,26 @@ class DocumentMessage(Struct, frozen=True):
) = UNSET
+class EditConflict(Struct, frozen=True):
+ cell: (
+ Annotated[
+ Cell,
+ Meta(
+ description="The cell the change named, as it now is. Null when the document does not have it, or when the change named the order or the app config."
+ ),
+ ]
+ | None
+ )
+ change: Annotated[
+ int,
+ Meta(
+ description="The index of the stale change in the request's `changes`, or of the stale cell in a run's `cells`. `0` for a save with a stale `If-Match`.",
+ ge=0,
+ ),
+ ]
+ document: Document
+
+
class EditRequest(Struct, frozen=True):
changes: Annotated[
tuple[Change, ...],
@@ -1010,6 +1083,54 @@ Outcome: TypeAlias = Annotated[
]
+class Problem(Struct, frozen=True):
+ status: Annotated[
+ int,
+ Meta(
+ description="The HTTP status code of the response.", ge=400, le=599
+ ),
+ ]
+ title: Annotated[
+ str,
+ Meta(
+ description="A short, human-readable name for the kind of problem."
+ ),
+ ]
+ type: Annotated[
+ str,
+ Meta(
+ description="What kind of problem this is, as a URI. The kinds this\nprotocol defines all start with `tag:marimo.io,2026:host/` and\nend with one of `invalid-request` (400), `unauthorized` (401),\n`forbidden` (403), `not-found` (404), `method-not-allowed`\n(405), `not-acceptable` (406), `conflict` (409), `no-runtime`\n(409), `decision-required` (409), `internal` (500), or\n`unsupported-operation` (501). A client that sees a kind it\ndoes not recognize falls back to `status`.\n"
+ ),
+ ]
+ decisions: (
+ Annotated[
+ tuple[Decision, ...],
+ Meta(
+ description="The choices the client has to make before the host can carry out the request. Only present for `decision-required`."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ detail: (
+ Annotated[
+ str,
+ Meta(
+ description="A human-readable explanation of what went wrong this time."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+ edit: (
+ Annotated[
+ EditConflict,
+ Meta(
+ description="Which change was stale and what the host holds instead. Only present for a `conflict` answering an edit, a save, or a run of cells."
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
+
+
class Project(Struct, frozen=True):
id: ProjectId
message: (
@@ -1185,7 +1306,7 @@ class RuntimeMessage(Struct, frozen=True):
) = UNSET
-class Analysis(Struct, frozen=True):
+class CellAnalysis(Struct, frozen=True):
defs: Annotated[
tuple[str, ...], Meta(description="Names this cell defines.")
]
@@ -1201,87 +1322,6 @@ class Analysis(Struct, frozen=True):
]
-class Cell(Struct, frozen=True):
- analysis: (
- Annotated[
- Analysis,
- Meta(
- description="Derived from the code by the host. Null when the host has no analyzer."
- ),
- ]
- | None
- )
- code: Annotated[
- str,
- Meta(
- description="The cell's source code, with newline line endings. A host normalizes other line endings when it loads a file."
- ),
- ]
- code_hash: Annotated[
- Etag,
- Meta(
- description="Identifies the code alone. Its text is `code`. Unchanged by renaming the cell or editing its config. Compare with an execution's `code_hash` to tell whether a result came from the current code."
- ),
- ]
- config: CellConfig
- etag: Annotated[
- Etag,
- Meta(
- description="Identifies code, name, and config together, and is the precondition for editing the cell. Its text is `code_hash`, `name`, and the config values `column`, `disabled`, `hide_code`, and `expand_output` in that order, each written as a JSON scalar such as `null`, `0`, or `true`."
- ),
- ]
- id: CellId
- name: Annotated[
- str,
- Meta(
- description="The cell's name. `_` for an anonymous cell; otherwise a Python identifier, unique within the notebook."
- ),
- ]
- notebook_id: NotebookId
-
-
-class CellMessage(Struct, frozen=True):
- cell: Cell
- request_id: (
- Annotated[
- str,
- Meta(
- description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did, and on snapshots unless that request's work is still in progress."
- ),
- ]
- | UnsetType
- ) = UNSET
- time: (
- Annotated[
- datetime,
- Meta(
- description="When the host made this change. Present on live and replayed events; omitted on snapshots."
- ),
- ]
- | UnsetType
- ) = UNSET
-
-
-class EditConflict(Struct, frozen=True):
- cell: (
- Annotated[
- Cell,
- Meta(
- description="The cell the change named, as it now is. Null when the document does not have it, or when the change named the order or the app config."
- ),
- ]
- | None
- )
- change: Annotated[
- int,
- Meta(
- description="The index of the stale change in the request's `changes`, or of the stale cell in a run's `cells`. `0` for a save with a stale `If-Match`.",
- ge=0,
- ),
- ]
- document: Document
-
-
class Execution(Struct, frozen=True):
bindings: Annotated[
tuple[Binding, ...],
@@ -1402,48 +1442,38 @@ class ExecutionMessage(Struct, frozen=True):
) = UNSET
-class Problem(Struct, frozen=True):
- status: Annotated[
- int,
- Meta(
- description="The HTTP status code of the response.", ge=400, le=599
- ),
+class Analysis(Struct, frozen=True):
+ cells: Annotated[
+ dict[str, CellAnalysis],
+ Meta(description="Every cell of that revision, by id."),
]
- title: Annotated[
- str,
+ document_etag: Annotated[
+ Etag,
Meta(
- description="A short, human-readable name for the kind of problem."
+ description="The document revision this analysis describes. Equal to the document's `etag` while the analysis is current."
),
]
- type: Annotated[
- str,
- Meta(
- description="What kind of problem this is, as a URI. The kinds this\nprotocol defines all start with `tag:marimo.io,2026:host/` and\nend with one of `invalid-request` (400), `unauthorized` (401),\n`forbidden` (403), `not-found` (404), `method-not-allowed`\n(405), `not-acceptable` (406), `conflict` (409), `no-runtime`\n(409), `decision-required` (409), `internal` (500), or\n`unsupported-operation` (501). A client that sees a kind it\ndoes not recognize falls back to `status`.\n"
- ),
+ notebook_id: Annotated[
+ NotebookId, Meta(description="The notebook this analysis belongs to.")
]
- decisions: (
- Annotated[
- tuple[Decision, ...],
- Meta(
- description="The choices the client has to make before the host can carry out the request. Only present for `decision-required`."
- ),
- ]
- | UnsetType
- ) = UNSET
- detail: (
+
+
+class AnalysisMessage(Struct, frozen=True):
+ analysis: Analysis
+ request_id: (
Annotated[
str,
Meta(
- description="A human-readable explanation of what went wrong this time."
+ description="The `Idempotency-Key` of the request that caused this event. Omitted when no request did, and on snapshots unless that request's work is still in progress."
),
]
| UnsetType
) = UNSET
- edit: (
+ time: (
Annotated[
- EditConflict,
+ datetime,
Meta(
- description="Which change was stale and what the host holds instead. Only present for a `conflict` answering an edit, a save, or a run of cells."
+ description="When the host made this change. Present on live and replayed events; omitted on snapshots."
),
]
| UnsetType
diff --git a/marimo/_core/stream.py b/marimo/_core/stream.py
index 90adb0ea05..aecf205c18 100644
--- a/marimo/_core/stream.py
+++ b/marimo/_core/stream.py
@@ -29,6 +29,7 @@ Body: TypeAlias = (
| protocol.Project
| protocol.Notebook
| protocol.Document
+ | protocol.Analysis
| protocol.Cell
| protocol.Runtime
| protocol.Attachment
@@ -47,6 +48,7 @@ Kind: TypeAlias = Literal[
"project",
"notebook",
"document",
+ "analysis",
"cell",
"runtime",
"attachment",
diff --git a/marimo/_runtime/dataflow/edges.py b/marimo/_runtime/dataflow/edges.py
index 3778d9afa4..81c905c078 100644
--- a/marimo/_runtime/dataflow/edges.py
+++ b/marimo/_runtime/dataflow/edges.py
@@ -136,51 +136,18 @@ def _resolve_variable_name(
return name
-def compute_edges_for_cell(
+def resolve_cell_references(
cell_id: CellId_t,
cell: CellImpl,
topology: GraphTopology,
definitions: DefinitionRegistry,
-) -> tuple[set[CellId_t], set[CellId_t]]:
- """Compute parent and child edges for a cell being registered.
+) -> dict[Name, set[CellId_t]]:
+ """Resolve each reference to its defining cells using language semantics.
- Args:
- cell_id: The ID this cell is being registered with
- cell: The cell to compute edges for
- topology: The graph topology
- definitions: The definition registry
-
- Returns:
- Tuple of (parents, children) where:
- - parents: cells that this cell depends on
- - children: cells that depend on this cell
+ Keys retain the reference as written, including SQL qualification.
+ Unresolved names and references to the cell itself are excluded.
"""
- parents: set[CellId_t] = set()
- children: set[CellId_t] = set()
-
- # First, process the variables that this cell defines. Any cell
- # that refers to a defined variable becomes a child of this cell.
- for name, variable_data in cell.variable_data.items():
- # NB. Only the last definition matters.
- # Technically more nuanced with branching statements, but this is
- # the best we can do with static analysis.
- variable = variable_data[-1]
-
- # a cell can refer to its own defs, but that doesn't add an
- # edge to the dependency graph
- referring_cells = get_referring_cells(
- name,
- language=variable.language,
- topology=topology,
- ) - {cell_id}
-
- children.update(referring_cells)
-
- # Next, process the cells references. The cell becomes a child
- # of cells that define its referenced variables. We also have
- # special logic for handling references that are deleted by this cell,
- # since cells that delete variables that were defined elsewhere
- # are made children of cells that reference that variable.
+ resolved: dict[Name, set[CellId_t]] = {}
for name in cell.refs:
# First, for each referenced variable, we add cells that define
# that variable as parents
@@ -242,8 +209,62 @@ def compute_edges_for_cell(
kind=cast(SQLTypes, other_variable_data.kind),
):
continue
- parents.add(other_id)
+ resolved.setdefault(name, set()).add(other_id)
+
+ return resolved
+
+
+def compute_edges_for_cell(
+ cell_id: CellId_t,
+ cell: CellImpl,
+ topology: GraphTopology,
+ definitions: DefinitionRegistry,
+) -> tuple[set[CellId_t], set[CellId_t]]:
+ """Compute parent and child edges for a cell being registered.
+
+ Args:
+ cell_id: The ID this cell is being registered with
+ cell: The cell to compute edges for
+ topology: The graph topology
+ definitions: The definition registry
+
+ Returns:
+ Tuple of (parents, children) where:
+ - parents: cells that this cell depends on
+ - children: cells that depend on this cell
+ """
+ parents: set[CellId_t] = set()
+ children: set[CellId_t] = set()
+
+ # First, process the variables that this cell defines. Any cell
+ # that refers to a defined variable becomes a child of this cell.
+ for name, variable_data in cell.variable_data.items():
+ # NB. Only the last definition matters.
+ # Technically more nuanced with branching statements, but this is
+ # the best we can do with static analysis.
+ variable = variable_data[-1]
+
+ # a cell can refer to its own defs, but that doesn't add an
+ # edge to the dependency graph
+ referring_cells = get_referring_cells(
+ name,
+ language=variable.language,
+ topology=topology,
+ ) - {cell_id}
+
+ children.update(referring_cells)
+
+ for defining_cells in resolve_cell_references(
+ cell_id, cell, topology, definitions
+ ).values():
+ parents.update(defining_cells)
+ # Next, process the cells references. The cell becomes a child
+ # of cells that define its referenced variables. We also have
+ # special logic for handling references that are deleted by this cell,
+ # since cells that delete variables that were defined elsewhere
+ # are made children of cells that reference that variable.
+ for name in cell.refs:
# Next, any cell that deletes this referenced variable is made
# a child of this cell. In particular, if a cell deletes a
# variable, it becomes a child of all other cells that
diff --git a/marimo/_server/host/analysis.py b/marimo/_server/host/analysis.py
index dc382b33a2..40246711ce 100644
--- a/marimo/_server/host/analysis.py
+++ b/marimo/_server/host/analysis.py
@@ -1,84 +1,92 @@
# Copyright 2026 Marimo. All rights reserved.
-"""Cell definitions, references, and syntax errors.
+"""Cell definitions, references, and syntax errors for the host protocol.
-The kernel reports errors involving multiple cells, such as cycles
-and multiple definitions.
+The kernel reports errors involving multiple cells.
"""
from __future__ import annotations
+import asyncio
+from dataclasses import dataclass
from typing import TYPE_CHECKING
+from marimo._ast.cell import CellImpl
from marimo._ast.compiler import compile_cell
from marimo._core import protocol
+from marimo._runtime.dataflow import DirectedGraph
+from marimo._runtime.dataflow.edges import resolve_cell_references
from marimo._types.ids import CellId_t
if TYPE_CHECKING:
- from collections.abc import Mapping
-
- from marimo._ast.cell import CellImpl
+ from marimo._core.document import DocumentSnapshot
SOURCE = "marimo"
-class Analyzer:
- """Incremental analysis for one document."""
+class HostAnalyzer:
+ """Analyze serialized document snapshots in a worker thread."""
+
+ def __init__(self) -> None:
+ self._cells = CellAnalyzer()
+
+ async def analyze(
+ self, snapshot: DocumentSnapshot
+ ) -> dict[protocol.CellId, protocol.CellAnalysis]:
+ return await asyncio.to_thread(self._cells, snapshot)
+
+
+@dataclass(frozen=True)
+class _CachedCell:
+ code_hash: protocol.Etag
+ result: CellImpl | protocol.Error
+
+
+class CellAnalyzer:
+ """Reuse compilation by cell identity and code hash across snapshots."""
def __init__(self) -> None:
- self._codes: dict[str, str] = {}
- self._compiled: dict[str, CellImpl] = {}
- self._syntax: dict[str, protocol.Error] = {}
+ self._cache: dict[protocol.CellId, _CachedCell] = {}
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)
+ self, snapshot: DocumentSnapshot
+ ) -> dict[protocol.CellId, protocol.CellAnalysis]:
+ cache: dict[protocol.CellId, _CachedCell] = {}
+ graph = DirectedGraph()
+ for cell in snapshot.cells:
+ cached = self._cache.get(cell.id)
+ if cached is None or cached.code_hash != cell.code_hash:
+ try:
+ result: CellImpl | protocol.Error = compile_cell(
+ cell.code, CellId_t(cell.id)
)
- ),
- 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)
+ except (SyntaxError, ValueError) as error:
+ result = _syntax_error(cell.code, error)
+ cached = _CachedCell(cell.code_hash, result)
+ cache[cell.id] = cached
+ if isinstance(cached.result, CellImpl):
+ graph.register_cell(CellId_t(cell.id), cached.result)
+ self._cache = cache
+
+ analyses: dict[protocol.CellId, protocol.CellAnalysis] = {}
+ for cell in snapshot.cells:
+ compiled = cache[cell.id].result
+ if isinstance(compiled, protocol.Error):
+ analyses[cell.id] = protocol.CellAnalysis(
+ defs=(), refs=(), errors=(compiled,)
+ )
+ else:
+ refs = resolve_cell_references(
+ CellId_t(cell.id),
+ compiled,
+ graph,
+ graph.definition_registry,
+ )
+ analyses[cell.id] = protocol.CellAnalysis(
+ defs=tuple(sorted(compiled.defs)),
+ refs=tuple(sorted(refs)),
+ errors=(),
+ )
+ return analyses
def _syntax_error(code: str, e: Exception) -> protocol.Error:
diff --git a/marimo/_server/host/bridge.py b/marimo/_server/host/bridge.py
index 4b24599b80..587dbe4b26 100644
--- a/marimo/_server/host/bridge.py
+++ b/marimo/_server/host/bridge.py
@@ -16,7 +16,7 @@ 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.analysis import HostAnalyzer
from marimo._server.host.backend import SessionBackend
from marimo._server.host.index import WorkspaceIndex
from marimo._session.events import SessionEventListener
@@ -105,13 +105,18 @@ class SessionBridge(SessionEventListener):
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(revision(*loaded))
backend = self._make_backend(record.id)
- return Notebook(document, Executions(), backend, sink)
+ return Notebook(
+ document,
+ Executions(),
+ backend,
+ sink,
+ analyzer=HostAnalyzer(),
+ )
async def _load(
self, file: Path
diff --git a/protocols/host/conformance/contract.py b/protocols/host/conformance/contract.py
index bd5f3eb60e..0ec407f3e5 100644
--- a/protocols/host/conformance/contract.py
+++ b/protocols/host/conformance/contract.py
@@ -27,6 +27,7 @@ KINDS = (
"project",
"notebook",
"document",
+ "analysis",
"cell",
"runtime",
"attachment",
diff --git a/protocols/host/conformance/test_contract.py b/protocols/host/conformance/test_contract.py
index 829f2d86de..f8c996d06b 100644
--- a/protocols/host/conformance/test_contract.py
+++ b/protocols/host/conformance/test_contract.py
@@ -25,6 +25,7 @@ FIXTURES = ROOT / "fixtures"
MODELS = {
"record.json": "HostRecord",
"cell.json": "Cell",
+ "analysis.json": "Analysis",
"diagnostic.json": "Error",
"edit.json": "EditRequest",
"edit-conflict-request.json": "EditRequest",
@@ -65,6 +66,18 @@ async def test_stream_examples(path):
frame.message()
[email protected]("message", [{}, {"analysis": {}}])
+async def test_invalid_analysis_messages_are_rejected(message):
+ data = json.dumps(message)
+ with pytest.raises(ValidationError):
+ Frame(event="analysis", data=data).message()
+
+ stream = f"event: analysis\ndata: {data}\n\nevent: ready\ndata: {{}}\n\n"
+ watch = Watch(frames(lines(stream)), timeout=1)
+ with pytest.raises(ValidationError):
+ await watch.ready()
+
+
async def test_sse_preserves_multiline_data_comments_and_explicit_ids():
stream = ": ping\r\nid: 7\r\nevent: future\r\ndata: one\r\ndata: two\r\n\r\nevent: ready\ndata: {}\n\n"
assert [frame async for frame in frames(lines(stream))] == [
diff --git a/protocols/host/fixtures/README.md b/protocols/host/fixtures/README.md
index 78bf82cf83..3127167794 100644
--- a/protocols/host/fixtures/README.md
+++ b/protocols/host/fixtures/README.md
@@ -8,7 +8,8 @@ opaque. Gaps represent events outside an excerpt or its filter.
`notebook-events.sse` opens a stream for notebook `n1` during the scratch run
shown in `run.sse`. Its snapshot includes the display and console output
already produced. Both streams end with the same execution and run completion
-events, using the same cursors. `cell.json` is cell `c3` from that snapshot.
+events, using the same cursors. `cell.json` is cell `c3` from that snapshot,
+and `analysis.json` is the analysis of that document.
`run-cells-request.json` requests `c3`, which defines `x`. In `run-cells.sse`,
the runtime then evaluates `k7f2`, which defines `y` using `x`. The dependent
diff --git a/protocols/host/fixtures/analysis.json b/protocols/host/fixtures/analysis.json
new file mode 100644
index 0000000000..6c108eeb19
--- /dev/null
+++ b/protocols/host/fixtures/analysis.json
@@ -0,0 +1,29 @@
+{
+ "notebook_id": "n1",
+ "document_etag": "e59d9c2af02f5814",
+ "cells": {
+ "c1": {
+ "defs": [
+ "mo"
+ ],
+ "refs": [],
+ "errors": []
+ },
+ "c3": {
+ "defs": [
+ "x"
+ ],
+ "refs": [],
+ "errors": []
+ },
+ "k7f2": {
+ "defs": [
+ "y"
+ ],
+ "refs": [
+ "x"
+ ],
+ "errors": []
+ }
+ }
+}
diff --git a/protocols/host/fixtures/cell.json b/protocols/host/fixtures/cell.json
index dbebc929bd..5c3ad310cf 100644
--- a/protocols/host/fixtures/cell.json
+++ b/protocols/host/fixtures/cell.json
@@ -10,12 +10,5 @@
"expand_output": false
},
"etag": "5cf78587dcf22d8d",
- "code_hash": "0f71456db2ea83f4",
- "analysis": {
- "defs": [
- "x"
- ],
- "refs": [],
- "errors": []
- }
+ "code_hash": "0f71456db2ea83f4"
}
diff --git a/protocols/host/fixtures/edits.sse b/protocols/host/fixtures/edits.sse
index 187986001d..7bd0343ec9 100644
--- a/protocols/host/fixtures/edits.sse
+++ b/protocols/host/fixtures/edits.sse
@@ -1,10 +1,10 @@
id: 110
event: cell
-data: {"cell":{"id":"c2","notebook_id":"n1","code":"print('hi')","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"ce27bab48d697cfc","code_hash":"c2d0a5e0790d97a0","analysis":{"defs":[],"refs":[],"errors":[]}},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}
+data: {"cell":{"id":"c2","notebook_id":"n1","code":"print('hi')","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"ce27bab48d697cfc","code_hash":"c2d0a5e0790d97a0"},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}
id: 111
event: cell
-data: {"cell":{"id":"c3","notebook_id":"n1","code":"x = 22","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"dde89bbcc1863211","code_hash":"43e1a529dbae470b","analysis":{"defs":["x"],"refs":[],"errors":[]}},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}
+data: {"cell":{"id":"c3","notebook_id":"n1","code":"x = 22","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"dde89bbcc1863211","code_hash":"43e1a529dbae470b"},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}
id: 112
event: cell.removed
diff --git a/protocols/host/fixtures/notebook-events.sse b/protocols/host/fixtures/notebook-events.sse
index f79536dd5a..190a7afcbb 100644
--- a/protocols/host/fixtures/notebook-events.sse
+++ b/protocols/host/fixtures/notebook-events.sse
@@ -2,17 +2,20 @@ event: notebook
data: {"notebook":{"id":"n1","project_id":"p1","path":"forecasts.py","name":"forecasts","operations":["notebook.update","notebook.delete","notebook.open","notebook.edit","notebook.save","runtime.start","runtime.stop","runtime.run","runtime.interrupt"],"updated_at":"2026-10-01T09:00:00Z"}}
event: cell
-data: {"cell":{"id":"c1","notebook_id":"n1","code":"import marimo as mo","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"48d6363150d6281c","code_hash":"f649a0b56c5c1966","analysis":{"defs":["mo"],"refs":[],"errors":[]}}}
+data: {"cell":{"id":"c1","notebook_id":"n1","code":"import marimo as mo","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"48d6363150d6281c","code_hash":"f649a0b56c5c1966"}}
event: cell
-data: {"cell":{"id":"c3","notebook_id":"n1","code":"x = 21","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"5cf78587dcf22d8d","code_hash":"0f71456db2ea83f4","analysis":{"defs":["x"],"refs":[],"errors":[]}}}
+data: {"cell":{"id":"c3","notebook_id":"n1","code":"x = 21","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"5cf78587dcf22d8d","code_hash":"0f71456db2ea83f4"}}
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":[]}}}
+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"}}
event: document
data: {"document":{"notebook_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: analysis
+data: {"analysis":{"notebook_id":"n1","document_etag":"e59d9c2af02f5814","cells":{"c1":{"defs":["mo"],"refs":[],"errors":[]},"c3":{"defs":["x"],"refs":[],"errors":[]},"k7f2":{"defs":["y"],"refs":["x"],"errors":[]}}}}
+
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 4a1a8c5a9a..6c9e3fffc0 100644
--- a/protocols/host/fixtures/problems/edit-conflict.json
+++ b/protocols/host/fixtures/problems/edit-conflict.json
@@ -17,14 +17,7 @@
"expand_output": false
},
"etag": "dde89bbcc1863211",
- "code_hash": "43e1a529dbae470b",
- "analysis": {
- "defs": [
- "x"
- ],
- "refs": [],
- "errors": []
- }
+ "code_hash": "43e1a529dbae470b"
},
"document": {
"notebook_id": "n1",
diff --git a/protocols/host/openapi.yaml b/protocols/host/openapi.yaml
index 53949b5a29..e157dc39e7 100644
--- a/protocols/host/openapi.yaml
+++ b/protocols/host/openapi.yaml
@@ -219,7 +219,8 @@ paths:
that orders them, in the opening phase and after every change, so
a client never holds a document whose `order` names a cell it has
not received. The effects of one change to the document arrive
- together, with no other event between them.
+ together, with no other event between them. The analysis, when
+ the host has one, follows the document it describes.
parameters:
- $ref: '#/components/parameters/NotebookId'
- $ref: '#/components/parameters/Types'
@@ -237,7 +238,7 @@ paths:
description: |
One event. `data` holds JSON, and the event name says
which shape: a NotebookMessage, DocumentMessage,
- CellMessage, RuntimeMessage, AttachmentMessage,
+ AnalysisMessage, CellMessage, RuntimeMessage, AttachmentMessage,
RunMessage, ExecutionMessage, ConsoleMessage, or
DisplayMessage for an event named
after that kind; a CustomMessage for `custom`; a RemovedMessage
@@ -292,7 +293,9 @@ paths:
On success the document has changed, and every attachment sees
the effects on the notebook's stream with this request's key: the
cells that changed, `cell.removed` for each deleted cell, and then
- the document, with nothing in between. The response carries the
+ the document, with nothing in between. The analysis of the new
+ revision follows with the same key once the host has it. The
+ response carries the
new etags, so a client keeps editing without reading again. A
change that changes nothing keeps its etags and sends no events.
Whether the result has reached the store shows in the document's
@@ -826,10 +829,11 @@ components:
description: |
The kinds a stream carries, and the values `types` accepts. The
catalog stream carries host, project, notebook, runtime, and
- attachment. A notebook's stream carries notebook, document, cell,
- runtime, attachment, run, execution, console, display, and custom.
- Custom events describe occurrences rather than object state.
- enum: [host, project, notebook, document, cell, runtime, attachment, run, execution, console, display, custom]
+ attachment. A notebook's stream carries notebook, document,
+ analysis, cell, runtime, attachment, run, execution, console,
+ display, and custom. Custom events describe occurrences rather
+ than object state.
+ enum: [host, project, notebook, document, analysis, cell, runtime, attachment, run, execution, console, display, custom]
Custom:
type: object
description: |
@@ -1284,15 +1288,31 @@ components:
type: boolean
description: Whether clients show the full output rather than a scrolled box.
Analysis:
+ type: object
+ description: |
+ What a document's cells imply, computed together over one
+ revision of the document so that cross-cell errors agree. One
+ per notebook, and removed with it. It follows the document it
+ describes, and `document_etag` says which revision that is.
+ required: [notebook_id, document_etag, cells]
+ properties:
+ notebook_id:
+ $ref: '#/components/schemas/NotebookId'
+ description: The notebook this analysis belongs to.
+ document_etag:
+ $ref: '#/components/schemas/Etag'
+ description: The document revision this analysis describes. Equal to the document's `etag` while the analysis is current.
+ cells:
+ type: object
+ additionalProperties: { $ref: '#/components/schemas/CellAnalysis' }
+ description: Every cell of that revision, by id.
+ CellAnalysis:
type: object
description: |
What a cell's text implies: the names it defines and reads, which
are the edges of the dependency graph, and the errors found in the
text alone or across the set of cells. A pure function of the
- code, so two producers compute the same values. Cross-cell errors
- need the whole set of cells and are reported as soon as the
- document has them, in the same unit as the change that caused
- them, without moving the etag of a cell whose code did not change.
+ code, so two producers compute the same values.
required: [defs, refs, errors]
properties:
defs:
@@ -1311,10 +1331,10 @@ components:
type: object
description: |
A unit of code and configuration in the document. A cell event
- fires when its code, name, config, or analysis changes. Only the
- first three move its etag. Markdown and SQL cells are code that
- calls `mo.md` or `mo.sql`; a client chooses the editor to show.
- required: [id, notebook_id, code, name, config, etag, code_hash, analysis]
+ fires when its code, name, or config changes. Markdown and SQL
+ cells are code that calls `mo.md` or `mo.sql`; a client chooses
+ the editor to show.
+ required: [id, notebook_id, code, name, config, etag, code_hash]
properties:
id: { $ref: '#/components/schemas/CellId' }
notebook_id: { $ref: '#/components/schemas/NotebookId' }
@@ -1331,9 +1351,6 @@ components:
code_hash:
$ref: '#/components/schemas/Etag'
description: Identifies the code alone. Its text is `code`. Unchanged by renaming the cell or editing its config. Compare with an execution's `code_hash` to tell whether a result came from the current code.
- analysis:
- oneOf: [{ $ref: '#/components/schemas/Analysis' }, { type: 'null' }]
- description: Derived from the code by the host. Null when the host has no analyzer.
Document:
type: object
description: |
@@ -1469,6 +1486,14 @@ components:
request_id: *request_id
time: *time
document: { $ref: '#/components/schemas/Document' }
+ AnalysisMessage:
+ type: object
+ description: The data of an `analysis` event. The analysis as it now is.
+ required: [analysis]
+ properties:
+ request_id: *request_id
+ time: *time
+ analysis: { $ref: '#/components/schemas/Analysis' }
CellMessage:
type: object
description: The data of a `cell` event. The cell as it now is.
diff --git a/protocols/host/spec.md b/protocols/host/spec.md
index 18bdcfea67..3b8e76a728 100644
--- a/protocols/host/spec.md
+++ b/protocols/host/spec.md
@@ -76,13 +76,14 @@ across renames and moves.
### Documents and cells
The **document** is the notebook's editable source, organized into **cells**.
-Each cell holds code and the information used to present and execute it. Cells
-also MAY carry static analysis so clients can understand their role in the
+Each cell holds code and the information used to present and execute it. A host
+MAY also publish an **analysis** of the document: each cell's definitions,
+references, and problems, so clients can understand a cell's role in the
computation and identify problems before execution.
Because cells share a dependency graph, editing one can affect the analysis of
-others. Hosts MUST publish those changes together with the edit, giving clients
-a consistent view of the document.
+others. An analysis therefore covers the whole document and names the revision
+it describes. Hosts publish it after that revision of the document.
### Runtimes and attachments
diff --git a/tests/_core/conftest.py b/tests/_core/conftest.py
index 5b2b42821a..c191aa0952 100644
--- a/tests/_core/conftest.py
+++ b/tests/_core/conftest.py
@@ -3,10 +3,12 @@
from __future__ import annotations
+import asyncio
+
import pytest
from marimo._core import backend as be, protocol
-from marimo._core.document import Document, code_hash
+from marimo._core.document import Document, DocumentSnapshot, code_hash
from marimo._core.executions import CellExecution, Executions
from marimo._core.host import Host
from marimo._core.notebook import Notebook
@@ -38,6 +40,37 @@ class ScriptedBackend:
self.calls.append(("forget", run_id))
+class ScriptedAnalyzer:
+ """Expose snapshots and let tests complete analysis explicitly."""
+
+ def __init__(self) -> None:
+ self.requests: list[DocumentSnapshot] = []
+ self.pending: asyncio.Queue[
+ tuple[
+ DocumentSnapshot,
+ asyncio.Future[dict[protocol.CellId, protocol.CellAnalysis]],
+ ]
+ ] = asyncio.Queue()
+
+ async def analyze(
+ self, snapshot: DocumentSnapshot
+ ) -> dict[protocol.CellId, protocol.CellAnalysis]:
+ result: asyncio.Future[
+ dict[protocol.CellId, protocol.CellAnalysis]
+ ] = asyncio.get_running_loop().create_future()
+ self.requests.append(snapshot)
+ self.pending.put_nowait((snapshot, result))
+ return await result
+
+ async def next_request(
+ self,
+ ) -> tuple[
+ DocumentSnapshot,
+ asyncio.Future[dict[protocol.CellId, protocol.CellAnalysis]],
+ ]:
+ return await asyncio.wait_for(self.pending.get(), timeout=5)
+
+
def runtime_id_of(notebook: Notebook) -> protocol.RuntimeId:
"""The current runtime's ID, for reports about it."""
assert notebook.runtime is not None
@@ -74,12 +107,14 @@ def make_notebook(
backend: ScriptedBackend | None = None,
*,
document: Document | None = None,
+ analyzer: ScriptedAnalyzer | None = None,
) -> Notebook:
return Notebook(
document or Document(record.id, [], {}),
Executions(),
backend or ScriptedBackend(),
sink,
+ analyzer=analyzer,
)
@@ -89,11 +124,12 @@ async def add_notebook(
backend: ScriptedBackend,
*,
document: Document | None = None,
+ analyzer: ScriptedAnalyzer | None = None,
) -> Notebook:
host.add_notebook(
record,
lambda current, sink: make_notebook(
- current, sink, backend, document=document
+ current, sink, backend, document=document, analyzer=analyzer
),
)
return await host.notebook(record.id)
diff --git a/tests/_core/test_notebook.py b/tests/_core/test_notebook.py
index 2465b7cbf2..4a826e8e1d 100644
--- a/tests/_core/test_notebook.py
+++ b/tests/_core/test_notebook.py
@@ -19,7 +19,6 @@ from marimo._core.executions import CellExecution, Executions
from marimo._core.host import Host
from marimo._core.notebook import Notebook
from marimo._core.protocol import (
- Analysis,
AttachmentMessage,
CellId,
Console,
@@ -1200,7 +1199,7 @@ async def test_current_cell_results_can_seed_another_notebook() -> None:
@pytest.mark.parametrize("saved", [False, True])
-def test_restoration_preserves_revisions_outputs_and_analysis(
+def test_restoration_preserves_revisions_and_outputs(
saved: bool,
) -> None:
document = Document(
@@ -1209,9 +1208,6 @@ def test_restoration_preserves_revisions_outputs_and_analysis(
{"width": "full"},
policy="lazy",
saved=saved,
- analyzer=lambda codes: {
- cell_id: Analysis(defs=(), refs=(), errors=()) for cell_id in codes
- },
)
# The output belongs to the previous source, and the saved revision can
# precede the current one. Neither is rewritten during restoration.
diff --git a/tests/_core/test_notebook_document.py b/tests/_core/test_notebook_document.py
index cbed46aa17..56a283d097 100644
--- a/tests/_core/test_notebook_document.py
+++ b/tests/_core/test_notebook_document.py
@@ -3,9 +3,10 @@
from __future__ import annotations
-from typing import TYPE_CHECKING
+import asyncio
import pytest
+from msgspec import UNSET
from msgspec.structs import replace
from marimo._core import protocol
@@ -19,13 +20,20 @@ from marimo._core.document import (
order_etag,
revision,
)
+from marimo._core.executions import Executions
from marimo._core.host import Host
from marimo._core.notebook import Notebook
from marimo._core.stream import Event
-from tests._core.conftest import make_notebook, names, project, record
-
-if TYPE_CHECKING:
- from collections.abc import Mapping
+from tests._core.conftest import (
+ ScriptedAnalyzer,
+ ScriptedBackend,
+ add_notebook,
+ make_notebook,
+ names,
+ project,
+ record,
+ request_ids,
+)
NOTEBOOK = protocol.NotebookId("n1")
HIDDEN = protocol.CellConfig(
@@ -42,33 +50,6 @@ def fixture_cells() -> list[CellSource]:
]
-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,
@@ -204,54 +185,16 @@ class TestReplace:
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:
+ def test_preserves_the_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
- },
+ NOTEBOOK, fixture_cells(), {"width": "full"}, policy="lazy"
)
# 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"]
@@ -272,26 +215,6 @@ class TestFromRecords:
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(
@@ -346,3 +269,208 @@ class TestNotebook:
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]
+
+
+def cell_analyses(
+ document: Document,
+) -> dict[protocol.CellId, protocol.CellAnalysis]:
+ """A placeholder analysis of every cell in the document."""
+ return {
+ cell.id: protocol.CellAnalysis(defs=(), refs=(), errors=())
+ for cell in document
+ }
+
+
+class TestAnalysis:
+ async def test_the_initial_revision_is_analyzed_and_published_after_the_document(
+ self, host: Host, log: list[Event]
+ ) -> None:
+ host.update_project(project())
+ analyzer = ScriptedAnalyzer()
+ document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})
+ notebook = await add_notebook(
+ host,
+ record(),
+ ScriptedBackend(),
+ document=document,
+ analyzer=analyzer,
+ )
+ snapshot, result = await analyzer.next_request()
+ assert snapshot == document.snapshot()
+ assert notebook.analysis is None
+
+ log.clear()
+ result.set_result(cell_analyses(document))
+ await asyncio.sleep(0)
+
+ assert names(log) == ["analysis"]
+ assert request_ids(log) == [UNSET]
+ assert notebook.analysis == protocol.Analysis(
+ notebook_id=NOTEBOOK,
+ document_etag=snapshot.document.etag,
+ cells=cell_analyses(document),
+ )
+ assert names(host.events(notebook_id="n1")) == [
+ "notebook",
+ "cell",
+ "cell",
+ "cell",
+ "document",
+ "analysis",
+ "ready",
+ ]
+
+ async def test_edits_during_analysis_are_analyzed_once_afterwards(
+ self, host: Host, log: list[Event]
+ ) -> None:
+ host.update_project(project())
+ analyzer = ScriptedAnalyzer()
+ document = Document(NOTEBOOK, fixture_cells(), {})
+ notebook = await add_notebook(
+ host,
+ record(),
+ ScriptedBackend(),
+ document=document,
+ analyzer=analyzer,
+ )
+ first, result = await analyzer.next_request()
+ first_analysis = cell_analyses(document)
+ notebook.replace([CellSource("c1", "1")], {}, request_id="edit-1")
+ notebook.replace(
+ [CellSource("c1", "2", name="named", config=HIDDEN)],
+ {"width": "full"},
+ request_id="edit-2",
+ )
+ assert len(analyzer.requests) == 1
+ assert first.document.etag != document._record.etag
+ assert first.cells[0].code == "import marimo as mo"
+
+ log.clear()
+ result.set_result(first_analysis)
+ latest, result = await analyzer.next_request()
+ assert names(log) == []
+ assert latest == document.snapshot()
+
+ result.set_result(cell_analyses(document))
+ await asyncio.sleep(0)
+ assert names(log) == ["analysis"]
+ assert request_ids(log) == ["edit-2"]
+ assert notebook.analysis is not None
+ assert notebook.analysis.document_etag == latest.document.etag
+
+ async def test_the_previous_analysis_stays_until_the_next_arrives(
+ self, host: Host
+ ) -> None:
+ host.update_project(project())
+ analyzer = ScriptedAnalyzer()
+ document = Document(NOTEBOOK, fixture_cells(), {})
+ notebook = await add_notebook(
+ host,
+ record(),
+ ScriptedBackend(),
+ document=document,
+ analyzer=analyzer,
+ )
+ first, result = await analyzer.next_request()
+ result.set_result(cell_analyses(document))
+ await asyncio.sleep(0)
+ notebook.replace([CellSource("c1", "1")], {})
+ _, result = await analyzer.next_request()
+
+ assert notebook.analysis is not None
+ assert (
+ notebook.analysis.document_etag
+ == first.document.etag
+ != document._record.etag
+ )
+ assert names(host.events(notebook_id="n1")) == [
+ "notebook",
+ "cell",
+ "document",
+ "analysis",
+ "ready",
+ ]
+ result.set_result(cell_analyses(document))
+ await asyncio.sleep(0)
+
+ @pytest.mark.parametrize("edit_while_running", [False, True])
+ async def test_a_failed_analysis_leaves_the_notebook_ready_for_the_next(
+ self, host: Host, log: list[Event], edit_while_running: bool
+ ) -> None:
+ host.update_project(project())
+ analyzer = ScriptedAnalyzer()
+ document = Document(NOTEBOOK, fixture_cells(), {})
+ notebook = await add_notebook(
+ host,
+ record(),
+ ScriptedBackend(),
+ document=document,
+ analyzer=analyzer,
+ )
+ _, result = await analyzer.next_request()
+ if edit_while_running:
+ notebook.replace([CellSource("c1", "1")], {})
+ log.clear()
+ result.set_exception(RuntimeError("compiler failed"))
+ await asyncio.sleep(0)
+ assert names(log) == []
+ assert notebook.analysis is None
+ if not edit_while_running:
+ notebook.replace([CellSource("c1", "1")], {})
+ snapshot, result = await analyzer.next_request()
+ assert snapshot == document.snapshot()
+ log.clear()
+ result.set_result(cell_analyses(document))
+ await asyncio.sleep(0)
+ assert names(log) == ["analysis"]
+
+ async def test_removal_discards_a_result_even_if_cancellation_is_suppressed(
+ self, host: Host, log: list[Event]
+ ) -> None:
+ started, cancelled = asyncio.Event(), asyncio.Event()
+ result = asyncio.get_running_loop().create_future()
+ document = Document(NOTEBOOK, fixture_cells(), {})
+
+ class Analyzer:
+ async def analyze(self, _snapshot):
+ started.set()
+ try:
+ return await asyncio.shield(result)
+ except asyncio.CancelledError:
+ cancelled.set()
+ return await result
+
+ host.update_project(project())
+ host.add_notebook(
+ record(),
+ lambda _, sink: Notebook(
+ document,
+ Executions(),
+ ScriptedBackend(),
+ sink,
+ analyzer=Analyzer(),
+ ),
+ )
+ await host.notebook("n1")
+ await asyncio.wait_for(started.wait(), timeout=5)
+ host.remove_notebook("n1")
+ await asyncio.wait_for(cancelled.wait(), timeout=5)
+ log.clear()
+ result.set_result(cell_analyses(document))
+ await asyncio.sleep(0)
+ assert names(log) == []
+ assert "n1" not in host.notebooks
+
+
+def test_snapshot_preserves_order_metadata_and_nested_configuration() -> None:
+ document = Document(NOTEBOOK, fixture_cells(), {"nested": {"items": [1]}})
+ snapshot = document.snapshot()
+ assert snapshot.cells == tuple(document)
+ assert snapshot.document == document._record
+ document._record.app_config["nested"]["items"].append(2)
+ document.replace([CellSource("c1", "42", name="renamed")], {})
+ assert snapshot.document.app_config == {"nested": {"items": [1]}}
+ assert snapshot.cells[0].code == "import marimo as mo"
+ assert snapshot.cells[-1].config == HIDDEN
+ snapshot.document.app_config["another"] = True
+ assert document._record.app_config == {}
diff --git a/tests/_core/test_protocol.py b/tests/_core/test_protocol.py
index 0df46b035f..4c625c83ec 100644
--- a/tests/_core/test_protocol.py
+++ b/tests/_core/test_protocol.py
@@ -20,6 +20,7 @@ FIXTURES = (
MODELS = {
"record.json": protocol.HostRecord,
"cell.json": protocol.Cell,
+ "analysis.json": protocol.Analysis,
"diagnostic.json": protocol.Error,
"edit.json": protocol.EditRequest,
"edit-conflict-request.json": protocol.EditRequest,
diff --git a/tests/_server/host/test_host_analysis.py b/tests/_server/host/test_host_analysis.py
index a6733fa25e..3651ccdee9 100644
--- a/tests/_server/host/test_host_analysis.py
+++ b/tests/_server/host/test_host_analysis.py
@@ -3,10 +3,32 @@
from __future__ import annotations
+import asyncio
+import threading
+from unittest.mock import Mock
+
import pytest
+from marimo._ast.cell import CellImpl
+from marimo._ast.compiler import compile_cell
from marimo._core import protocol
-from marimo._server.host.analysis import Analyzer, analyze
+from marimo._core.document import CellSource, Document, DocumentSnapshot
+from marimo._server.host.analysis import CellAnalyzer, HostAnalyzer
+from marimo._types.ids import CellId_t
+
+
+def snapshot(codes: dict[str, str]) -> DocumentSnapshot:
+ return Document(
+ protocol.NotebookId("n1"),
+ [CellSource(cid, code) for cid, code in codes.items()],
+ {},
+ ).snapshot()
+
+
+def analyze(
+ codes: dict[str, str],
+) -> dict[protocol.CellId, protocol.CellAnalysis]:
+ return CellAnalyzer()(snapshot(codes))
def test_refs_are_names_other_cells_define() -> None:
@@ -19,7 +41,9 @@ def test_refs_are_names_other_cells_define() -> None:
)
assert analyses["a"].defs == ("mo",)
assert analyses["a"].refs == ("x",)
- assert analyses["b"] == protocol.Analysis(defs=("x",), refs=(), errors=())
+ assert analyses["b"] == protocol.CellAnalysis(
+ defs=("x",), refs=(), errors=()
+ )
assert analyses["c"].refs == ("x",)
@@ -55,7 +79,7 @@ def test_positions_count_utf16_code_units() -> None:
def test_an_analyzer_kept_between_edits_matches_a_fresh_one() -> None:
- analyzer = Analyzer()
+ analyzer = CellAnalyzer()
steps = [
{"a": "x = 1", "b": "y = x"},
{"a": "x = 1", "b": "y = x", "c": "x = 2"},
@@ -65,14 +89,14 @@ def test_an_analyzer_kept_between_edits_matches_a_fresh_one() -> None:
{"b": "def (:", "c": "z = y"},
]
for codes in steps:
- assert analyzer(codes) == analyze(codes), codes
+ assert analyzer(snapshot(codes)) == analyze(codes), codes
def test_analyzer_retries_after_an_unexpected_compiler_failure(
monkeypatch: pytest.MonkeyPatch,
) -> None:
- analyzer = Analyzer()
- analyzer({"a": "x = 1"})
+ analyzer = CellAnalyzer()
+ analyzer(snapshot({"a": "x = 1"}))
codes = {"a": "y = 2", "b": "z = y"}
def fail(*_args: object, **_kwargs: object) -> None:
@@ -81,6 +105,119 @@ def test_analyzer_retries_after_an_unexpected_compiler_failure(
with monkeypatch.context() as patch:
patch.setattr("marimo._server.host.analysis.compile_cell", fail)
with pytest.raises(RuntimeError, match="compiler failed"):
- analyzer(codes)
+ analyzer(snapshot(codes))
+
+ assert analyzer(snapshot(codes)) == analyze(codes)
+
+
+async def test_host_analyzer_reports_each_revision_off_the_loop(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ loop = asyncio.get_running_loop()
+ started = asyncio.Event()
+ release = threading.Event()
+ codes = {"a": "x = 1", "b": "y = x"}
+ expected = analyze(codes)
+
+ def blocked_compile(code: str, cell_id: CellId_t) -> CellImpl:
+ loop.call_soon_threadsafe(started.set)
+ if not release.wait(timeout=5):
+ raise TimeoutError("the event loop did not release compilation")
+ return compile_cell(code, cell_id)
+
+ monkeypatch.setattr(
+ "marimo._server.host.analysis.compile_cell", blocked_compile
+ )
+ analyzer = HostAnalyzer()
+ reported = asyncio.create_task(analyzer.analyze(snapshot(codes)))
+ try:
+ await asyncio.wait_for(started.wait(), timeout=5)
+ # The loop must resume while compilation is still blocked.
+ assert not reported.done()
+ finally:
+ release.set()
+ result = await asyncio.wait_for(reported, timeout=5)
- assert analyzer(codes) == analyze(codes)
+ assert result == expected
+
+
+async def test_host_analyzer_raises_unexpected_failures(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ analyzer = HostAnalyzer()
+
+ def fail(*_: object, **__: object) -> None:
+ raise RuntimeError("boom")
+
+ monkeypatch.setattr("marimo._server.host.analysis.compile_cell", fail)
+ with pytest.raises(RuntimeError, match="boom"):
+ await analyzer.analyze(snapshot({"a": "x = 1"}))
+
+
+def test_compilation_cache_uses_identity_and_code_hash(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ compiler = Mock(wraps=compile_cell)
+ monkeypatch.setattr("marimo._server.host.analysis.compile_cell", compiler)
+ analyzer = CellAnalyzer()
+ document = Document(
+ protocol.NotebookId("n1"),
+ [
+ CellSource("a", "x = 1"),
+ CellSource("b", "y = x"),
+ CellSource("bad", "def (:"),
+ ],
+ {},
+ )
+ analyzer(document.snapshot())
+ assert compiler.call_count == 3
+
+ # Names, configuration, and order are visible without recompiling code.
+ document.replace(
+ [
+ CellSource("b", "y = x", name="renamed"),
+ CellSource("a", "x = 1"),
+ CellSource("bad", "def (:"),
+ ],
+ {"width": "full"},
+ )
+ analyzer(document.snapshot())
+ assert compiler.call_count == 3
+
+ # An unchanged cell loses its reference when its provider changes.
+ document.replace([CellSource("a", "z = 1"), CellSource("b", "y = x")], {})
+ assert analyzer(document.snapshot())[protocol.CellId("b")].refs == ()
+ assert compiler.call_count == 4
+
+ document.replace([CellSource("b", "y = x")], {})
+ analyzer(document.snapshot())
+ document.replace([CellSource("a", "z = 1"), CellSource("c", "y = x")], {})
+ analyzer(document.snapshot())
+ assert compiler.call_count == 6
+
+
[email protected]("reverse", [False, True])
+ ("provider", "consumer", "refs"),
+ [
+ ('mo.sql("CREATE TABLE t (id INT)")', "print(t)", ()),
+ (
+ 'mo.sql("CREATE TABLE s.t (id INT)")',
+ 'mo.sql("SELECT * FROM s.t")',
+ ("s.t",),
+ ),
+ (
+ 'mo.sql("CREATE TABLE s.t (id INT)")',
+ 'mo.sql("SELECT * FROM other.t")',
+ (),
+ ),
+ ("t = 1", 'mo.sql("SELECT * FROM t")', ("t",)),
+ ],
+)
+def test_references_follow_runtime_language_semantics(
+ provider, consumer, refs, reverse
+):
+ cells = [("provider", provider), ("consumer", consumer)]
+ if reverse:
+ cells.reverse()
+ assert analyze(dict(cells))[protocol.CellId("consumer")].refs == refs
diff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.py
index 4b64c2b822..bdb6768ca7 100644
--- a/tests/_server/host/test_host_api.py
+++ b/tests/_server/host/test_host_api.py
@@ -16,6 +16,7 @@ from starlette.routing import Route
from marimo._core import backend as be, protocol
from marimo._core.host import Host
+from marimo._core.notebook import Notebook
from marimo._core.protocol import ProjectMessage
from marimo._core.run_log import RetentionPolicy
from marimo._server.host import api as api_module
@@ -45,6 +46,16 @@ TOKEN = "record-token"
AUTH = {"Authorization": f"Bearer {TOKEN}"}
+async def analyzed(notebook: Notebook) -> protocol.Analysis:
+ """Wait for the notebook's analysis, which runs off the event loop."""
+ deadline = asyncio.get_running_loop().time() + 5
+ while notebook.analysis is None:
+ if asyncio.get_running_loop().time() > deadline:
+ raise TimeoutError("the notebook was not analyzed")
+ await asyncio.sleep(0.01)
+ return notebook.analysis
+
+
def key(value: str) -> dict[str, str]:
return {**AUTH, "Idempotency-Key": value}
@@ -469,6 +480,7 @@ 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 = await harness.host.notebook(harness.notebook_id)
+ await analyzed(notebook)
response, task, disconnect = request(
harness.app, "GET", f"/notebooks/{notebook.id}/events", headers=AUTH
)
@@ -478,13 +490,14 @@ async def test_a_notebook_stream_attaches_the_client(harness: Harness) -> None:
"notebook",
"cell",
"document",
+ "analysis",
"attachment",
"ready",
]
assert response.records[2]["data"]["document"]["order"] == [
response.records[1]["data"]["cell"]["id"]
]
- assert response.records[3]["data"]["attachment"]["kind"] == "client"
+ assert response.records[4]["data"]["attachment"]["kind"] == "client"
disconnect()
await asyncio.wait_for(task, 5)
@@ -492,6 +505,7 @@ async def test_a_notebook_stream_attaches_the_client(harness: Harness) -> None:
"notebook",
"cell",
"document",
+ "analysis",
"ready",
]
@@ -1437,9 +1451,10 @@ async def test_the_notebook_stream_carries_cells_then_the_document(
f"/notebooks/{harness.notebook_id}/events",
headers=AUTH,
)
- await wait_for(response, until_ready)
+ await wait_for(response, lambda r: "analysis" in r.names())
disconnect()
+ # The document is served as soon as it is read; its analysis follows.
assert response.names() == [
"notebook",
"cell",
@@ -1447,14 +1462,14 @@ async def test_the_notebook_stream_carries_cells_then_the_document(
"document",
"attachment",
"ready",
+ "analysis",
]
first, second = (r["data"]["cell"] for r in response.records[1:3])
document = response.records[3]["data"]["document"]
+ analysis = response.records[6]["data"]["analysis"]
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"
@@ -1462,6 +1477,12 @@ async def test_the_notebook_stream_carries_cells_then_the_document(
assert all(
c["notebook_id"] == harness.notebook_id for c in (first, second)
)
+ assert analysis["notebook_id"] == harness.notebook_id
+ assert analysis["document_etag"] == document["etag"]
+ assert analysis["cells"] == {
+ first["id"]: {"defs": ["x"], "refs": [], "errors": []},
+ second["id"]: {"defs": ["y"], "refs": ["x"], "errors": []},
+ }
# A filtered stream is a snapshot of the document alone, and a second
# connection reuses the loaded document.