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
Save notebook documents through the host (#11265)
Trevor Manz00b7cb58acd2
diff --git a/marimo/_core/errors.py b/marimo/_core/errors.pyindex 1c406d8062..a86a04bbb9 100644--- a/marimo/_core/errors.py+++ b/marimo/_core/errors.py@@ -48,3 +48,17 @@ class EditConflict(Conflict):self.change = changeself.cell = cellself.document = document+++class DecisionRequired(Conflict):+ """The command needs a choice from the client before it can proceed.++ Carries the decisions to put to the client, which repeats the+ request with its answers.+ """++ def __init__(+ self, message: str, *, decisions: tuple[protocol.Decision, ...]+ ) -> None:+ super().__init__(message)+ self.decisions = decisionsdiff --git a/marimo/_core/notebook.py b/marimo/_core/notebook.pyindex 372c0ba2e1..8d40b85479 100644--- a/marimo/_core/notebook.py+++ b/marimo/_core/notebook.py@@ -135,12 +135,19 @@ class Notebook:document=self.document._record, cells=applied.cells)- def mark_saved(self, *, request_id: str | None = None) -> None:- """Mark the current document revision as saved."""+ def mark_saved(+ self, etag: protocol.Etag, *, request_id: str | None = None+ ) -> protocol.Document:+ """Record `etag` as the persisted revision and return the document.++ The revision may precede the current one, when the document+ changed while it was being written.+ """self._require_open()- document = self.document.mark_saved()- if document is not None:- self._publish(document, request_id)+ published = self.document.mark_saved(etag)+ if published is not None:+ self._publish(published, request_id)+ return self.document._recorddef _publish_changed(self, changed: Changed, request_id: str | Nonediff --git a/marimo/_server/host/__init__.py b/marimo/_server/host/__init__.pyindex 4ef4e55e46..54df84d09b 100644--- a/marimo/_server/host/__init__.py+++ b/marimo/_server/host/__init__.py@@ -10,6 +10,7 @@ OPERATIONS = ["notebook.delete","notebook.open","notebook.edit",+ "notebook.save","runtime.start","runtime.stop","runtime.restart",diff --git a/marimo/_server/host/api.py b/marimo/_server/host/api.pyindex 083d8f587b..dd74271b1a 100644--- a/marimo/_server/host/api.py+++ b/marimo/_server/host/api.py@@ -21,6 +21,7 @@ from marimo import _loggersfrom marimo._core import protocolfrom marimo._core.errors import (Conflict,+ DecisionRequired,EditConflict,Invalid,NoRuntime,@@ -75,6 +76,7 @@ _TITLES = {"method-not-allowed": "Method not allowed","conflict": "Conflict","no-runtime": "No runtime",+ "decision-required": "Decision required","unsupported-operation": "Unsupported operation","internal": "Internal error",}@@ -94,12 +96,14 @@ def problem(detail: str | None = None,*,edit: protocol.EditConflict | None = None,+ decisions: tuple[protocol.Decision, ...] | None = None,) -> Response:"""Return a protocol error as an HTTP problem response.Without a kind, the status picks one. A status this protocol doesnot name is a server bug, so it becomes a 500 rather than a problem- of an unknown kind. A conflict over an edit carries `edit`.+ of an unknown kind. A conflict over an edit carries `edit`, and a+ request that needs a choice first carries `decisions`."""kind = _HTTP_KINDS.get(status) if kind is None else kind@@ -112,6 +116,7 @@ def problem(status=status,detail=msgspec.UNSET if detail is None else detail,edit=msgspec.UNSET if edit is None else edit,+ decisions=msgspec.UNSET if decisions is None else decisions,)return Response(msgspec.json.encode(body),@@ -129,6 +134,7 @@ def build_app() -> Router:Route("/notebooks/{id}", _delete_notebook, methods=["DELETE"]),Route("/notebooks/{id}/events", _notebook_events, methods=["GET"]),Route("/notebooks/{id}/edits", _edit_notebook, methods=["POST"]),+ Route("/notebooks/{id}/save", _save_notebook, methods=["POST"]),Route("/notebooks/{id}/open", _open_notebook, methods=["POST"]),Route("/notebooks/{id}/runtime", _start_runtime, methods=["PUT"]),Route("/notebooks/{id}/runtime", _stop_runtime, methods=["DELETE"]),@@ -201,7 +207,12 @@ def _mutation(operation: str) -> Callable[[_Endpoint], _Endpoint]:400, "invalid-request", "Idempotency-Key is required")digest = hashlib.sha256(await request.body()).hexdigest()- fingerprint = f"{request.method} {request.url.path} {digest}"+ # A precondition is part of the request, so a retry that+ # names another revision is another request.+ if_match = request.headers.get("If-Match", "")+ fingerprint = (+ f"{request.method} {request.url.path} {digest} {if_match}"+ )remembered = context.remembered(key)if remembered is not None:if remembered.fingerprint != fingerprint:@@ -352,6 +363,8 @@ async def _execute_mutation(endpoint: _Endpoint, request: Request) -> Response:return await endpoint(request)except NoRuntime as e:return problem(409, "no-runtime", str(e))+ except DecisionRequired as e:+ return problem(409, "decision-required", str(e), decisions=e.decisions)except EditConflict as e:return problem(409,@@ -618,6 +631,39 @@ async def _edit_notebook(request: Request) -> Response:return _reply(200, response)+@_mutation("notebook.save")+async def _save_notebook(request: Request) -> Response:+ """Write the document to its file; 409 with `edit` when `If-Match` is stale."""+ context = _context(request)+ key = request.headers["Idempotency-Key"]+ notebook = await _notebook(request)+ body = await _decode(request, protocol.SaveRequest)+ response = await context.bridge.save(+ notebook.id,+ if_match=_if_match(request.headers.get("If-Match")),+ decisions={} if body.decisions is msgspec.UNSET else body.decisions,+ request_id=key,+ )+ return _reply(200, response)+++def _if_match(header: str | None) -> tuple[str, ...] | None:+ """The etags an `If-Match` header accepts, or `None` when it accepts any.++ The header is `*` or a comma-separated list of entity tags, each+ optionally quoted. `If-Match` compares strongly (RFC 9110, 13.1.1),+ so a tag marked weak with `W/` never matches and is left out.+ """+ if header is None or header.strip() == "*":+ return None+ tags = []+ for part in header.split(","):+ tag = part.strip()+ if tag and not tag.startswith("W/"):+ tags.append(tag.strip('"'))+ return tuple(tags)++@_mutation("notebook.open")async def _open_notebook(request: Request) -> Response:"""Open the notebook in the configured browser."""diff --git a/marimo/_server/host/backend.py b/marimo/_server/host/backend.pyindex b167250954..0169389c59 100644--- a/marimo/_server/host/backend.py+++ b/marimo/_server/host/backend.py@@ -79,6 +79,7 @@ class SessionBackend(SessionConsumer):observe: Observe,document_changed: Callable[[], None] | None = None,session_attached: Callable[[], None] | None = None,+ session_detached: Callable[[Session], None] | None = None,) -> None:self._notebook_id = notebook_idself._file = file@@ -89,6 +90,8 @@ class SessionBackend(SessionConsumer):"""Called after the session's document changes, from any writer."""self._session_attached = session_attached"""Called with the session attached, before the runtime is reported."""+ self._session_detached = session_detached+ """Called with the session that detached, before its exit is reported."""self._kernel: _Kernel | None = Noneself._run: _Run | None = Noneself._translators: dict[str, RunTranslator] = {}@@ -275,6 +278,8 @@ class SessionBackend(SessionConsumer):if kernel is None or kernel.session is None:returnsession = kernel.session+ if self._session_detached is not None:+ self._session_detached(session)reason = Noneif session.kernel_state() is KernelState.STOPPED:info = session.kernel_exit_info()diff --git a/marimo/_server/host/bridge.py b/marimo/_server/host/bridge.pyindex 57fe3c67d1..324002e6d5 100644--- a/marimo/_server/host/bridge.py+++ b/marimo/_server/host/bridge.py@@ -4,13 +4,21 @@from __future__ import annotationsimport asyncio+import copy+from dataclasses import dataclassfrom typing import TYPE_CHECKING, Anyfrom marimo import _loggersfrom marimo._config.manager import ScriptConfigReaderfrom marimo._core import protocolfrom marimo._core.document import CellSource, Document, revision-from marimo._core.errors import Conflict, NotFound+from marimo._core.errors import (+ Conflict,+ DecisionRequired,+ EditConflict,+ Invalid,+ NotFound,+)from marimo._core.executions import Executionsfrom marimo._core.host import Hostfrom marimo._core.notebook import Notebook@@ -21,24 +29,78 @@ from marimo._server.host.backend import SessionBackendfrom marimo._server.host.index import WorkspaceIndexfrom marimo._session.events import SessionEventListenerfrom marimo._session.notebook.storage import rename_no_replace+from marimo._utils.generated_with import (+ contents_differ_excluding_generated_with,+)if TYPE_CHECKING:- from collections.abc import Sequence+ from collections.abc import Mapping, Sequencefrom pathlib import Pathfrom marimo._config.manager import MarimoConfigManagerfrom marimo._core.backend import Message- from marimo._core.document import Policy+ from marimo._core.document import Changed, Policyfrom marimo._core.stream import Event, Sink+ from marimo._messaging.notebook import NotebookCellfrom marimo._server.session_manager import SessionManager+ from marimo._session.notebook import AppFileManagerfrom marimo._session.session import SessionLOGGER = _loggers.marimo_logger()+_FILE_CHANGED = protocol.Decision(+ id="file",+ prompt="The notebook file changed outside marimo. Overwrite it with the document, or reload the document from it?",+ options=(+ protocol.DecisionOption(id="overwrite", label="Overwrite the file"),+ protocol.DecisionOption(id="reload", label="Reload from the file"),+ ),+)+++@dataclass(frozen=True)+class _FileContents:+ """A notebook file as read: its text and the document it parses to."""++ text: str+ cells: list[CellSource]+ app_config: dict[str, Any]+++def _read_text(file: Path) -> str:+ return file.read_text(encoding="utf-8")+++def _texts_differ(text: str, baseline: str) -> bool:+ """Whether two notebook texts differ, as the editor's watcher judges it."""+ if text.strip() == baseline.strip():+ return False+ return contents_differ_excluding_generated_with(text, baseline)+++def _etags(+ changed: Changed, document: protocol.Document+) -> protocol.EditResponse:+ """An edit response for a replacement, with etags for what changed."""+ cells: dict[str, protocol.CellEtags | None] = {+ cell.id: protocol.CellEtags(etag=cell.etag, code_hash=cell.code_hash)+ for cell in changed.cells+ }+ for cell_id in changed.removed:+ cells[cell_id] = None+ return protocol.EditResponse(document=document, cells=cells)+++def _running_loop() -> asyncio.AbstractEventLoop | None:+ try:+ return asyncio.get_running_loop()+ except RuntimeError:+ return None+# NB: The host keeps a separate document to avoid migrating the frontend yet.# Editor changes are mirrored into it; host edits become session transactions.-# Remove this adapter when MO-8002 unifies document ownership after host saving.+# TODO(MO-7927): Remove this adapter when Session consumes the host Notebook.class SessionBridge(SessionEventListener):"""Connect a host's notebook catalog to a session manager."""@@ -50,6 +112,12 @@ class SessionBridge(SessionEventListener):self._manager = managerself._config_manager = config_managerself._files_lock = asyncio.Lock()+ self._saving: set[protocol.NotebookId] = set()+ # TODO(MO-8005): The writer owns this baseline once there is one+ # per notebook file; the host keeps it only while it owns the file.+ self._file_texts: dict[protocol.NotebookId, str] = {}+ """Each file's text as the host last read or wrote it, without a session."""+ self._rebaselining: dict[protocol.NotebookId, asyncio.Task[None]] = {}self._adopting: dict[protocol.NotebookId, Session] = {}self.host = Host(operations=OPERATIONS)self._backends: dict[protocol.NotebookId, SessionBackend] = {}@@ -100,7 +168,8 @@ class SessionBridge(SessionEventListener):else:if loaded is None:raise Conflict("The notebook document could not be loaded")- cells, app_config = loaded+ cells, app_config = loaded.cells, loaded.app_config+ self._file_texts[record.id] = loaded.textdocument = Document(record.id,cells,@@ -109,7 +178,7 @@ class SessionBridge(SessionEventListener):saved=session is None,)if session is not None and loaded is not None:- document.mark_saved(revision(*loaded))+ document.mark_saved(revision(loaded.cells, loaded.app_config))backend = self._make_backend(record.id)return Notebook(document,@@ -119,17 +188,24 @@ class SessionBridge(SessionEventListener):analyzer=HostAnalyzer(),)- async def _load(- self, file: Path- ) -> tuple[list[CellSource], dict[str, Any]] | None:+ async def _load(self, file: Path) -> _FileContents | None:"""Read a notebook file, or return `None` if it cannot be loaded."""try:- return await asyncio.to_thread(self._read, str(file))+ return await asyncio.to_thread(self._read, file)except Exception as e:LOGGER.warning("Could not load %s: %s", file, e)return None- def _read(self, path: str) -> tuple[list[CellSource], dict[str, Any]]:+ def _read(self, file: Path) -> _FileContents:+ # The text is read first, so that a change landing between the+ # two reads makes the next save ask rather than overwrite.+ text = _read_text(file)+ cells, app_config = documents.from_file_manager(+ self._file_manager(str(file))+ )+ return _FileContents(text, cells, app_config)++ def _file_manager(self, path: str) -> AppFileManager:from marimo._server.app_defaults import AppDefaultsfrom marimo._session.notebook import AppFileManager@@ -138,9 +214,166 @@ class SessionBridge(SessionEventListener):if self._config_manager is Noneelse AppDefaults.from_config_manager(self._config_manager))- return documents.from_file_manager(- AppFileManager(path, defaults=defaults)+ return AppFileManager(path, defaults=defaults)++ async def save(+ self,+ notebook_id: str,+ *,+ if_match: Sequence[str] | None,+ decisions: Mapping[str, str] | None = None,+ request_id: str,+ ) -> protocol.EditResponse:+ """Write the document to its file and record the revision written.++ With a session attached, the session's own file manager writes+ the session's cells, which the document mirrors. Its record of+ the last write then stays true, so its watcher does not take the+ host's write for someone else's and its next write is not+ skipped as unchanged. Without a session, a file manager of the+ host's own writes the document's cells. Either way the file+ keeps its header and app config, and the saved revision is+ computed from the cells and config that were written rather+ than taken from the document, which may have moved on.++ Without a session, the host owns the file and keeps its text as+ last read or written. A file whose text differs from that is+ not overwritten until the client decides to, or asks to reload+ the document from it instead. With a session, the editor owns+ the file and watches it itself.++ Raises:+ Conflict: If the notebook has no file or the write fails.+ EditConflict: If `if_match` does not name the document's etag,+ or the document changed while the file was being read+ for a reload.+ DecisionRequired: If the file changed and `decisions` has no+ answer for it.+ Invalid: If `decisions` has an answer this host does not offer.+ """+ notebook = await self.host.notebook(notebook_id)+ async with self._files_lock:+ if self.host.peek_notebook(notebook_id) is not notebook:+ raise NotFound(f"no notebook {notebook_id}")+ file = self.index.file_of(notebook.id)+ if file is None:+ raise Conflict("The notebook has no file to save to")+ # Check and snapshot only after waiting for the file lock.+ snapshot = notebook.document.snapshot()+ if if_match is not None and snapshot.document.etag not in if_match:+ raise EditConflict(+ "The document has changed since it was read",+ change=0,+ cell=None,+ document=snapshot.document,+ )+ session = self._session_of(notebook.id)+ if session is None and await self._file_changed(notebook.id, file):+ answer = (decisions or {}).get(_FILE_CHANGED.id)+ if answer is None:+ raise DecisionRequired(+ "The file changed outside marimo",+ decisions=(_FILE_CHANGED,),+ )+ if answer == "reload":+ return await self._reload(+ notebook, file, snapshot.document, request_id+ )+ if answer != "overwrite":+ raise Invalid(+ f"{answer!r} is not an option for {_FILE_CHANGED.id}"+ )+ # TODO(MO-8005): Move persistence to the notebook, with sessions+ # consuming its events. Until then, save_from_cells on an attached+ # session can replace a concurrent edit with this older snapshot.+ # The notebook's writer must persist snapshots without mutating+ # the live document; cover attached-session edits during a save.+ if session is None:+ cells = [documents.to_notebook_cell(c) for c in snapshot.cells]+ manager = None+ else:+ cells = copy.deepcopy(session.document.cells)+ manager = session.app_file_manager+ self._saving.add(notebook.id)+ try:+ etag, text = await asyncio.to_thread(+ self._write, str(file), cells, manager+ )+ except Exception as e:+ raise Conflict(f"The notebook cannot be saved: {e}") from e+ finally:+ self._saving.discard(notebook.id)+ if session is None:+ self._file_texts[notebook.id] = text+ document = notebook.mark_saved(etag, request_id=request_id)+ return protocol.EditResponse(document=document, cells={})++ def _write(+ self,+ path: str,+ cells: Sequence[NotebookCell],+ manager: AppFileManager | None,+ ) -> tuple[protocol.Etag, str]:+ """Write `cells` to the file; return the revision and text written.++ The revision covers the cells as passed and the app config the+ manager wrote, not the manager's live cells, which another+ thread may change while the file is written.+ """+ if manager is None:+ manager = self._file_manager(path)+ text = manager.save_from_cells(cells)+ etag = revision(+ documents.sources(cells), manager.app.config.asdict_difference()+ )+ return etag, text++ async def _file_changed(+ self, notebook_id: protocol.NotebookId, file: Path+ ) -> bool:+ """Whether the file's text differs from what the host last read or wrote.++ Without a baseline, require a decision. A failed read cannot+ establish that overwriting the file is safe, so refuse the save.+ """+ pending = self._rebaselining.get(notebook_id)+ if pending is not None:+ await pending+ self._rebaselining.pop(notebook_id, None)+ baseline = self._file_texts.get(notebook_id)+ if baseline is None:+ return True+ try:+ text = await asyncio.to_thread(_read_text, file)+ except (OSError, UnicodeError) as e:+ raise Conflict("The notebook file could not be read") from e+ return _texts_differ(text, baseline)++ async def _reload(+ self,+ notebook: Notebook,+ file: Path,+ before: protocol.Document,+ request_id: str,+ ) -> protocol.EditResponse:+ """Replace the document with the file's contents as the saved revision."""+ loaded = await self._load(file)+ if loaded is None:+ raise Conflict("The notebook file could not be loaded")+ # An edit may have landed while the file was read. Replacing the+ # document now would lose it.+ if notebook.document._record.etag != before.etag:+ raise EditConflict(+ "The document changed while the file was being read",+ change=0,+ cell=None,+ document=notebook.document._record,+ )+ self._file_texts[notebook.id] = loaded.text+ changed = notebook.replace(+ loaded.cells, loaded.app_config, saved=True, request_id=request_id)+ return _etags(changed, notebook.document._record)async def edit(self,@@ -185,6 +418,10 @@ class SessionBridge(SessionEventListener):notebook = self.host.peek_notebook(notebook_id)if session is None or notebook is None:return+ # The editor owns the file now; a baseline being read for the+ # host is no longer wanted.+ self._rebaselining.pop(notebook_id, None)+ self._follow_saves(notebook_id, session)document = notebook.documentif document._record.saved_etag != document._record.etag:documents.apply_to_session(session, document)@@ -192,6 +429,84 @@ class SessionBridge(SessionEventListener):cells, app_config = documents.from_session(session)notebook.replace(cells, app_config, saved=True)+ # TODO(MO-7927): Following the editor's writes ends when the notebook+ # owns persistence and the editor saves through it.+ def _follow_saves(+ self, notebook_id: protocol.NotebookId, session: Session+ ) -> None:+ """Record the editor's writes as the saved revision.++ The file manager reports each write on the writing thread with+ the cells and app config it wrote. The revision is computed+ from those, not from the live document, which may have moved+ on. The editor's save endpoint writes on the event loop and+ autosave on a worker, so the record is made directly in the+ first case and handed to the loop in the second.+ """+ loop = asyncio.get_running_loop()++ def persisted(+ cells: Sequence[NotebookCell], app_config: dict[str, Any]+ ) -> None:+ etag = revision(documents.sources(cells), app_config)+ if _running_loop() is loop:+ self._saved(notebook_id, etag)+ else:+ loop.call_soon_threadsafe(self._saved, notebook_id, etag)++ session.app_file_manager.on_persisted = persisted++ def _detach_document(+ self, notebook_id: protocol.NotebookId, session: Session+ ) -> None:+ """Stop following the editor's writes; the host owns the file again.++ Its baseline for external changes is the file as the editor+ left it, read off the event loop before the next save compares.+ """+ session.app_file_manager.on_persisted = None+ self._rebaselining[notebook_id] = (+ asyncio.get_running_loop().create_task(+ self._rebaseline(notebook_id)+ )+ )++ async def _rebaseline(self, notebook_id: protocol.NotebookId) -> None:+ file = self.index.file_of(notebook_id)+ try:+ text = (+ None+ if file is None+ else await asyncio.to_thread(_read_text, file)+ )+ except OSError:+ text = None+ # A session that attached meanwhile owns the file again and has+ # dropped this task from the pending ones.+ if self._rebaselining.get(notebook_id) is not asyncio.current_task():+ return+ if text is None:+ self._file_texts.pop(notebook_id, None)+ else:+ self._file_texts[notebook_id] = text++ def _saved(+ self, notebook_id: protocol.NotebookId, etag: protocol.Etag+ ) -> None:+ """Record a write the editor made.++ A write the host asked for is recorded by `save`, under its+ request, so it is not recorded here as well.+ """+ if notebook_id in self._saving:+ return+ try:+ notebook = self.host.peek_notebook(notebook_id)+ except NotFound:+ return+ if notebook is not None:+ notebook.mark_saved(etag)+def _mirror(self, notebook_id: protocol.NotebookId) -> None:"""Bring the document up to date with the session's after it changed."""session = self._session_of(notebook_id)@@ -360,6 +675,9 @@ class SessionBridge(SessionEventListener):observe,document_changed=lambda: self._mirror(notebook_id),session_attached=lambda: self._attach_document(notebook_id),+ session_detached=lambda session: self._detach_document(+ notebook_id, session+ ),)self._backends[notebook_id] = backendreturn backend@@ -367,6 +685,8 @@ class SessionBridge(SessionEventListener):def _forget_backend(self, event: Event) -> None:if event.name == "notebook.removed" and event.notebook_id is not None:self._backends.pop(event.notebook_id, None)+ self._file_texts.pop(event.notebook_id, None)+ self._rebaselining.pop(event.notebook_id, None)async def _adopt(self, session: Session) -> None:path = session.app_file_manager.pathdiff --git a/marimo/_server/host/document.py b/marimo/_server/host/document.pyindex 68afdf74c5..ceef792954 100644--- a/marimo/_server/host/document.py+++ b/marimo/_server/host/document.py@@ -27,6 +27,7 @@ from marimo._messaging.notebook import (CreateCell,DeleteCell,DocumentChange,+ NotebookCell,ReorderCells,SetCode,SetConfig,@@ -40,17 +41,26 @@ from marimo._runtime.commands import EditCellsCommandfrom marimo._types.ids import CellId_tif TYPE_CHECKING:+ from collections.abc import Iterable+from marimo._core.document import Documentfrom marimo._session.notebook import AppFileManagerfrom marimo._session.session import Sessiondef from_session(session: Session) -> tuple[list[CellSource], dict[str, Any]]:- cells = [+ return (+ sources(session.document.cells),+ session.app_file_manager.app.config.asdict_difference(),+ )+++def sources(cells: Iterable[NotebookCell]) -> list[CellSource]:+ """The document sources for the editor's cells."""+ return [CellSource(cell.id, cell.code, cell.name, _config(cell.config))- for cell in session.document.cells+ for cell in cells]- return cells, session.app_file_manager.app.config.asdict_difference()def from_file_manager(@@ -81,6 +91,15 @@ def _cell_config(config: protocol.CellConfig) -> CellConfig:)+def to_notebook_cell(cell: protocol.Cell) -> NotebookCell:+ return NotebookCell(+ id=CellId_t(cell.id),+ code=cell.code,+ name=cell.name,+ config=_cell_config(cell.config),+ )++def apply_to_session(session: Session, document: Document) -> None:"""Apply the document's cells and order to the session as one transaction.diff --git a/marimo/_session/notebook/file_manager.py b/marimo/_session/notebook/file_manager.pyindex 633d33a5db..bc44131be1 100644--- a/marimo/_session/notebook/file_manager.py+++ b/marimo/_session/notebook/file_manager.py@@ -19,6 +19,7 @@ from marimo._environments.script_metadata import (from marimo._messaging.notebook.changes import (Transaction,)+from marimo._messaging.notebook.document import NotebookCellfrom marimo._runtime.layout.layout import (LayoutConfig,read_layout_config,@@ -43,7 +44,6 @@ LOGGER = _loggers.marimo_logger()if TYPE_CHECKING:from collections.abc import Callable, Sequence- from marimo._messaging.notebook.document import NotebookCellfrom marimo._server.models.models import (CopyNotebookRequest,SaveNotebookRequest,@@ -85,6 +85,17 @@ class AppFileManager:# Track the last saved content to avoid reloading our own writesself._last_saved_content: str | None = None+ # TODO(MO-7927): The host follows the editor's writes through this+ # hook until the notebook owns persistence and no second writer+ # remains to follow.+ self.on_persisted: (+ Callable[[Sequence[NotebookCell], dict[str, Any]], None] | None+ ) = None+ """Called with the cells and app config a save wrote, on its thread.++ The cells are the snapshot the save was given, not the live+ document, which another thread may have changed meanwhile.+ """# Serializes concurrent writers. Reentrant so public entry points# can wrap the full "mutate app + _save_file" sequence while@@ -482,11 +493,26 @@ class AppFileManager:if request.persist:self._invalidate_autosaves()- return self._save_file(+ contents = self._save_file(filename_path,notebook=self.app.to_ir(),persist=request.persist,)+ if request.persist:+ self._persisted(+ [+ NotebookCell(id=i, code=c, name=n, config=f)+ for i, c, n, f in zip(+ cell_ids, codes, names, configs, strict=True+ )+ ]+ )+ return contents++ def _persisted(self, cells: Sequence[NotebookCell]) -> None:+ callback = self.on_persisted+ if callback is not None:+ callback(cells, self.app.config.asdict_difference())def capture_autosave_target(self) -> tuple[Path | None, int]:with self._save_lock:@@ -531,11 +557,13 @@ class AppFileManager:names=[cell.name for cell in cells],configs=[cell.config for cell in cells],)- return self._save_file(+ contents = self._save_file(self._filename,notebook=self.app.to_ir(),persist=True,)+ self._persisted(cells)+ return contentsdef _invalidate_autosaves(self) -> None:self._autosave_generation += 1diff --git a/tests/_core/test_notebook_document.py b/tests/_core/test_notebook_document.pyindex 5df39de7e8..4766685f28 100644--- a/tests/_core/test_notebook_document.py+++ b/tests/_core/test_notebook_document.py@@ -436,6 +436,25 @@ class TestNotebook:]assert log[-1].data.document == changed.document # type: ignore[union-attr]+ def test_mark_saved_records_the_revision_that_was_written(+ self, notebook: Notebook, log: list[Event]+ ) -> None:+ notebook.replace(fixture_cells(), {})+ written = notebook.document._record.etag+ notebook.replace([CellSource("c1", "x = 22")], {})+ log.clear()++ document = notebook.mark_saved(written, request_id="save-1")++ assert document.saved_etag == written+ assert document.etag != written+ assert names(log) == ["document"]+ assert request_ids(log) == ["save-1"]+ assert log[0].data.document == document # type: ignore[union-attr]+ # Marking the same revision again publishes nothing.+ assert notebook.mark_saved(written) == document+ assert names(log) == ["document"]+def test_edit_publishes_as_one_unit_with_the_request_key(self, notebook: Notebook, log: list[Event]) -> None:diff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.pyindex b35741196b..2b0c238c37 100644--- a/tests/_server/host/test_host_api.py+++ b/tests/_server/host/test_host_api.py@@ -26,6 +26,7 @@ from marimo._server.host.index import WorkspaceIndexfrom marimo._server.main import create_starlette_appfrom marimo._server.models.home import MarimoFilefrom marimo._server.workspace import FixedFilesWorkspace, SingleFileWorkspace+from marimo._session.notebook import AppFileManagerfrom tests._core.conftest import ScriptedBackend, make_notebook, runtime_id_offrom tests._server.host.drive import (PORT,@@ -1663,3 +1664,223 @@ async def test_a_stale_etag_is_a_conflict_that_changes_nothing(assert (first_record(again, "document")["document"]["etag"] == document["etag"])+++async def test_save_writes_the_file_and_reports_the_saved_revision(+ harness: Harness,+) -> None:+ stream, disconnect = await opened(harness)+ document = first_record(stream, "document")["document"]+ first_id = document["order"][0]+ edited = await finished(+ harness.app,+ "POST",+ f"/notebooks/{harness.notebook_id}/edits",+ headers=key("edit-1"),+ body=edit_body(+ {+ "kind": "put_cell",+ "base_etag": None,+ "after": first_id,+ "cell": {"id": "fresh", "code": "z = 3"},+ }+ ),+ )+ assert edited.status == 200, edited.body+ etag = edited.json()["document"]["etag"]+ assert "z = 3" not in (harness.root / "forecasts.py").read_text()++ # A weak validator never matches, even one naming the current etag.+ for header in ('"stale"', "W/stale, other", f'W/"{etag}"'):+ stale = await finished(+ harness.app,+ "POST",+ f"/notebooks/{harness.notebook_id}/save",+ headers={**key(f"save-{header}"), "If-Match": header},+ body=b"{}",+ )+ assert stale.status == 409, stale.body+ assert stale.json()["edit"]["change"] == 0+ assert stale.json()["edit"]["document"]["etag"] == etag++ saved = await finished(+ harness.app,+ "POST",+ f"/notebooks/{harness.notebook_id}/save",+ headers={**key("save-1"), "If-Match": f'W/"other", "{etag}"'},+ body=b"{}",+ )+ assert saved.status == 200, saved.body+ assert saved.json()["document"]["saved_etag"] == etag+ text = (harness.root / "forecasts.py").read_text()+ assert "z = 3" in text+ assert 'width="full"' in text+ await wait_for(+ stream,+ lambda r: any(+ x.get("event") == "document"+ and x["data"]["document"]["saved_etag"] == etag+ and x["data"]["request_id"] == "save-1"+ for x in r.records+ ),+ )++ # A retry under the same key with another precondition is another request.+ again = await finished(+ harness.app,+ "POST",+ f"/notebooks/{harness.notebook_id}/save",+ headers={**key("save-1"), "If-Match": '"stale"'},+ body=b"{}",+ )+ assert again.status == 409+ assert "another request" in again.json()["detail"]+ disconnect()+++async def test_edits_during_a_save_remain_unsaved(+ harness: Harness, monkeypatch: pytest.MonkeyPatch+) -> None:+ document = (await harness.host.notebook(harness.notebook_id)).document+ written = document._record.etag+ started = asyncio.Event()+ release = threading.Event()+ loop = asyncio.get_running_loop()+ original = AppFileManager.save_from_cells++ def save(self: AppFileManager, cells: Any, **kwargs: Any) -> str:+ loop.call_soon_threadsafe(started.set)+ assert release.wait(5)+ return original(self, cells, **kwargs)++ monkeypatch.setattr(AppFileManager, "save_from_cells", save)+ saved, task, _ = request(+ harness.app,+ "POST",+ f"/notebooks/{harness.notebook_id}/save",+ headers=key("save-before-edit"),+ body=b"{}",+ )+ try:+ await asyncio.wait_for(started.wait(), 5)+ edited = await finished(+ harness.app,+ "POST",+ f"/notebooks/{harness.notebook_id}/edits",+ headers=key("edit-during-save"),+ body=edit_body(+ {+ "kind": "put_cell",+ "base_etag": None,+ "cell": {"id": "new", "code": "new_value = 42"},+ }+ ),+ )+ assert edited.status == 200, edited.body+ finally:+ release.set()+ await asyncio.wait_for(task, 5)++ assert saved.status == 200, saved.body+ assert saved.json()["document"] == {+ **edited.json()["document"],+ "saved_etag": written,+ }+ assert "new_value" not in (harness.root / "forecasts.py").read_text()+++async def test_a_file_changed_outside_marimo_needs_a_decision(+ harness: Harness,+) -> None:+ stream, disconnect = await opened(harness)+ disconnect()+ cell = first_record(stream, "cell")["cell"]+ file = harness.root / "forecasts.py"+ edited = await finished(+ harness.app,+ "POST",+ f"/notebooks/{harness.notebook_id}/edits",+ headers=key("edit-1"),+ body=edit_body(+ {+ "kind": "put_cell",+ "base_etag": cell["etag"],+ "cell": {"id": cell["id"], "code": "x = 99"},+ }+ ),+ )+ assert edited.status == 200, edited.body+ file.write_text(file.read_text().replace("x = 21", "x = 22"))++ async def save(name: str, body: bytes) -> Response:+ return await finished(+ harness.app,+ "POST",+ f"/notebooks/{harness.notebook_id}/save",+ headers=key(name),+ body=body,+ )++ asked = await save("save-1", b"{}")+ assert asked.status == 409, asked.body+ problem = asked.json()+ assert problem["type"].endswith("/decision-required")+ assert [d["id"] for d in problem["decisions"]] == ["file"]+ assert [o["id"] for o in problem["decisions"][0]["options"]] == [+ "overwrite",+ "reload",+ ]+ assert "x = 22" in file.read_text()++ unknown = await save("save-2", b'{"decisions": {"file": "merge"}}')+ assert unknown.status == 400, unknown.body+ assert unknown.json()["type"].endswith("/invalid-request")++ reloaded = await save("save-3", b'{"decisions": {"file": "reload"}}')+ assert reloaded.status == 200, reloaded.body+ response = reloaded.json()+ assert response["document"]["saved_etag"] == response["document"]["etag"]+ assert set(response["cells"]) == {cell["id"]}+ document = (await harness.host.notebook(harness.notebook_id)).document+ assert document.cell(cell["id"]).code == "x = 22" # type: ignore[union-attr]+ assert "x = 22" in file.read_text()++ # With the document back in step with the file, a plain save proceeds.+ edited = await finished(+ harness.app,+ "POST",+ f"/notebooks/{harness.notebook_id}/edits",+ headers=key("edit-2"),+ body=edit_body(+ {+ "kind": "put_cell",+ "base_etag": "*",+ "cell": {"id": cell["id"], "code": "x = 100"},+ }+ ),+ )+ assert edited.status == 200, edited.body+ file.write_text(file.read_text().replace("x = 22", "x = 23"))+ overwritten = await save("save-4", b'{"decisions": {"file": "overwrite"}}')+ assert overwritten.status == 200, overwritten.body+ assert "x = 100" in file.read_text()+ assert (await save("save-5", b"{}")).status == 200++ # The host's own writes are not changes, even when the file does not+ # read back as written: a new cell's id is not stored in the file.+ for n, base, code in ((6, None, "y = 1\n\n"), (7, "*", "y = 2")):+ edited = await finished(+ harness.app,+ "POST",+ f"/notebooks/{harness.notebook_id}/edits",+ headers=key(f"edit-{n}"),+ body=edit_body(+ {+ "kind": "put_cell",+ "base_etag": base,+ "cell": {"id": "fresh", "code": code},+ }+ ),+ )+ assert edited.status == 200, edited.body+ assert (await save(f"save-{n}", b"{}")).status == 200diff --git a/tests/_server/host/test_host_bridge.py b/tests/_server/host/test_host_bridge.pyindex 4b5cbe5d83..8d1a6f383a 100644--- a/tests/_server/host/test_host_bridge.py+++ b/tests/_server/host/test_host_bridge.py@@ -4,13 +4,14 @@from __future__ import annotationsimport asyncio+import threadingfrom typing import TYPE_CHECKINGimport pytestfrom marimo._config.manager import MarimoConfigManagerfrom marimo._core import protocol-from marimo._core.errors import Conflict+from marimo._core.errors import Conflict, DecisionRequired, EditConflictfrom marimo._core.stream import Eventfrom marimo._messaging.notification import (CompletedRunNotification,@@ -742,3 +743,308 @@ async def test_an_edit_reaches_the_kernel_as_one_command(EditCellsCommand(codes={"new": "z = 2"}, configs={}, delete_ids=[])]bridge.close()+++def replace_code(cell: protocol.Cell, code: str) -> protocol.PutCell:+ return protocol.PutCell(+ base_etag=cell.etag, cell=protocol.CellInput(id=cell.id, code=code)+ )+++async def test_save_writes_the_cells_and_keeps_the_app_config(+ manager: FakeManager, tmp_path: Path+) -> None:+ prepare(manager, tmp_path, "a.py")+ path = tmp_path / "a.py"+ path.write_text(+ NOTEBOOK.replace("marimo.App()", 'marimo.App(width="full")')+ )+ bridge = SessionBridge(manager) # type: ignore[arg-type]+ await bridge.open()+ record = bridge.index.notebook_for(str(path))+ assert record is not None+ document = (await bridge.host.notebook(record.id)).document+ (cell,) = document+ events: list[Event] = []+ bridge.host.subscribe(events.append, notebook_id=record.id)++ edited = await bridge.edit(+ record.id, [replace_code(cell, "x = 2")], request_id="edit-1"+ )+ assert edited.document.saved_etag != edited.document.etag++ with pytest.raises(EditConflict) as stale:+ await bridge.save(record.id, if_match=["stale"], request_id="save-0")+ assert stale.value.change == 0+ assert "x = 2" not in path.read_text()++ saved = await bridge.save(+ record.id, if_match=[edited.document.etag], request_id="save-1"+ )++ assert (+ saved.document.saved_etag+ == saved.document.etag+ == edited.document.etag+ )+ assert saved.cells == {}+ text = path.read_text()+ assert "x = 2" in text+ assert 'width="full"' in text+ assert names(events)[-1] == "document"+ assert events[-1].data.request_id == "save-1" # type: ignore[union-attr]+ bridge.close()+++async def test_saving_keeps_an_edit_made_while_the_file_is_written(+ manager: FakeManager, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ from marimo._session.notebook import AppFileManager++ prepare(manager, tmp_path, "a.py")+ path = tmp_path / "a.py"+ path.write_text(NOTEBOOK)+ bridge = SessionBridge(manager) # type: ignore[arg-type]+ await bridge.open()+ record = bridge.index.notebook_for(str(path))+ assert record is not None+ document = (await bridge.host.notebook(record.id)).document+ (cell,) = document+ written = document._record.etag++ started = asyncio.Event()+ release = threading.Event()+ loop = asyncio.get_running_loop()+ original = AppFileManager.save_from_cells++ def save(self: AppFileManager, cells: Any, **kwargs: Any) -> str:+ loop.call_soon_threadsafe(started.set)+ assert release.wait(5)+ return original(self, cells, **kwargs)++ monkeypatch.setattr(AppFileManager, "save_from_cells", save)+ saving = asyncio.ensure_future(+ bridge.save(record.id, if_match=None, request_id="save-1")+ )+ try:+ await asyncio.wait_for(started.wait(), 5)+ edited = await bridge.edit(+ record.id, [replace_code(cell, "x = 2")], request_id="edit-1"+ )+ finally:+ release.set()+ saved = await asyncio.wait_for(saving, 5)++ # The file has the snapshot; the host keeps the edit, unsaved.+ assert saved.document.etag == edited.document.etag+ assert saved.document.saved_etag == written+ assert document._record.saved_etag != document._record.etag+ assert "x = 1" in path.read_text()+ assert "x = 2" not in path.read_text()+ bridge.close()+++async def test_save_with_a_session_writes_through_the_editors_file_manager(+ manager: FakeManager, tmp_path: Path+) -> None:+ from marimo._session.notebook import AppFileManager++ prepare(manager, tmp_path, "a.py")+ path = tmp_path / "a.py"+ path.write_text(NOTEBOOK)+ session = FakeSession(str(path))+ session.app_file_manager = AppFileManager(str(path))+ session.document = session.app_file_manager.app.cell_manager.document+ manager.sessions["browser-1"] = session+ bridge = SessionBridge(manager) # type: ignore[arg-type]+ await bridge.open()+ record = bridge.index.notebook_for(str(path))+ assert record is not None+ document = (await bridge.host.notebook(record.id)).document+ (cell,) = document+ # The editor wrote once, so its manager remembers what is on disk.+ session.app_file_manager.save_from_cells(list(session.document.cells))+ events: list[Event] = []+ bridge.host.subscribe(events.append, notebook_id=record.id)++ edited = await bridge.edit(+ record.id, [replace_code(cell, "x = 2")], request_id="edit-1"+ )+ saved = await bridge.save(record.id, if_match=None, request_id="save-1")++ assert saved.document.saved_etag == edited.document.etag+ text = path.read_text()+ assert "x = 2" in text+ # The editor's record of the last write is the host's write, so its+ # watcher ignores it and its next write of other content proceeds.+ assert session.app_file_manager.content_matches_last_save(text)+ # The write is published once, under the request that asked for it,+ # not again when the editor's manager reports it.+ published = [+ e+ for e in events+ if e.name == "document"+ and e.data.document.saved_etag == saved.document.etag # type: ignore[union-attr]+ ]+ assert [e.data.request_id for e in published] == ["save-1"] # type: ignore[union-attr]+ bridge.close()+++async def test_the_editor_saving_marks_the_host_document_saved(+ manager: FakeManager, tmp_path: Path+) -> None:+ from marimo._ast.cell import CellConfig+ from marimo._core.document import revision+ from marimo._messaging.notebook import NotebookCell+ from marimo._server.host.document import from_file_manager+ from marimo._session.notebook import AppFileManager+ from marimo._types.ids import CellId_t++ prepare(manager, tmp_path, "a.py")+ path = tmp_path / "a.py"+ path.write_text(NOTEBOOK)+ bridge = SessionBridge(manager) # type: ignore[arg-type]+ await bridge.open()+ record = bridge.index.notebook_for(str(path))+ assert record is not None+ document = (await bridge.host.notebook(record.id)).document+ session = FakeSession(str(path))+ session.app_file_manager = AppFileManager(str(path))+ session.document = session.app_file_manager.app.cell_manager.document+ manager.sessions["browser-1"] = session+ await manager.event_bus.emit_session_created(session) # type: ignore[arg-type]+ (cell,) = session.document.cells+ before = document._record.etag++ # The editor writes new content the host has not mirrored yet.+ session.app_file_manager.save_from_cells(+ [NotebookCell(CellId_t(cell.id), "x = 2", cell.name, CellConfig())]+ )++ written = revision(*from_file_manager(session.app_file_manager))+ assert document._record.saved_etag == written+ assert document._record.etag == before != written++ # Once the session goes away, its writes are no longer the host's,+ # and the file as the editor left it is what the host compares to.+ manager.close_session("browser-1")+ assert session.app_file_manager.on_persisted is None+ saved = await bridge.save(record.id, if_match=None, request_id="save-1")+ assert saved.document.saved_etag == saved.document.etag+ assert "x = 1" in path.read_text()+ path.write_text(path.read_text().replace("x = 1", "x = 3"))+ with pytest.raises(DecisionRequired):+ await bridge.save(record.id, if_match=None, request_id="save-2")+ bridge.close()++[email protected]("error", [OSError, UnicodeError])+async def test_save_refuses_to_overwrite_when_the_file_cannot_be_read(+ manager: FakeManager,+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+ error: type[Exception],+) -> None:+ prepare(manager, tmp_path, "a.py")+ path = tmp_path / "a.py"+ path.write_text(NOTEBOOK)+ bridge = SessionBridge(manager) # type: ignore[arg-type]+ await bridge.open()+ record = bridge.index.notebook_for(str(path))+ assert record is not None+ notebook = await bridge.host.notebook(record.id)+ before = notebook.document.snapshot()+ external = NOTEBOOK.replace("x = 1", "x = 2")+ path.write_text(external)++ def unreadable(_file: Path) -> str:+ raise error("The change check failed, but the file is writable")++ monkeypatch.setattr("marimo._server.host.bridge._read_text", unreadable)+ try:+ with pytest.raises(Conflict, match="could not be read"):+ await bridge.save(record.id, if_match=None, request_id="save-1")+ assert path.read_text() == external+ assert notebook.document.snapshot() == before+ finally:+ bridge.close()+++async def test_save_without_a_file_baseline_requires_a_decision(+ manager: FakeManager, tmp_path: Path+) -> None:+ prepare(manager, tmp_path, "a.py")+ path = tmp_path / "a.py"+ path.write_text(NOTEBOOK)+ bridge = SessionBridge(manager) # type: ignore[arg-type]+ await bridge.open()+ record = bridge.index.notebook_for(str(path))+ assert record is not None+ await bridge.host.notebook(record.id)+ bridge._file_texts.pop(record.id)+ external = NOTEBOOK.replace("x = 1", "x = 2")+ path.write_text(external)+ try:+ with pytest.raises(DecisionRequired):+ await bridge.save(record.id, if_match=None, request_id="save-1")+ assert path.read_text() == external++ reloaded = await bridge.save(+ record.id,+ if_match=None,+ decisions={"file": "reload"},+ request_id="save-2",+ )+ assert reloaded.document.saved_etag == reloaded.document.etag+ assert path.read_text() == external+ assert bridge._file_texts[record.id] == external+ finally:+ bridge.close()+++async def test_reloading_refuses_to_drop_an_edit_made_while_reading(+ manager: FakeManager, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ prepare(manager, tmp_path, "a.py")+ path = tmp_path / "a.py"+ path.write_text(NOTEBOOK)+ bridge = SessionBridge(manager) # type: ignore[arg-type]+ await bridge.open()+ record = bridge.index.notebook_for(str(path))+ assert record is not None+ document = (await bridge.host.notebook(record.id)).document+ (cell,) = document+ path.write_text(NOTEBOOK.replace("x = 1", "x = 2"))++ started = asyncio.Event()+ release = threading.Event()+ loop = asyncio.get_running_loop()+ original = SessionBridge._read++ def read(self: SessionBridge, file: Path) -> Any:+ loop.call_soon_threadsafe(started.set)+ assert release.wait(5)+ return original(self, file)++ monkeypatch.setattr(SessionBridge, "_read", read)+ reloading = asyncio.ensure_future(+ bridge.save(+ record.id,+ if_match=None,+ decisions={"file": "reload"},+ request_id="save-1",+ )+ )+ try:+ await asyncio.wait_for(started.wait(), 5)+ edited = await bridge.edit(+ record.id, [replace_code(cell, "x = 3")], request_id="edit-1"+ )+ finally:+ release.set()++ with pytest.raises(EditConflict) as conflict:+ await asyncio.wait_for(reloading, 5)+ assert conflict.value.document == edited.document+ assert document.cell(cell.id).code == "x = 3" # type: ignore[union-attr]+ bridge.close()diff --git a/tests/_session/notebook/test_app_file_manager.py b/tests/_session/notebook/test_app_file_manager.pyindex dbee61fd71..ed72f6c06b 100644--- a/tests/_session/notebook/test_app_file_manager.py+++ b/tests/_session/notebook/test_app_file_manager.py@@ -213,3 +213,23 @@ def test_manifest_and_cell_saves_preserve_each_other(assert [cell.code for cell in saved.app.cell_manager.cell_data()] == ["x = 2"]+++def test_on_persisted_reports_the_cells_and_config_written(+ tmp_path: Path,+) -> None:+ from marimo._ast.cell import CellConfig+ from marimo._messaging.notebook.document import NotebookCell+ from marimo._types.ids import CellId_t++ nb = tmp_path / "nb.py"+ nb.write_text(_NOTEBOOK_SOURCE.replace("App()", 'App(width="full")'))+ fm = AppFileManager(str(nb))+ seen: list[tuple[list[NotebookCell], dict[str, object]]] = []+ fm.on_persisted = lambda cells, config: seen.append((list(cells), config))+ (cell,) = fm.app.cell_manager.cell_data()+ cells = [NotebookCell(CellId_t(cell.cell_id), "x = 2", "_", CellConfig())]++ fm.save_from_cells(cells)++ assert seen == [(cells, {"width": "full"})]