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
Name a document's notebook with `notebook_id` (#11255)
Trevor Manzbf1ced70cb63
diff --git a/marimo/_core/document.py b/marimo/_core/document.pyindex d1c9256333..978af39f68 100644--- a/marimo/_core/document.py+++ b/marimo/_core/document.py@@ -69,6 +69,11 @@ def document_etag(return etag("\n".join([order_etag, app_config_etag, *cell_etags]))+def normalize_code(code: str) -> str:+ """Convert line endings to newlines."""+ return code.replace("\r\n", "\n").replace("\r", "\n")++def default_config() -> protocol.CellConfig:return protocol.CellConfig(column=None, disabled=False, hide_code=False, expand_output=False@@ -85,6 +90,24 @@ class CellSource:config: protocol.CellConfig = field(default_factory=default_config)+def revision(+ cells: Sequence[CellSource], app_config: Mapping[str, Any]+) -> protocol.Etag:+ """The document etag these sources produce."""+ return document_etag(+ order_etag([source.id for source in cells]),+ app_config_etag(app_config),+ [+ cell_etag(+ code_hash(normalize_code(source.code)),+ source.name,+ source.config,+ )+ for source in cells+ ],+ )++@dataclass(frozen=True)class Changed:"""Changed cells, removed cell IDs, and the updated document."""@@ -150,10 +173,10 @@ class Document:raise ValueError("document order must contain every cell exactly once")- if any(cell.notebook_id != document.id for cell in cells):+ if any(cell.notebook_id != document.notebook_id for cell in cells):raise ValueError("cells must belong to the document")restored = cls(- document.id,+ document.notebook_id,[CellSource(cell.id, cell.code, cell.name, cell.config)for cell in (by_id[cell_id] for cell_id in document.order)@@ -249,7 +272,7 @@ class Document:return self._refresh()def _build(self, source: CellSource) -> protocol.Cell:- code = source.code.replace("\r\n", "\n").replace("\r", "\n")+ code = normalize_code(source.code)hashed = code_hash(code)return protocol.Cell(id=protocol.CellId(source.id),@@ -267,7 +290,7 @@ class Document:order = order_etag(self._order)app_config = app_config_etag(self._app_config)document = protocol.Document(- id=self._id,+ notebook_id=self._id,order=tuple(protocol.CellId(c) for c in self._order),app_config=dict(self._app_config),policy=self._policy,diff --git a/marimo/_core/host.py b/marimo/_core/host.pyindex 4a66957d33..2588cc4076 100644--- a/marimo/_core/host.py+++ b/marimo/_core/host.py@@ -79,7 +79,8 @@ class _NotebookRecords(Mapping[str, protocol.Notebook]):def _identity(event: Event) -> tuple[str, str]:assert event.kind is not None- return event.name, getattr(event.data, event.kind).id+ body = getattr(event.data, event.kind)+ return event.name, getattr(body, "id", None) or body.notebook_idclass Host:diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.pyindex 3845d7cfb0..f06910286d 100644--- a/marimo/_core/protocol.py+++ b/marimo/_core/protocol.py@@ -786,7 +786,7 @@ class Document(Struct, frozen=True):description="Identifies the document as currently applied. Its text is `order_etag`, `app_config_etag`, and every cell's `etag` in order, so it changes when any of them does."),]- id: Annotated[+ notebook_id: Annotated[NotebookId, Meta(description="The notebook this document belongs to.")]order: Annotated[diff --git a/marimo/_server/host/bridge.py b/marimo/_server/host/bridge.pyindex 1c801e5e0d..4b24599b80 100644--- a/marimo/_server/host/bridge.py+++ b/marimo/_server/host/bridge.py@@ -9,7 +9,7 @@ from typing import TYPE_CHECKING, Anyfrom marimo import _loggersfrom marimo._config.manager import ScriptConfigReaderfrom marimo._core import protocol-from marimo._core.document import CellSource, Document+from marimo._core.document import CellSource, Document, revisionfrom marimo._core.errors import Conflict, NotFoundfrom marimo._core.executions import Executionsfrom marimo._core.host import Host@@ -109,7 +109,7 @@ class SessionBridge(SessionEventListener):saved=session is None,)if session is not None and loaded is not None:- document.mark_saved(Document(record.id, *loaded)._record.etag)+ document.mark_saved(revision(*loaded))backend = self._make_backend(record.id)return Notebook(document, Executions(), backend, sink)diff --git a/protocols/host/conformance/contract.py b/protocols/host/conformance/contract.pyindex 28a1bce3c3..bd5f3eb60e 100644--- a/protocols/host/conformance/contract.py+++ b/protocols/host/conformance/contract.py@@ -203,7 +203,7 @@ def document_state(assert document is not None, "snapshot has no document"assert sorted(document["order"]) == sorted(cells)for cell in cells.values():- assert cell["notebook_id"] == document["id"]+ assert cell["notebook_id"] == document["notebook_id"]assert cell["code_hash"] == etag(cell["code"])config = cell["config"]parts = [cell["code_hash"], cell["name"]]diff --git a/protocols/host/fixtures/edit-response.json b/protocols/host/fixtures/edit-response.jsonindex 97c14f559e..5107900a64 100644--- a/protocols/host/fixtures/edit-response.json+++ b/protocols/host/fixtures/edit-response.json@@ -1,6 +1,6 @@{"document": {- "id": "n1",+ "notebook_id": "n1","order": ["c1","c2",diff --git a/protocols/host/fixtures/edits.sse b/protocols/host/fixtures/edits.sseindex 771fc655b7..187986001d 100644--- a/protocols/host/fixtures/edits.sse+++ b/protocols/host/fixtures/edits.sse@@ -12,9 +12,9 @@ data: {"id":"k7f2","request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2id: 113event: document-data: {"document":{"id":"n1","order":["c1","c2","c3"],"app_config":{"width":"full","app_title":"Forecasts"},"policy":"autorun","etag":"949c0dd20bc77042","saved_etag":"e59d9c2af02f5814","order_etag":"162e15055422ed71","app_config_etag":"1d79ec53fdad1a23"},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}+data: {"document":{"notebook_id":"n1","order":["c1","c2","c3"],"app_config":{"width":"full","app_title":"Forecasts"},"policy":"autorun","etag":"949c0dd20bc77042","saved_etag":"e59d9c2af02f5814","order_etag":"162e15055422ed71","app_config_etag":"1d79ec53fdad1a23"},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}id: 114event: document-data: {"document":{"id":"n1","order":["c1","c2","c3"],"app_config":{"width":"full","app_title":"Forecasts"},"policy":"autorun","etag":"949c0dd20bc77042","saved_etag":"949c0dd20bc77042","order_etag":"162e15055422ed71","app_config_etag":"1d79ec53fdad1a23"},"request_id":"save-9b1c6d2e","time":"2026-10-01T09:21:02Z"}+data: {"document":{"notebook_id":"n1","order":["c1","c2","c3"],"app_config":{"width":"full","app_title":"Forecasts"},"policy":"autorun","etag":"949c0dd20bc77042","saved_etag":"949c0dd20bc77042","order_etag":"162e15055422ed71","app_config_etag":"1d79ec53fdad1a23"},"request_id":"save-9b1c6d2e","time":"2026-10-01T09:21:02Z"}diff --git a/protocols/host/fixtures/notebook-events.sse b/protocols/host/fixtures/notebook-events.sseindex 16ab8c787a..f79536dd5a 100644--- a/protocols/host/fixtures/notebook-events.sse+++ b/protocols/host/fixtures/notebook-events.sse@@ -11,7 +11,7 @@ event: celldata: {"cell":{"id":"k7f2","notebook_id":"n1","code":"y = x * 2","name":"_","config":{"column":null,"disabled":false,"hide_code":true,"expand_output":false},"etag":"f199b5f48ae0aabb","code_hash":"db2b9ee97e1ecf4c","analysis":{"defs":["y"],"refs":["x"],"errors":[]}}}event: document-data: {"document":{"id":"n1","order":["c1","c3","k7f2"],"app_config":{"width":"full"},"policy":"autorun","etag":"e59d9c2af02f5814","saved_etag":"e59d9c2af02f5814","order_etag":"b9c412c2d7d63161","app_config_etag":"283513048dfeb45b"}}+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: runtimedata: {"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.jsonindex d73bd124f3..4a1a8c5a9a 100644--- a/protocols/host/fixtures/problems/edit-conflict.json+++ b/protocols/host/fixtures/problems/edit-conflict.json@@ -27,7 +27,7 @@}},"document": {- "id": "n1",+ "notebook_id": "n1","order": ["c1","c2",diff --git a/protocols/host/openapi.yaml b/protocols/host/openapi.yamlindex 90c6bc1ff9..53949b5a29 100644--- a/protocols/host/openapi.yaml+++ b/protocols/host/openapi.yaml@@ -1341,12 +1341,12 @@ components:objects: the cell order, app config, and host execution policy.The policy is retained for v1 compatibility and comes from theruntime configuration, not the notebook's app config. One per notebook,- identified by the notebook's id, and removed with it. The order and the app+ and removed with it. The order and the appconfig carry their own etags, so an edit to one does not conflictwith an edit to the other, or with edits to cells.- required: [id, order, app_config, policy, etag, saved_etag, order_etag, app_config_etag]+ required: [notebook_id, order, app_config, policy, etag, saved_etag, order_etag, app_config_etag]properties:- id:+ notebook_id:$ref: '#/components/schemas/NotebookId'description: The notebook this document belongs to.order:diff --git a/tests/_core/test_notebook_document.py b/tests/_core/test_notebook_document.pyindex c47702f5c1..cbed46aa17 100644--- a/tests/_core/test_notebook_document.py+++ b/tests/_core/test_notebook_document.py@@ -17,6 +17,7 @@ from marimo._core.document import (code_hash,document_etag,order_etag,+ revision,)from marimo._core.host import Hostfrom marimo._core.notebook import Notebook@@ -124,6 +125,14 @@ class TestEtags:order_etag(["a"]), app_config_etag({}), [hashed]) != (document_etag(order_etag(["a"]), app_config_etag({}), []))+ def test_revision_matches_the_document_built_from_the_same_sources(+ self,+ ) -> None:+ cells = [*fixture_cells(), CellSource("crlf", "x = 1\r\ny = 2")]+ app_config = {"width": "full"}+ document = Document(NOTEBOOK, cells, app_config)+ assert revision(cells, app_config) == document._record.etag+def test_normalizes_line_endings_before_hashing(self) -> None:document = Document(NOTEBOOK, [CellSource("a", "x = 1\r\ny = 2")], {})(cell,) = documentdiff --git a/tests/_core/test_protocol.py b/tests/_core/test_protocol.pyindex d8f4c6fe4d..0df46b035f 100644--- a/tests/_core/test_protocol.py+++ b/tests/_core/test_protocol.py@@ -51,6 +51,10 @@ def stream_events(path: Path) -> list[dict[str, str]]:return events+def identity(body: dict[str, Any]) -> str:+ return body.get("id") or body["notebook_id"]++def messages(name: str, kind: str) -> list[dict[str, Any]]:return [json.loads(event["data"])@@ -241,7 +245,7 @@ def test_catalog_capabilities_and_runtime_stop() -> None:assert obj["project_id"] in state["project"]if kind in {"runtime", "attachment"}:assert obj["notebook_id"] in state["notebook"]- state.setdefault(kind, {})[obj["id"]] = obj+ state.setdefault(kind, {})[identity(obj)] = objassert not state.get("runtime")assert set(state["attachment"]) == {"a1", "a2"}catalogs.append(@@ -274,7 +278,7 @@ def test_notebook_snapshot_matches_live_history() -> None:kind = event["event"]message = json.loads(event["data"])message.pop("time")- state[(kind, message[kind]["id"])] = message+ state[(kind, identity(message[kind]))] = messageseen_cells = set()for event in notebook[:ready]:kind = event["event"]@@ -283,7 +287,7 @@ def test_notebook_snapshot_matches_live_history() -> None:seen_cells.add(message["cell"]["id"])elif kind == "document":assert set(message["document"]["order"]) == seen_cells- key = (kind, message[kind]["id"])+ key = (kind, identity(message[kind]))if key in state:assert state.pop(key) == messageassert not state