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.

Name a document's notebook with `notebook_id` (#11255)

Trevor Manzbf1ced70cb63
diff --git a/marimo/_core/document.py b/marimo/_core/document.py
index 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.py
index 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_id
class Host:
diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.py
index 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.py
index 1c801e5e0d..4b24599b80 100644
--- a/marimo/_server/host/bridge.py
+++ b/marimo/_server/host/bridge.py
@@ -9,7 +9,7 @@ from typing import TYPE_CHECKING, Any
from marimo import _loggers
from marimo._config.manager import ScriptConfigReader
from marimo._core import protocol
-from marimo._core.document import CellSource, Document
+from marimo._core.document import CellSource, Document, revision
from marimo._core.errors import Conflict, NotFound
from marimo._core.executions import Executions
from 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.py
index 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.json
index 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.sse
index 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":"2
id: 113
event: 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: 114
event: 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.sse
index 16ab8c787a..f79536dd5a 100644
--- a/protocols/host/fixtures/notebook-events.sse
+++ b/protocols/host/fixtures/notebook-events.sse
@@ -11,7 +11,7 @@ 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":[]}}}
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: 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 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.yaml
index 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 the
runtime 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 app
config carry their own etags, so an edit to one does not conflict
with 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.py
index 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 Host
from 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,) = document
diff --git a/tests/_core/test_protocol.py b/tests/_core/test_protocol.py
index 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)] = obj
assert 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]))] = message
seen_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) == message
assert not state