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.
"""Run and execution transitions, without a stream or a backend."""
from __future__ import annotations
import dataclasses
import pytest
from dirty_equals import IsDatetime
from msgspec.structs import replace
from marimo._core import backend as be, protocol
from marimo._core.document import Document, DocumentCell
from marimo._core.errors import NoRuntime
from marimo._core.executions import (
CellExecution,
Change,
Executions,
Released,
Removed,
)
from marimo._core.stream import utcnow
from tests._core.conftest import retained_execution
NOTEBOOK = protocol.NotebookId("n1")
RUNTIME = protocol.Runtime(
id=protocol.RuntimeId("rt-1"),
notebook_id=NOTEBOOK,
status="running",
message=None,
marimo_version=None,
started_at=utcnow(),
)
def run(run_id: str) -> protocol.Run:
return protocol.Run(
id=protocol.RunId(run_id),
notebook_id=NOTEBOOK,
caused_by=None,
status="queued",
outcome=None,
started_at=None,
completed_at=None,
)
def planned(run_id: str, *executions: tuple[str, str | None]) -> be.Planned:
"""Plan executions as `(id, cell_id)` pairs; a `None` cell is scratch."""
return be.Planned(
protocol.RunId(run_id),
tuple(
be.PlannedExecution(
protocol.ExecutionId(eid),
cell,
"hash",
"code" if cell is None else None,
)
for eid, cell in executions
),
)
def complete(
executions: Executions,
eid: str,
outcome: protocol.Outcome | None = None,
) -> list[Change]:
execution = protocol.ExecutionId(eid)
changes: list[Change] = []
for msg in (
be.Started(execution),
be.Completed(execution, outcome or protocol.ValueOutcome(None)),
):
changes.extend(executions.observe(msg, RUNTIME))
return changes
def describe(changes: list[Change]) -> list[str]:
"""Render changes as `kind id`, with `.removed` and `released` marked."""
out: list[str] = []
for change in changes:
if isinstance(change, Released):
out.append(f"released {change.run_id}")
elif isinstance(change, Removed):
out.append(
f"{change.record_type.__name__.lower()}.removed {change.id}"
)
else:
out.append(f"{type(change).__name__.lower()} {change.id}")
return out
def variable(execution_id: str = "e1") -> protocol.Variable:
return protocol.Variable(
execution_id=protocol.ExecutionId(execution_id),
id=protocol.ItemId("v1"),
name="x",
preview="1",
revision=protocol.Revision(protocol.ExecutionId(execution_id), 0),
type="int",
)
@pytest.mark.parametrize("started", [False, True])
def test_completion_freezes_the_outcome_and_input_revisions(
started: bool,
) -> None:
executions = Executions()
executions.begin(run("r1"), "request")
[queued] = executions.observe(planned("r1", ("e1", "a")), RUNTIME)
assert isinstance(queued, protocol.Execution)
eid = queued.id
if started:
executions.observe(be.Started(eid), RUNTIME)
executions.observe(
be.Concluded(eid, protocol.ValueOutcome(None)), RUNTIME
)
inputs = {
"x": protocol.Revision(protocol.ExecutionId("producer"), 2),
"print": None,
}
completed = be.Completed(eid, protocol.InterruptedOutcome(), inputs)
assert executions.observe(completed, RUNTIME) == [
replace(
queued,
status="completed",
outcome=protocol.InterruptedOutcome(),
depends_on=inputs,
started_at=IsDatetime() if started else None,
completed_at=IsDatetime(),
)
]
retained = executions.current(protocol.CellId("a"))
inputs.clear()
for message in (
be.Started(eid),
be.Concluded(eid, protocol.ValueOutcome(None)),
be.Completed(eid, protocol.ValueOutcome(None)),
):
assert executions.observe(message, RUNTIME) == []
assert executions.current(protocol.CellId("a")) == retained
def test_a_cell_result_outlives_its_run_until_the_next_replaces_it() -> None:
executions = Executions()
executions.begin(run("r1"), "first")
executions.observe(planned("r1", ("e1", "a")), RUNTIME)
bound = variable()
assert executions.observe(be.Produced(bound), RUNTIME) == [bound]
complete(executions, "e1")
done = executions.observe(
be.Done(protocol.RunId("r1"), "succeeded"), RUNTIME
)
assert describe(done) == ["run r1"]
assert executions.active() is None
assert describe(executions._records()) == [
"run r1",
"execution e1",
"variable v1",
]
assert executions.request_id(protocol.RunId("r1")) == "first"
assert executions.snapshot_request(protocol.RunId("r1")) is None
before = executions.current(protocol.CellId("a"))
assert before is not None
updated = replace(
bound, preview="2", revision=replace(bound.revision, update=1)
)
assert executions.observe(be.Produced(updated), RUNTIME) == [updated]
assert executions.current(protocol.CellId("a")) == dataclasses.replace(
before, variables=(updated,)
)
assert before.variables == (bound,)
executions.begin(run("r2"), "second")
replaced = executions.observe(planned("r2", ("e2", "a")), RUNTIME)
assert describe(replaced) == [
"variable.removed v1",
"execution.removed e1",
"released r1",
"execution e2",
]
executions.release(protocol.RunId("r1"))
assert executions.run(protocol.RunId("r1")) is None
assert describe(executions._records()) == ["run r2", "execution e2"]
assert executions.observe(be.Produced(updated), RUNTIME) == []
def test_scratch_work_leaves_with_its_run() -> None:
executions = Executions()
executions.begin(run("r1"), "request")
executions.observe(planned("r1", ("e1", None)), RUNTIME)
assert executions.observe(be.Produced(variable()), RUNTIME) == []
produced = executions.observe(
be.Produced(
protocol.Console(
protocol.ExecutionId("e1"),
protocol.ItemId("c1"),
"stdout",
0,
"x",
)
),
RUNTIME,
)
assert describe(produced) == ["console c1"]
assert executions.run_id_of(produced[0]) == "r1"
complete(executions, "e1")
done = executions.observe(
be.Done(protocol.RunId("r1"), "succeeded"), RUNTIME
)
assert describe(done) == ["run r1", "released r1"]
executions.release(protocol.RunId("r1"))
assert executions._records() == []
def test_a_run_completes_only_after_its_executions_and_reports_failures() -> (
None
):
executions = Executions()
executions.begin(run("r1"), "request")
executions.observe(planned("r1", ("e1", "a")), RUNTIME)
executions.observe(be.Started(protocol.ExecutionId("e1")), RUNTIME)
with pytest.raises(ValueError, match="unfinished"):
executions.observe(be.Done(protocol.RunId("r1"), "succeeded"), RUNTIME)
complete(executions, "e1", protocol.InterruptedOutcome())
with pytest.raises(ValueError, match="successful"):
executions.observe(be.Done(protocol.RunId("r1"), "succeeded"), RUNTIME)
done = executions.observe(be.Done(protocol.RunId("r1"), "failed"), RUNTIME)
assert [
change.outcome for change in done if isinstance(change, protocol.Run)
] == ["failed"]
def test_interrupting_completes_everything_in_flight() -> None:
executions = Executions()
executions.begin(run("r1"), "request")
executions.observe(planned("r1", ("e1", "a"), ("e2", None)), RUNTIME)
for eid in ("e1", "e2"):
executions.observe(be.Started(protocol.ExecutionId(eid)), RUNTIME)
changes = executions.interrupt()
assert describe(changes) == ["execution e1", "execution e2", "run r1"]
assert all(
isinstance(change.outcome, protocol.InterruptedOutcome)
for change in changes
if isinstance(change, protocol.Execution)
)
# The scratch execution is forgotten silently; the cell result stays.
assert describe(executions._records()) == ["run r1", "execution e1"]
def test_clearing_removes_results_and_releases_runs() -> None:
executions = Executions()
executions.begin(run("r1"), "request")
executions.observe(planned("r1", ("e1", "a")), RUNTIME)
executions.observe(
be.Produced(
protocol.Console(
protocol.ExecutionId("e1"),
protocol.ItemId("c1"),
"stdout",
0,
"x",
)
),
RUNTIME,
)
complete(executions, "e1")
executions.observe(be.Done(protocol.RunId("r1"), "succeeded"), RUNTIME)
assert describe(executions.clear()) == [
"console.removed c1",
"execution.removed e1",
"released r1",
]
def test_scheduling_needs_a_runtime_but_stray_updates_do_not() -> None:
executions = Executions()
with pytest.raises(NoRuntime):
executions.observe(be.Scheduled(protocol.RunId("r1")), None)
assert (
executions.observe(be.Started(protocol.ExecutionId("e1")), None) == []
)
scheduled = executions.observe(be.Scheduled(protocol.RunId("r1")), RUNTIME)
assert describe(scheduled) == ["run r1"]
assert executions.request_id(protocol.RunId("r1")) is None
def test_planning_does_not_scan_unrelated_cells(
monkeypatch: pytest.MonkeyPatch,
) -> None:
executions = Executions()
executions.begin(run("r1"), "request")
visits = 0
getattribute = protocol.Execution.__getattribute__
def counted(execution: protocol.Execution, name: str) -> object:
nonlocal visits
if name == "cell_id":
visits += 1
return getattribute(execution, name)
monkeypatch.setattr(protocol.Execution, "__getattribute__", counted)
changes = executions.observe(
planned("r1", *((str(index), str(index)) for index in range(1000))),
RUNTIME,
)
assert visits <= 3000
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.Started(protocol.ExecutionId("e2")), 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([DocumentCell("c1", "42")], {})
retained = dataclasses.replace(
retained_execution(run_id="old-run"), variables=(variable("restored"),)
)
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",
"variable v1",
]
executions.begin(run("r1"), "request")
changes = executions.observe(planned("r1", ("e1", "c1")), RUNTIME)
assert describe(changes) == [
"console.removed restored-output",
"variable.removed v1",
"execution.removed restored",
"execution e1",
]
assert executions.current(protocol.CellId("c1")) is None
@pytest.mark.parametrize(
("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"),
("variable-owner", "belong to their execution"),
("duplicate-item", "unique"),
],
)
def test_restore_rejects_inconsistent_executions(
invalid: str, message: str
) -> None:
document = Document([DocumentCell("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")),),
)
elif invalid == "variable-owner":
retained = dataclasses.replace(
retained, variables=(variable("other"),)
)
elif invalid == "duplicate-item":
retained = dataclasses.replace(
retained,
variables=(replace(variable("restored"), id=outputs[0].id),),
)
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")
assert executions.current(cell_id) is None
executions.begin(run("r1"), "request")
executions.observe(planned("r1", ("e1", "a")), RUNTIME)
output = protocol.Display(
execution_id=protocol.ExecutionId("e1"),
id=protocol.ItemId("d1"),
seq=0,
mimetype="application/json",
data='{"values":[1]}',
)
executions.observe(be.Produced(output), RUNTIME)
assert executions.current(cell_id) is None
complete(executions, "e1")
result = executions.current(cell_id)
assert result is not None
assert result.outputs == (output,)
updated = protocol.Display(
execution_id=output.execution_id,
id=output.id,
seq=output.seq,
mimetype=output.mimetype,
data='{"values":[1,2]}',
)
executions.observe(be.Produced(updated), RUNTIME)
current = executions.current(cell_id)
assert current is not None
assert current.outputs == (updated,)
assert result.outputs[0].data == '{"values":[1]}'