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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
from contextlib import contextmanager
from typing import TYPE_CHECKING
import pytest
from marimo._ast.cell_id import CellIdGenerator
from marimo._code_mode._context import (
AsyncCodeModeContext,
StaleCellError,
)
from marimo._messaging.notebook.changes import SetCode, Transaction
from marimo._messaging.notebook.document import (
NotebookCell,
NotebookDocument,
notebook_document_context,
)
from marimo._runtime.commands import ExecuteCellCommand
from marimo._types.ids import CellId_t
if TYPE_CHECKING:
from collections.abc import Generator
from marimo._runtime.runtime import Kernel
@contextmanager
def _ctx(
k: Kernel,
*,
skip_staleness_check: bool = False,
) -> Generator[AsyncCodeModeContext, None, None]:
cells = [
NotebookCell(id=cid, code=cell.code, name="", config=cell.config)
for cid, cell in k.graph.cells.items()
]
doc = NotebookDocument(cells)
with notebook_document_context(doc):
ctx = AsyncCodeModeContext(
k, skip_staleness_check=skip_staleness_check
)
ctx._id_generator = CellIdGenerator(seed=7)
ctx._id_generator.seen_ids = set(doc.cell_ids)
yield ctx
async def _seed(k: Kernel, cell_id: str, code: str) -> None:
await k.run([ExecuteCellCommand(cell_id=CellId_t(cell_id), code=code)])
def _bump_cell_version(doc: NotebookDocument, cell_id: str, code: str) -> None:
doc.apply(
Transaction(
changes=(SetCode(cell_id=CellId_t(cell_id), code=code),),
source="frontend",
)
)
class TestStalenessBlocks:
async def test_edit_without_read_raises(self, k: Kernel) -> None:
await _seed(k, "0", "a = 1")
with _ctx(k) as ctx:
async with ctx as nb:
with pytest.raises(StaleCellError) as exc:
nb.edit_cell("0", "a = 2")
assert exc.value.cell_id == CellId_t("0")
assert CellId_t("0") in exc.value.stale_cells
async def test_edit_after_read_succeeds(self, k: Kernel) -> None:
await _seed(k, "0", "a = 1")
with _ctx(k) as ctx:
async with ctx as nb:
_ = nb.cells["0"].code # materialize == read
nb.edit_cell("0", "a = 2")
async def test_read_persists_across_contexts(self, k: Kernel) -> None:
# kernel.agent is long-lived, so a read satisfies a future call's
# check as long as the cell's version hasn't been bumped since.
await _seed(k, "0", "a = 1")
with _ctx(k) as ctx:
async with ctx as nb:
_ = nb.cells["0"].code
with _ctx(k) as ctx:
async with ctx as nb:
nb.edit_cell("0", "a = 2")
async def test_frontend_edit_invalidates_prior_read(
self, k: Kernel
) -> None:
await _seed(k, "0", "a = 1")
with _ctx(k) as ctx:
async with ctx as nb:
_ = nb.cells["0"].code
with _ctx(k) as ctx:
_bump_cell_version(ctx._document, "0", "a = 99")
async with ctx as nb:
with pytest.raises(StaleCellError):
nb.edit_cell("0", "a = 2")
class TestStalenessExemptions:
async def test_pending_add_then_edit(self, k: Kernel) -> None:
with _ctx(k) as ctx:
async with ctx as nb:
cid = nb.create_cell("x = 1")
nb.edit_cell(cid, "x = 2")
async def test_config_only_edit_does_not_check(self, k: Kernel) -> None:
await _seed(k, "0", "a = 1")
with _ctx(k) as ctx:
async with ctx as nb:
nb.edit_cell("0", hide_code=False)
async def test_delete_cell_not_protected(self, k: Kernel) -> None:
await _seed(k, "0", "a = 1")
with _ctx(k) as ctx:
async with ctx as nb:
nb.delete_cell("0")
async def test_move_cell_not_protected(self, k: Kernel) -> None:
await _seed(k, "0", "a = 1")
await _seed(k, "1", "b = 2")
with _ctx(k) as ctx:
async with ctx as nb:
nb.move_cell("0", after="1")
async def test_skip_staleness_check_opt_out(self, k: Kernel) -> None:
await _seed(k, "0", "a = 1")
with _ctx(k, skip_staleness_check=True) as ctx:
async with ctx as nb:
nb.edit_cell("0", "a = 2")
class TestStaleCellErrorMessage:
async def test_lists_other_stale_cells(self, k: Kernel) -> None:
await _seed(k, "0", "a = 1")
await _seed(k, "1", "b = 2")
await _seed(k, "2", "c = 3")
with _ctx(k) as ctx:
async with ctx as nb:
with pytest.raises(StaleCellError) as exc:
nb.edit_cell("0", "a = 999")
assert exc.value.stale_cells == frozenset(
{CellId_t("0"), CellId_t("1"), CellId_t("2")}
)
msg = str(exc.value)
assert "'0'" in msg
assert "Other stale cells: 1, 2." in msg
assert "skip_staleness_check=True" in msg
class TestCrossContextWriteRead:
async def test_create_then_edit_cross_context(self, k: Kernel) -> None:
with _ctx(k) as ctx:
async with ctx as nb:
cid = nb.create_cell("x = 1")
nb.run_cell(cid)
with _ctx(k) as ctx:
async with ctx as nb:
nb.edit_cell(cid, "x = 2")
async def test_edit_then_edit_cross_context(self, k: Kernel) -> None:
await _seed(k, "0", "a = 1")
with _ctx(k) as ctx:
async with ctx as nb:
_ = nb.cells["0"].code
nb.edit_cell("0", "a = 2")
with _ctx(k) as ctx:
async with ctx as nb:
nb.edit_cell("0", "a = 3")
class TestFileWatchReload:
async def test_same_code_keeps_reads_valid(self, k: Kernel) -> None:
await _seed(k, "0", "a = 1")
with _ctx(k) as ctx:
async with ctx as nb:
_ = nb.cells["0"].code
with _ctx(k) as ctx:
ctx._document.apply(
Transaction(
changes=(SetCode(cell_id=CellId_t("0"), code="a = 1"),),
source="file-watch",
)
)
async with ctx as nb:
nb.edit_cell("0", "a = 2")
async def test_changed_code_invalidates_reads(self, k: Kernel) -> None:
await _seed(k, "0", "a = 1")
with _ctx(k) as ctx:
async with ctx as nb:
_ = nb.cells["0"].code
with _ctx(k) as ctx:
ctx._document.apply(
Transaction(
changes=(SetCode(cell_id=CellId_t("0"), code="a = 100"),),
source="file-watch",
)
)
async with ctx as nb:
with pytest.raises(StaleCellError):
nb.edit_cell("0", "a = 2")
class TestEmptyCellExemption:
async def test_edit_empty_cell_without_read(self, k: Kernel) -> None:
await _seed(k, "0", "")
with _ctx(k) as ctx:
async with ctx as nb:
nb.edit_cell("0", "x = 1")
async def test_edit_whitespace_cell_without_read(self, k: Kernel) -> None:
await _seed(k, "0", " \n ")
with _ctx(k) as ctx:
async with ctx as nb:
nb.edit_cell("0", "x = 1")
async def test_non_empty_cell_still_requires_read(self, k: Kernel) -> None:
await _seed(k, "0", "a = 1")
with _ctx(k) as ctx:
async with ctx as nb:
with pytest.raises(StaleCellError):
nb.edit_cell("0", "x = 1")
async def test_two_edits_on_empty_cell_same_context(
self, k: Kernel
) -> None:
await _seed(k, "0", "")
with _ctx(k) as ctx:
async with ctx as nb:
nb.edit_cell("0", "x = 1")
nb.edit_cell("0", "x = 2")
async def test_empty_then_non_empty_edit_cross_context(
self, k: Kernel
) -> None:
# First edit lands via empty-cell exemption; the agent's own write
# records a read, so the next-context edit passes without a fresh
# materialization even though the cell is now non-empty.
await _seed(k, "0", "")
with _ctx(k) as ctx:
async with ctx as nb:
nb.edit_cell("0", "x = 1")
with _ctx(k) as ctx:
async with ctx as nb:
nb.edit_cell("0", "x = 2")
async def test_empty_cells_excluded_from_stale_error_list(
self, k: Kernel
) -> None:
await _seed(k, "empty", "")
await _seed(k, "real", "a = 1")
with _ctx(k) as ctx:
async with ctx as nb:
with pytest.raises(StaleCellError) as exc:
nb.edit_cell("real", "a = 2")
assert exc.value.stale_cells == frozenset({CellId_t("real")})
class TestSetupCellMigration:
async def test_rename_to_setup_without_read_raises(
self, k: Kernel
) -> None:
# The migration path silently fills `code` from `self.graph.cells`
# when the agent passes `name="setup"` with `code=None`. Without
# the post-migration staleness check, that fill could overwrite
# the doc with stale graph code without ever requiring a read.
await _seed(k, "0", "x = 1")
with _ctx(k) as ctx:
async with ctx as nb:
with pytest.raises(StaleCellError):
nb.edit_cell("0", name="setup")
async def test_rename_to_setup_after_read_succeeds(
self, k: Kernel
) -> None:
await _seed(k, "0", "x = 1")
with _ctx(k) as ctx:
async with ctx as nb:
_ = nb.cells["0"].code
nb.edit_cell("0", name="setup")
class TestCellsViewReadRecording:
"""Reads record on `.code` access, never on wrapper construction.
Indexing, iteration, find, and grep all just hand out wrappers — they
do not by themselves prove the agent has seen the code. Without this
invariant, `first = ctx.cells[0]; ctx.edit_cell(first.id, ...)` would
blindly clobber code the agent never looked at.
"""
async def test_indexing_alone_does_not_satisfy_staleness(
self, k: Kernel
) -> None:
await _seed(k, "0", "a = 1")
with _ctx(k) as ctx:
async with ctx as nb:
first = nb.cells[0] # wrapper only — no .code access
with pytest.raises(StaleCellError):
nb.edit_cell(first.id, "a = 2")
async def test_indexing_then_code_access_satisfies_staleness(
self, k: Kernel
) -> None:
await _seed(k, "0", "a = 1")
with _ctx(k) as ctx:
async with ctx as nb:
first = nb.cells[0]
_ = first.code # this is the access that counts
nb.edit_cell(first.id, "a = 2")
async def test_iteration_alone_does_not_record_reads(
self, k: Kernel
) -> None:
await _seed(k, "0", "a = 1")
await _seed(k, "1", "b = 2")
with _ctx(k) as ctx:
async with ctx as nb:
for _ in nb.cells:
pass
with pytest.raises(StaleCellError):
nb.edit_cell("0", "a = 99")
async def test_iteration_with_code_access_records_reads(
self, k: Kernel
) -> None:
await _seed(k, "0", "a = 1")
await _seed(k, "1", "b = 2")
with _ctx(k) as ctx:
async with ctx as nb:
for cell in nb.cells:
_ = cell.code
nb.edit_cell("0", "a = 99")
nb.edit_cell("1", "b = 99")
async def test_find_does_not_record_reads(self, k: Kernel) -> None:
# find returns matched wrappers but the agent has not seen the
# source — only that a substring matched. Editing without a
# follow-up `.code` read must still raise.
await _seed(k, "0", "alpha = 1")
await _seed(k, "1", "beta = 2")
with _ctx(k) as ctx:
async with ctx as nb:
matches = nb.cells.find("alpha")
assert len(matches) == 1
with pytest.raises(StaleCellError):
nb.edit_cell("0", "alpha = 99")
async def test_grep_does_not_record_reads(self, k: Kernel) -> None:
await _seed(k, "0", "alpha = 1")
await _seed(k, "1", "beta = 2")
with _ctx(k) as ctx:
async with ctx as nb:
matches = nb.cells.grep(r"alpha")
assert len(matches) == 1
with pytest.raises(StaleCellError):
nb.edit_cell("0", "alpha = 99")
async def test_repr_records_reads(self, k: Kernel) -> None:
# `repr(ctx.cells)` shows first-line code previews of every cell,
# so the agent has seen source snippets — editing without a
# separate read must succeed.
await _seed(k, "0", "a = 1")
await _seed(k, "1", "b = 2")
with _ctx(k) as ctx:
async with ctx as nb:
_ = repr(nb.cells)
nb.edit_cell("0", "a = 99")
nb.edit_cell("1", "b = 99")
async def test_notebook_cell_repr_records_read(self, k: Kernel) -> None:
# NotebookCell.__repr__ embeds a code preview via `self.code`, so
# repr-ing a single cell counts as a read.
await _seed(k, "0", "a = 1")
with _ctx(k) as ctx:
async with ctx as nb:
_ = repr(nb.cells[0])
nb.edit_cell("0", "a = 2")