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.
"""Host fixtures with a backend that records commands."""
from __future__ import annotations
import asyncio
from typing import TYPE_CHECKING
import msgspec
import pytest
from marimo._core import backend as be, protocol, protocol_events
from marimo._core.document import Document, DocumentCell, code_hash
from marimo._core.executions import CellExecution, Executions
from marimo._core.host import Host
from marimo._core.notebook import Notebook
from marimo._core.run_log import RetentionPolicy
from marimo._core.stream import RoutedEvent, Sink, event_name
if TYPE_CHECKING:
from collections.abc import Mapping, Sequence
OPERATIONS = ["notebook.create", "runtime.start", "runtime.run"]
class ScriptedBackend:
"""Records backend commands without executing them."""
def __init__(self) -> None:
self.calls: list[tuple[object, ...]] = []
def start(self, runtime_id: str) -> None:
self.calls.append(("start", runtime_id))
def stop(self, runtime_id: str) -> None:
self.calls.append(("stop", runtime_id))
def run(self, run_id: str, code: str) -> None:
self.calls.append(("run", run_id, code))
def run_cells(
self, run_id: str, document: Document, cell_ids: Sequence[str]
) -> None:
self.calls.append(
("run_cells", run_id, document.etag, tuple(cell_ids))
)
def interrupt(self, run_id: str) -> None:
self.calls.append(("interrupt", run_id))
def forget(self, run_id: str) -> None:
self.calls.append(("forget", run_id))
class ScriptedAnalyzer:
"""Expose snapshots and let tests complete analysis explicitly."""
def __init__(self) -> None:
self.requests: list[Document] = []
self.pending: asyncio.Queue[
tuple[
Document,
asyncio.Future[dict[protocol.CellId, protocol.CellAnalysis]],
]
] = asyncio.Queue()
async def analyze(
self, snapshot: Document
) -> 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[
Document,
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
return notebook.runtime.id
def project(project_id: str = "p1") -> protocol.Project:
return protocol.Project(
id=protocol.ProjectId(project_id),
name="forecasting",
root="/Users/me/forecasting",
status="indexed",
message=None,
operations=("notebook.create",),
)
def record(
notebook_id: str = "n1", path: str = "forecasts.py"
) -> protocol.Notebook:
return protocol.Notebook(
id=protocol.NotebookId(notebook_id),
project_id=protocol.ProjectId("p1"),
path=path,
name=path.removesuffix(".py"),
operations=("runtime.start", "runtime.run"),
updated_at=None,
)
def make_notebook(
record: protocol.Notebook,
sink: Sink,
backend: ScriptedBackend | None = None,
*,
document: Document | None = None,
analyzer: ScriptedAnalyzer | None = None,
) -> Notebook:
document = document if document is not None else Document([], {})
return Notebook(
record.id,
document,
Executions(),
backend or ScriptedBackend(),
sink,
saved_etag=document.etag,
analyzer=analyzer,
)
async def add_notebook(
host: Host,
record: protocol.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, analyzer=analyzer
),
)
return await host.notebook(record.id)
@pytest.fixture
def host() -> Host:
return Host(operations=OPERATIONS)
@pytest.fixture
def backend() -> ScriptedBackend:
return ScriptedBackend()
@pytest.fixture
async def notebook(host: Host, backend: ScriptedBackend) -> Notebook:
host.update_project(project())
return await add_notebook(host, record(), backend)
@pytest.fixture
def log(host: Host) -> list[RoutedEvent]:
"""Collect events published during the test."""
events: list[RoutedEvent] = []
host.subscribe(events.append, notebook_id="n1")
return events
class RecordingBridge:
"""A notebook bridge that counts edits and can hold one in flight."""
def __init__(self, host: Host) -> None:
self.host = host
self.edits = 0
self.started = asyncio.Event()
self.release = asyncio.Event()
self.release.set()
self.preconditions: list[Sequence[str] | None] = []
async def edit(
self,
notebook_id: str,
changes: Sequence[protocol.Change],
*,
request_id: str,
) -> protocol.EditResponse:
self.edits += 1
self.started.set()
await self.release.wait()
notebook = await self.host.notebook(notebook_id)
return notebook.edit(changes, request_id=request_id)
async def save(
self,
notebook_id: str,
*,
if_match: Sequence[str] | None,
decisions: Mapping[str, str],
request_id: str,
) -> protocol.EditResponse:
del decisions
self.preconditions.append(if_match)
notebook = await self.host.notebook(notebook_id)
return notebook.edit((), request_id=request_id)
@pytest.fixture
async def bridge() -> RecordingBridge:
host = Host(
operations=(
"notebook.edit",
"notebook.save",
"runtime.start",
"runtime.run",
)
)
host.update_project(project())
await add_notebook(
host,
msgspec.structs.replace(record(), operations=tuple(host.operations)),
ScriptedBackend(),
document=Document([DocumentCell(protocol.CellId("c1"), "x = 1")], {}),
)
return RecordingBridge(host)
def names(events: list[RoutedEvent]) -> list[str]:
return [event_name(e.event) for e in events]
def request_ids(events: list[RoutedEvent]) -> list[object]:
return [getattr(e.event.data, "request_id", None) for e in events]
class Clock:
now = 0.0
def __call__(self) -> float:
return self.now
async def host_at(clock: Clock, history: int = 1000) -> tuple[Host, Notebook]:
host = Host(
operations=[],
history=history,
clock=clock,
retention=RetentionPolicy(ephemeral_seconds=10),
)
host.update_project(project())
notebook = await add_notebook(host, record(), ScriptedBackend())
notebook.adopt(lambda _: None)
notebook.observe(be.Running(runtime_id_of(notebook)))
return host, notebook
def plan(
notebook: Notebook, run: protocol.Run, eid: str, cell: str | None = None
) -> protocol.ExecutionId:
execution = protocol.ExecutionId(eid)
notebook.observe(
be.Planned(
run.id,
(
be.PlannedExecution(
execution, cell, "hash", "code" if cell is None else None
),
),
)
)
notebook.observe(be.Started(execution))
return execution
def finish(notebook: Notebook, execution: protocol.ExecutionId) -> None:
notebook.observe(
be.Completed(
execution,
protocol.ValueOutcome(
protocol.DisplayData(mimetype="text/plain", data="value")
),
)
)
def fold(events: list[RoutedEvent], initial: dict | None = None) -> dict:
state = dict(initial or {})
for routed in events:
event = routed.event
if isinstance(event, protocol.ResetEvent):
state.clear()
elif isinstance(
event,
(
protocol.RunEvent,
protocol.ExecutionEvent,
protocol.ConsoleEvent,
protocol.DisplayEvent,
),
):
body = protocol_events.body(event)
state[event_name(event), body.id] = body
elif isinstance(
event,
(
protocol.RunRemovedEvent,
protocol.ExecutionRemovedEvent,
protocol.ConsoleRemovedEvent,
protocol.DisplayRemovedEvent,
),
):
state.pop(
(event_name(event).removesuffix(".removed"), event.data.id),
None,
)
return state
def retained_execution(
cell_id: str | None = "c1", run_id: str | None = None
) -> CellExecution:
"""A completed execution with one console item, as a store retains it."""
execution_id = protocol.ExecutionId("restored")
return CellExecution(
protocol.Execution(
id=execution_id,
run_id=None if run_id is None else protocol.RunId(run_id),
runtime_id=None,
caused_by=None,
cell_id=None if cell_id is None else protocol.CellId(cell_id),
code="42" if cell_id is None else None,
code_hash=code_hash("42"),
depends_on={},
status="completed",
outcome=protocol.ValueOutcome(
protocol.DisplayData(mimetype="text/plain", data="42")
),
started_at=None,
completed_at=None,
),
(
protocol.Console(
execution_id,
protocol.ItemId("restored-output"),
"stdout",
0,
"hello",
),
),
)