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.

Add `version` to documents and cells (#11317)

Trevor Manzf895568c68d5
diff --git a/marimo/_core/document.py b/marimo/_core/document.py
index 7602c5319a..e53271731a 100644
--- a/marimo/_core/document.py
+++ b/marimo/_core/document.py
@@ -124,11 +124,11 @@ class Changed:
@dataclass(frozen=True)
class Applied:
- """An edit's effects and the etags of the cells it touched."""
+ """An edit's effects and the cells it touched."""
changed: Changed
- cells: dict[protocol.CellId, protocol.CellEtags | None]
- """By id, for each cell the edit put, and `None` for each it deleted."""
+ cells: dict[protocol.CellId, DocumentCell | None]
+ """By id, each cell as the edit put it, and `None` for each it deleted."""
@dataclass(frozen=True)
@@ -331,15 +331,10 @@ class Document:
document, changed = self.replace(
[staged[cell_id] for cell_id in order], self._app_config
)
- cells: dict[protocol.CellId, protocol.CellEtags | None] = {}
- for cell_id, put in touched.items():
- if put:
- cell = document._cells[cell_id]
- cells[cell_id] = protocol.CellEtags(
- etag=cell.etag, code_hash=cell.code_hash
- )
- else:
- cells[cell_id] = None
+ cells = {
+ cell_id: document._cells[cell_id] if put else None
+ for cell_id, put in touched.items()
+ }
return document, Applied(changed, cells)
diff --git a/marimo/_core/notebook.py b/marimo/_core/notebook.py
index 59b9cf633b..8d03364da4 100644
--- a/marimo/_core/notebook.py
+++ b/marimo/_core/notebook.py
@@ -62,6 +62,11 @@ class Notebook:
self._id = notebook_id
self._document = document
self._saved_etag = saved_etag
+ # Versions order the records clients read. The document's advances
+ # with each change to its content; a cell's is the document version
+ # at which it was created or last changed.
+ self._version = 1
+ self._cell_versions = {cell.id: 1 for cell in document}
# The document record as last published, so a change that leaves
# it the same publishes nothing.
self._published: protocol.Document | None = self._document_record
@@ -128,6 +133,7 @@ class Notebook:
saved_etag=self._saved_etag,
order_etag=document.order_etag,
app_config_etag=document.app_config_etag,
+ version=self._version,
)
@property
@@ -157,25 +163,23 @@ class Notebook:
"""Replace the document and publish its changes.
With `saved`, the new contents are also the persisted revision.
- The response carries etags for the cells that changed, and
+ The response carries the version of each cell that changed, and
`None` for each cell that was removed.
"""
self._require_open()
self._document, changed = self._document.replace(cells, app_config)
if saved:
self._saved_etag = self._document.etag
- self._publish_changed(changed, request_id)
- etags: dict[str, protocol.CellEtags | None] = {
- cell.id: protocol.CellEtags(
- etag=cell.etag, code_hash=cell.code_hash
+ with self.sink.deferred():
+ self._publish_changed(changed, request_id)
+ versions: dict[str, protocol.CellVersion | None] = {
+ cell.id: self._cell_version(cell) for cell in changed.cells
+ }
+ for cell_id in changed.removed:
+ versions[cell_id] = None
+ return protocol.EditResponse(
+ document=self._document_record, cells=versions
)
- for cell in changed.cells
- }
- for cell_id in changed.removed:
- etags[cell_id] = None
- return protocol.EditResponse(
- document=self._document_record, cells=etags
- )
def edit(
self, changes: Sequence[protocol.Change], *, request_id: str
@@ -202,11 +206,15 @@ class Notebook:
document=self._document_record,
)
self._document, applied = result
- self._publish_changed(applied.changed, request_id)
- return protocol.EditResponse(
- document=self._document_record,
- cells=dict(applied.cells.items()),
- )
+ with self.sink.deferred():
+ self._publish_changed(applied.changed, request_id)
+ return protocol.EditResponse(
+ document=self._document_record,
+ cells={
+ cell_id: None if cell is None else self._cell_version(cell)
+ for cell_id, cell in applied.cells.items()
+ },
+ )
def mark_saved(
self, etag: protocol.Etag, *, request_id: str | None = None
@@ -232,6 +240,14 @@ class Notebook:
config=cell.config,
etag=cell.etag,
code_hash=cell.code_hash,
+ version=self._cell_versions[cell.id],
+ )
+
+ def _cell_version(self, cell: DocumentCell) -> protocol.CellVersion:
+ return protocol.CellVersion(
+ etag=cell.etag,
+ code_hash=cell.code_hash,
+ version=self._cell_versions[cell.id],
)
def _refresh(self) -> protocol.Document | None:
@@ -246,6 +262,12 @@ class Notebook:
self, changed: Changed, request_id: str | None
) -> None:
"""Publish a document change, then analyze the new revision."""
+ if changed:
+ self._version += 1
+ for cell in changed.cells:
+ self._cell_versions[cell.id] = self._version
+ for cell_id in changed.removed:
+ self._cell_versions.pop(cell_id, None)
with self.sink.deferred():
for cell in changed.cells:
self._publish(self._cell_record(cell), request_id)
diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.py
index 91e428a8fb..241239731b 100644
--- a/marimo/_core/protocol.py
+++ b/marimo/_core/protocol.py
@@ -696,11 +696,13 @@ class Cell(Struct, frozen=True):
),
]
notebook_id: NotebookId
-
-
-class CellEtags(Struct, frozen=True):
- code_hash: Etag
- etag: Etag
+ version: Annotated[
+ int,
+ Meta(
+ description="The document version at which the cell was created or last changed.",
+ ge=1,
+ ),
+ ]
class CellMessage(Struct, frozen=True):
@@ -725,6 +727,14 @@ class CellMessage(Struct, frozen=True):
) = UNSET
+class CellVersion(Struct, frozen=True):
+ code_hash: Etag
+ etag: Etag
+ version: Annotated[
+ int, Meta(description="The cell's version after the edit.", ge=1)
+ ]
+
+
Change: TypeAlias = Annotated[
PutCell | DeleteCell | SetOrder,
Meta(description="One change to the document, tagged on `kind`."),
@@ -893,6 +903,13 @@ class Document(Struct, frozen=True):
]
| None
)
+ version: Annotated[
+ int,
+ Meta(
+ description="Counts changes to the cells, the order, or the app config. A save does not advance it. Comparable only within one notebook while it is in the catalog.",
+ ge=1,
+ ),
+ ]
class DocumentMessage(Struct, frozen=True):
@@ -946,9 +963,9 @@ class EditRequest(Struct, frozen=True):
class EditResponse(Struct, frozen=True):
cells: Annotated[
- dict[str, CellEtags | None],
+ dict[str, CellVersion | None],
Meta(
- description="The etags of each cell the request created or changed, by id, and null for each cell it deleted."
+ description="The version of each cell the request created or changed, by id, and null for each cell it deleted."
),
]
document: Document
diff --git a/protocols/host/conformance/contract.py b/protocols/host/conformance/contract.py
index 8a3e5781b8..116482ce7d 100644
--- a/protocols/host/conformance/contract.py
+++ b/protocols/host/conformance/contract.py
@@ -229,4 +229,7 @@ def document_state(
parts = [document["order_etag"], document["app_config_etag"]]
parts.extend(cells[cell_id]["etag"] for cell_id in document["order"])
assert document["etag"] == etag("\n".join(parts))
+ assert document["version"] >= 1
+ for cell in cells.values():
+ assert 1 <= cell["version"] <= document["version"]
return document, cells
diff --git a/protocols/host/fixtures/cell.json b/protocols/host/fixtures/cell.json
index 5c3ad310cf..56afbb07a9 100644
--- a/protocols/host/fixtures/cell.json
+++ b/protocols/host/fixtures/cell.json
@@ -10,5 +10,6 @@
"expand_output": false
},
"etag": "5cf78587dcf22d8d",
- "code_hash": "0f71456db2ea83f4"
+ "code_hash": "0f71456db2ea83f4",
+ "version": 1
}
diff --git a/protocols/host/fixtures/edit-response.json b/protocols/host/fixtures/edit-response.json
index 5a673c88fa..4f9a774ee9 100644
--- a/protocols/host/fixtures/edit-response.json
+++ b/protocols/host/fixtures/edit-response.json
@@ -12,16 +12,19 @@
"etag": "f01a47d5aa0cad55",
"saved_etag": "e59d9c2af02f5814",
"order_etag": "162e15055422ed71",
- "app_config_etag": "283513048dfeb45b"
+ "app_config_etag": "283513048dfeb45b",
+ "version": 2
},
"cells": {
"c2": {
"etag": "ce27bab48d697cfc",
- "code_hash": "c2d0a5e0790d97a0"
+ "code_hash": "c2d0a5e0790d97a0",
+ "version": 2
},
"c3": {
"etag": "dde89bbcc1863211",
- "code_hash": "43e1a529dbae470b"
+ "code_hash": "43e1a529dbae470b",
+ "version": 2
},
"k7f2": null
}
diff --git a/protocols/host/fixtures/edits.sse b/protocols/host/fixtures/edits.sse
index d0243adde4..18d6294c33 100644
--- a/protocols/host/fixtures/edits.sse
+++ b/protocols/host/fixtures/edits.sse
@@ -1,10 +1,10 @@
id: 110
event: cell
-data: {"cell":{"id":"c2","notebook_id":"n1","code":"print('hi')","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"ce27bab48d697cfc","code_hash":"c2d0a5e0790d97a0"},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}
+data: {"cell":{"id":"c2","notebook_id":"n1","code":"print('hi')","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"ce27bab48d697cfc","code_hash":"c2d0a5e0790d97a0","version":2},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}
id: 111
event: cell
-data: {"cell":{"id":"c3","notebook_id":"n1","code":"x = 22","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"dde89bbcc1863211","code_hash":"43e1a529dbae470b"},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}
+data: {"cell":{"id":"c3","notebook_id":"n1","code":"x = 22","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"dde89bbcc1863211","code_hash":"43e1a529dbae470b","version":2},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}
id: 112
event: cell.removed
@@ -12,9 +12,9 @@ data: {"id":"k7f2","request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2
id: 113
event: document
-data: {"document":{"notebook_id":"n1","order":["c1","c2","c3"],"app_config":{"width":"full"},"etag":"f01a47d5aa0cad55","saved_etag":"e59d9c2af02f5814","order_etag":"162e15055422ed71","app_config_etag":"283513048dfeb45b"},"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"},"etag":"f01a47d5aa0cad55","saved_etag":"e59d9c2af02f5814","order_etag":"162e15055422ed71","app_config_etag":"283513048dfeb45b","version":2},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}
id: 114
event: document
-data: {"document":{"notebook_id":"n1","order":["c1","c2","c3"],"app_config":{"width":"full"},"etag":"f01a47d5aa0cad55","saved_etag":"f01a47d5aa0cad55","order_etag":"162e15055422ed71","app_config_etag":"283513048dfeb45b"},"request_id":"save-9b1c6d2e","time":"2026-10-01T09:21:02Z"}
+data: {"document":{"notebook_id":"n1","order":["c1","c2","c3"],"app_config":{"width":"full"},"etag":"f01a47d5aa0cad55","saved_etag":"f01a47d5aa0cad55","order_etag":"162e15055422ed71","app_config_etag":"283513048dfeb45b","version":2},"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 c1144e6382..f0c36621f1 100644
--- a/protocols/host/fixtures/notebook-events.sse
+++ b/protocols/host/fixtures/notebook-events.sse
@@ -2,16 +2,16 @@ event: notebook
data: {"notebook":{"id":"n1","project_id":"p1","path":"forecasts.py","name":"forecasts","operations":["notebook.update","notebook.delete","notebook.open","notebook.edit","notebook.save","runtime.start","runtime.stop","runtime.run","runtime.interrupt"],"updated_at":"2026-10-01T09:00:00Z"}}
event: cell
-data: {"cell":{"id":"c1","notebook_id":"n1","code":"import marimo as mo","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"48d6363150d6281c","code_hash":"f649a0b56c5c1966"}}
+data: {"cell":{"id":"c1","notebook_id":"n1","code":"import marimo as mo","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"48d6363150d6281c","code_hash":"f649a0b56c5c1966","version":1}}
event: cell
-data: {"cell":{"id":"c3","notebook_id":"n1","code":"x = 21","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"5cf78587dcf22d8d","code_hash":"0f71456db2ea83f4"}}
+data: {"cell":{"id":"c3","notebook_id":"n1","code":"x = 21","name":"_","config":{"column":null,"disabled":false,"hide_code":false,"expand_output":false},"etag":"5cf78587dcf22d8d","code_hash":"0f71456db2ea83f4","version":1}}
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"}}
+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","version":1}}
event: document
-data: {"document":{"notebook_id":"n1","order":["c1","c3","k7f2"],"app_config":{"width":"full"},"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"},"etag":"e59d9c2af02f5814","saved_etag":"e59d9c2af02f5814","order_etag":"b9c412c2d7d63161","app_config_etag":"283513048dfeb45b","version":1}}
event: analysis
data: {"analysis":{"notebook_id":"n1","document_etag":"e59d9c2af02f5814","cells":{"c1":{"defs":["mo"],"refs":[],"errors":[]},"c3":{"defs":["x"],"refs":[],"errors":[]},"k7f2":{"defs":["y"],"refs":["x"],"errors":[]}}}}
diff --git a/protocols/host/fixtures/problems/edit-conflict.json b/protocols/host/fixtures/problems/edit-conflict.json
index 885a9592bb..c54fced91a 100644
--- a/protocols/host/fixtures/problems/edit-conflict.json
+++ b/protocols/host/fixtures/problems/edit-conflict.json
@@ -17,7 +17,8 @@
"expand_output": false
},
"etag": "dde89bbcc1863211",
- "code_hash": "43e1a529dbae470b"
+ "code_hash": "43e1a529dbae470b",
+ "version": 2
},
"document": {
"notebook_id": "n1",
@@ -32,7 +33,8 @@
"etag": "f01a47d5aa0cad55",
"saved_etag": "e59d9c2af02f5814",
"order_etag": "162e15055422ed71",
- "app_config_etag": "283513048dfeb45b"
+ "app_config_etag": "283513048dfeb45b",
+ "version": 2
}
}
}
diff --git a/protocols/host/openapi.yaml b/protocols/host/openapi.yaml
index cf0ae004c9..78308df834 100644
--- a/protocols/host/openapi.yaml
+++ b/protocols/host/openapi.yaml
@@ -1364,7 +1364,7 @@ components:
fires when its code, name, or config changes. Markdown and SQL
cells are code that calls `mo.md` or `mo.sql`; a client chooses
the editor to show.
- required: [id, notebook_id, code, name, config, etag, code_hash]
+ required: [id, notebook_id, code, name, config, etag, code_hash, version]
properties:
id: { $ref: '#/components/schemas/CellId' }
notebook_id: { $ref: '#/components/schemas/NotebookId' }
@@ -1381,6 +1381,10 @@ components:
code_hash:
$ref: '#/components/schemas/Etag'
description: Identifies the code alone. Its text is `code`. Unchanged by renaming the cell or editing its config. Compare with an execution's `code_hash` to tell whether a result came from the current code.
+ version:
+ type: integer
+ minimum: 1
+ description: The document version at which the cell was created or last changed.
Document:
type: object
description: |
@@ -1389,7 +1393,7 @@ components:
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: [notebook_id, order, app_config, etag, saved_etag, order_etag, app_config_etag]
+ required: [notebook_id, order, app_config, etag, saved_etag, order_etag, app_config_etag, version]
properties:
notebook_id:
$ref: '#/components/schemas/NotebookId'
@@ -1414,6 +1418,10 @@ components:
app_config_etag:
$ref: '#/components/schemas/Etag'
description: Identifies the app config alone. Its text is the app config as canonical JSON, with keys sorted by code point, no whitespace, and strings carrying only the escapes JSON requires.
+ version:
+ type: integer
+ minimum: 1
+ description: Counts changes to the cells, the order, or the app config. A save does not advance it. Comparable only within one notebook while it is in the catalog.
HostMessage:
type: object
description: The data of a `host` event. The host object, plus which request caused the event and when.
@@ -1766,13 +1774,17 @@ components:
type: array
items: { $ref: '#/components/schemas/Change' }
description: The changes, applied in order as one unit.
- CellEtags:
+ CellVersion:
type: object
- description: The identifiers of a cell after an edit.
- required: [etag, code_hash]
+ description: A cell's etags and version after an edit.
+ required: [etag, code_hash, version]
properties:
etag: { $ref: '#/components/schemas/Etag' }
code_hash: { $ref: '#/components/schemas/Etag' }
+ version:
+ type: integer
+ minimum: 1
+ description: The cell's version after the edit.
EditResponse:
type: object
description: The document after an edit or a save, and the cells it touched.
@@ -1782,8 +1794,8 @@ components:
cells:
type: object
additionalProperties:
- oneOf: [{ $ref: '#/components/schemas/CellEtags' }, { type: 'null' }]
- description: The etags of each cell the request created or changed, by id, and null for each cell it deleted.
+ oneOf: [{ $ref: '#/components/schemas/CellVersion' }, { type: 'null' }]
+ description: The version of each cell the request created or changed, by id, and null for each cell it deleted.
EditConflict:
type: object
description: The first stale change of an edit or run, and the state the host holds.
diff --git a/protocols/host/spec.md b/protocols/host/spec.md
index e71d94c883..95ece448a1 100644
--- a/protocols/host/spec.md
+++ b/protocols/host/spec.md
@@ -76,14 +76,19 @@ across renames and moves.
### Documents and cells
The **document** is the notebook's editable source, organized into **cells**.
-Each cell holds code and the information used to present and execute it. A host
-MAY also publish an **analysis** of the document: each cell's definitions,
-references, and problems, so clients can understand a cell's role in the
-computation and identify problems before execution.
-
-Because cells share a dependency graph, editing one can affect the analysis of
-others. An analysis therefore covers the whole document and names the revision
-it describes. Hosts publish it after that revision of the document.
+Each cell holds code and the information used to present and execute it. The
+document and each cell carry an **etag**, derived from their content, and a
+**version**. The document's version counts its changes. A cell's version is
+the document version at which the cell was created or last changed, so of two
+records of a cell, the higher version is the newer. Versions are comparable
+only within one notebook.
+
+A host MAY also publish an **analysis** of the document: each cell's
+definitions, references, and problems, so clients can understand a cell's role
+in the computation and identify problems before execution. Because cells share
+a dependency graph, editing one can affect the analysis of others. An analysis
+therefore covers the whole document and names the revision it describes. Hosts
+publish it after that revision of the document.
### Runtimes and attachments
@@ -314,6 +319,9 @@ Preconditions use **etags**, identifiers derived from content. They let clients
edit different parts of a document independently while detecting competing
changes to the same part. For example, two clients can update different cells,
but an edit based on an older version of the same cell produces a conflict.
+An accepted edit answers with the document and the version of each cell it
+touched. The client already has the content it sent, and the versions let it
+recognize the edit when its events arrive on the stream.
Accepting an edit and saving it are separate actions. The host reports whether
the current document has reached storage, whether it saves automatically or
diff --git a/tests/_core/test_notebook.py b/tests/_core/test_notebook.py
index fd1f158e39..8fdf53f026 100644
--- a/tests/_core/test_notebook.py
+++ b/tests/_core/test_notebook.py
@@ -1200,9 +1200,13 @@ async def test_current_cell_results_can_seed_another_notebook() -> None:
saved_etag=notebook.saved_etag,
)
source_record, source_cells = published(notebook)
+ # A new notebook starts its own version history.
assert published(restored) == (
- replace(source_record, notebook_id=restored.id),
- [replace(cell, notebook_id=restored.id) for cell in source_cells],
+ replace(source_record, notebook_id=restored.id, version=1),
+ [
+ replace(cell, notebook_id=restored.id, version=1)
+ for cell in source_cells
+ ],
)
assert list(restored.document) == list(notebook.document)
assert restored.executions.current(CellId("c1")) == retained
diff --git a/tests/_core/test_notebook_document.py b/tests/_core/test_notebook_document.py
index 7ab2d5caee..5ce83dc880 100644
--- a/tests/_core/test_notebook_document.py
+++ b/tests/_core/test_notebook_document.py
@@ -280,9 +280,7 @@ class TestApply:
assert applied.cells["k7f2"] is None
new_c3 = document.cell("c3")
assert new_c3 is not None
- assert applied.cells["c3"] == protocol.CellEtags(
- etag=new_c3.etag, code_hash=new_c3.code_hash
- )
+ assert applied.cells["c3"] == new_c3
assert new_c3.etag != c3.etag
def test_a_stale_etag_applies_nothing_and_names_the_change(self) -> None:
@@ -356,9 +354,7 @@ class TestApply:
document, applied = result
assert document == before
assert not applied.changed
- assert applied.cells["c3"] == protocol.CellEtags(
- etag=c3.etag, code_hash=c3.code_hash
- )
+ assert applied.cells["c3"] == c3
class TestFromRecords:
@@ -443,6 +439,44 @@ class TestNotebookRecords:
behind = other.mark_saved(saved.etag)
assert behind.saved_etag == saved.etag != behind.etag
+ def test_versions_order_changes_and_stamp_the_cells_they_touch(
+ self,
+ ) -> None:
+ notebook = hosted(Document(fixture_cells(), {}))
+ record, cells = records(notebook)
+ assert record.version == 1
+ assert [c.version for c in cells] == [1, 1, 1]
+ (_, c3, k7f2) = cells
+
+ response = notebook.edit(
+ [put("c3", "x = 22", c3.etag), delete("k7f2", k7f2.etag)],
+ request_id="e",
+ )
+
+ # Changed cells take the new document version; others keep theirs.
+ assert response.document.version == 2
+ assert response.cells["k7f2"] is None
+ assert response.cells["c3"].version == 2 # type: ignore[union-attr]
+ record, cells = records(notebook)
+ assert record.version == 2
+ assert [(c.id, c.version) for c in cells] == [("c1", 1), ("c3", 2)]
+
+ # Saving moves `saved_etag` only; a no-op edit changes nothing.
+ assert notebook.mark_saved(record.etag).version == 2
+ same = notebook.edit(
+ [put("c1", "import marimo as mo", cells[0].etag)], request_id="n"
+ )
+ assert same.document.version == 2
+ assert same.cells["c1"] == protocol.CellVersion(
+ etag=cells[0].etag, code_hash=cells[0].code_hash, version=1
+ )
+
+ # A reload changes content like any edit.
+ notebook.replace([cell("c1", "1")], {})
+ record, cells = records(notebook)
+ assert record.version == 3
+ assert [(c.id, c.version) for c in cells] == [("c1", 3)]
+
def test_a_stale_edit_names_the_cell_and_document_as_they_are(
self,
) -> None:
@@ -463,6 +497,53 @@ class TestNotebookRecords:
class TestNotebook:
+ @pytest.mark.parametrize("method", ["edit", "replace"])
+ @pytest.mark.parametrize("remove", [False, True])
+ def test_response_preserves_revision_before_subscriber_changes(
+ self,
+ host: Host,
+ notebook: Notebook,
+ log: list[Event],
+ method: str,
+ remove: bool,
+ ) -> None:
+ notebook.replace([cell("c1", "0")], {})
+ log.clear()
+
+ def change_again(event: Event) -> None:
+ if (
+ isinstance(event.data, protocol.CellMessage)
+ and event.data.request_id == "first"
+ ):
+ change = delete("c1", "*") if remove else put("c1", "2", "*")
+ notebook.edit([change], request_id="second")
+
+ host.subscribe(change_again, notebook_id=notebook.id)
+ if method == "edit":
+ response = notebook.edit([put("c1", "1", "*")], request_id="first")
+ else:
+ response = notebook.replace(
+ [cell("c1", "1")], {}, request_id="first"
+ )
+
+ first_cell, first_document = log[:2]
+ assert isinstance(first_cell.data, protocol.CellMessage)
+ assert isinstance(first_document.data, protocol.DocumentMessage)
+ published = first_cell.data.cell
+ assert response == protocol.EditResponse(
+ document=first_document.data.document,
+ cells={
+ "c1": protocol.CellVersion(
+ etag=published.etag,
+ code_hash=published.code_hash,
+ version=published.version,
+ )
+ },
+ )
+ assert notebook.document.cell("c1") == (
+ None if remove else cell("c1", "2")
+ )
+
async def test_initialization_publishes_cells_then_the_document(
self, host: Host, log: list[Event]
) -> None:
diff --git a/tests/_core/test_protocol.py b/tests/_core/test_protocol.py
index b22cbab539..cf61299e7f 100644
--- a/tests/_core/test_protocol.py
+++ b/tests/_core/test_protocol.py
@@ -491,7 +491,7 @@ def test_edit_request_response_and_events() -> None:
assert all(updated[key] == value for key, value in cell.items())
cells[cell["id"]] = updated
touched[cell["id"]] = {
- key: updated[key] for key in ("etag", "code_hash")
+ key: updated[key] for key in ("etag", "code_hash", "version")
}
else:
assert change["kind"] == "delete_cell"