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
refactor: consolidate `CellManager` and `NotebookDocument` (#9405)
Kiran Gadhave981b3e686043
diff --git a/marimo/_ast/app.py b/marimo/_ast/app.pyindex 2b3df508f1..6ebbde763d 100644--- a/marimo/_ast/app.py+++ b/marimo/_ast/app.py@@ -294,7 +294,7 @@ class App:strict=False,):cell = None- cell_data = self._cell_manager._cell_data.get(cell_id)+ cell_data = self._cell_manager.get_cell_data(cell_id)new_cell_id = app._cell_manager.create_cell_id()# If the cell exists, the cell data should be set (ie not None).if cell_data is not None:@@ -1014,23 +1014,31 @@ class InternalApp:names: Iterable[str],configs: Iterable[CellConfig],) -> InternalApp:- new_cell_manager = CellManager()+ """Rewrite the cell list from textual fields, in place.++ Mutates ``self._app._cell_manager`` rather than replacing it,+ so any caller holding ``app.cell_manager`` or+ ``app.cell_manager.document`` (notably ``Session.document``)+ continues to see live state without rebinding.++ Cells that survive the rewrite keep their compiled ``Cell``;+ callers from save flows pass the frontend's snapshot, which+ renames/reorders/reconfigures cells but doesn't recompile.+ """+ cm = self._app._cell_manager+ prev_compiled = dict(cm._compiled_cells)+ rebuilt = CellManager(prefix=cm.prefix)for cell_id, code, name, config in zip(cell_ids, codes, names, configs, strict=False):- cell = None- # If the cell exists, the cell data should be set.- cell_data = self._app._cell_manager._cell_data.get(cell_id)- if cell_data is not None:- cell = cell_data.cell- new_cell_manager.register_cell(+ rebuilt.register_cell(cell_id=cell_id,code=code,name=name,config=config,- cell=cell,+ cell=prev_compiled.get(cell_id),)- self._app._cell_manager = new_cell_manager+ cm._replace_state_from(rebuilt)return selfasync def run_cell_async(@@ -1073,7 +1081,7 @@ class InternalApp:name=cell_data.name,options=cell_data.config.asdict(),)- for cell_data in self._app._cell_manager._cell_data.values()+ for cell_data in self._app._cell_manager.cell_data()],app=AppInstantiation(options=self._app._config.asdict(),diff --git a/marimo/_ast/cell_manager.py b/marimo/_ast/cell_manager.pyindex ef91125a6b..fe5141c7cc 100644--- a/marimo/_ast/cell_manager.py+++ b/marimo/_ast/cell_manager.py@@ -10,6 +10,8 @@ from typing import (TypeVar,)+from msgspec.structs import replace as structs_replace+from marimo import _loggersfrom marimo._ast.cell import Cell, CellConfigfrom marimo._ast.cell_id import CellIdGenerator@@ -23,6 +25,7 @@ from marimo._ast.models import CellDatafrom marimo._ast.names import DEFAULT_CELL_NAME, SETUP_CELL_NAMEfrom marimo._ast.parse import fixed_dedentfrom marimo._ast.pytest import process_for_pytest+from marimo._messaging.notebook.document import NotebookCell, NotebookDocumentfrom marimo._schemas.serialization import (CellDef,SetupCell,@@ -66,11 +69,17 @@ class CellManager:Args:prefix (str, optional): Prefix to add to all cell IDs. Defaults to ""."""- self._cell_data: dict[CellId_t, CellData] = {}+ self._document = NotebookDocument()+ self._compiled_cells: dict[CellId_t, Cell | None] = {}self.prefix = prefixself.unparsable = Falseself._cell_id_generator = CellIdGenerator(prefix, seed=42)+ @property+ def document(self) -> NotebookDocument:+ """The underlying NotebookDocument tracking cell-list state."""+ return self._document+def create_cell_id(self) -> CellId_t:"""Create a new unique cell ID.@@ -207,14 +216,25 @@ class CellManager:"""if cell_id is None:cell_id = self.create_cell_id()-- self._cell_data[cell_id] = CellData(- cell_id=cell_id,- code=code,- name=name,- config=config or CellConfig(),- cell=cell,- )+ else:+ self._cell_id_generator.seen_ids.add(cell_id)++ resolved_config = config or CellConfig()+ existing = self._document.get(cell_id)+ if existing is not None:+ existing.code = code+ existing.name = name+ existing.config = resolved_config+ else:+ self._document._cells.append(+ NotebookCell(+ id=cell_id,+ code=code,+ name=name,+ config=resolved_config,+ )+ )+ self._compiled_cells[cell_id] = celldef register_ir_cell(self, cell_def: CellDef, app: InternalApp | None = None@@ -263,7 +283,7 @@ class CellManager:"""# If this is the first cell, and its name is setup, assume that it's# the setup cell.- if len(self._cell_data) == 0 and name == SETUP_CELL_NAME:+ if len(self._document) == 0 and name == SETUP_CELL_NAME:cell_id = self.setup_cell_idelse:cell_id = self.create_cell_id()@@ -281,7 +301,7 @@ class CellManager:If no cells exist, creates an empty cell with default configuration."""- if not self._cell_data:+ if len(self._document) == 0:cell_id = self.create_cell_id()self.register_cell(cell_id=cell_id,@@ -289,6 +309,16 @@ class CellManager:config=CellConfig(),)+ def _synthesize_cell_data(self, nb_cell: NotebookCell) -> CellData:+ """Build a CellData view from a NotebookCell + the compiled sidecar."""+ return CellData(+ cell_id=nb_cell.id,+ code=nb_cell.code,+ name=nb_cell.name,+ config=nb_cell.config,+ cell=self._compiled_cells.get(nb_cell.id),+ )+def cell_name(self, cell_id: CellId_t) -> str:"""Get the name of a cell by its ID.@@ -301,7 +331,7 @@ class CellManager:Raises:KeyError: If the cell_id doesn't exist"""- return self._cell_data[cell_id].name+ return self._document.get_cell(cell_id).namedef names(self) -> Iterable[str]:"""Get an iterator over all cell names.@@ -309,8 +339,8 @@ class CellManager:Returns:Iterable[str]: Iterator yielding each cell's name"""- for cell_data in self._cell_data.values():- yield cell_data.name+ for nb_cell in self._document._cells:+ yield nb_cell.namedef codes(self) -> Iterable[str]:"""Get an iterator over all cell codes.@@ -318,8 +348,8 @@ class CellManager:Returns:Iterable[str]: Iterator yielding each cell's source code"""- for cell_data in self._cell_data.values():- yield cell_data.code+ for nb_cell in self._document._cells:+ yield nb_cell.codedef code_lookup(self) -> dict[CellId_t, str]:"""Get a dict for cell codes.@@ -327,10 +357,7 @@ class CellManager:Returns:dict[CellId_t, str]: Dictionary mapping cell to their source code"""- return {- cell_id: cell_data.code- for cell_id, cell_data in self._cell_data.items()- }+ return {nb_cell.id: nb_cell.code for nb_cell in self._document._cells}def configs(self) -> Iterable[CellConfig]:"""Get an iterator over all cell configurations.@@ -338,8 +365,8 @@ class CellManager:Returns:Iterable[CellConfig]: Iterator yielding each cell's configuration"""- for cell_data in self._cell_data.values():- yield cell_data.config+ for nb_cell in self._document._cells:+ yield nb_cell.configdef valid_cells(self,@@ -350,9 +377,10 @@ class CellManager:Iterable[tuple[CellId_t, Cell]]: Iterator yielding tuples of (cell_id, cell)for each valid cell"""- for cell_data in self._cell_data.values():- if cell_data.cell is not None:- yield (cell_data.cell_id, cell_data.cell)+ for nb_cell in self._document._cells:+ cell = self._compiled_cells.get(nb_cell.id)+ if cell is not None:+ yield (nb_cell.id, cell)def valid_cell_ids(self) -> Iterable[CellId_t]:"""Get an iterator over IDs of all valid cells.@@ -360,9 +388,9 @@ class CellManager:Returns:Iterable[CellId_t]: Iterator yielding cell IDs of valid cells"""- for cell_data in self._cell_data.values():- if cell_data.cell is not None:- yield cell_data.cell_id+ for nb_cell in self._document._cells:+ if self._compiled_cells.get(nb_cell.id) is not None:+ yield nb_cell.iddef cell_ids(self) -> Iterable[CellId_t]:"""Get an iterator over all cell IDs in registration order.@@ -370,7 +398,7 @@ class CellManager:Returns:Iterable[CellId_t]: Iterator yielding all cell IDs"""- return self._cell_data.keys()+ return self._document.cell_idsdef has_cell(self, cell_id: CellId_t) -> bool:"""Check if a cell with the given ID exists.@@ -381,7 +409,7 @@ class CellManager:Returns:bool: True if the cell exists, False otherwise"""- return cell_id in self._cell_data+ return cell_id in self._documentdef cells(self,@@ -391,8 +419,8 @@ class CellManager:Returns:Iterable[Optional[Cell]]: Iterator yielding Cell objects (or None for invalid cells)"""- for cell_data in self._cell_data.values():- yield cell_data.cell+ for nb_cell in self._document._cells:+ yield self._compiled_cells.get(nb_cell.id)def config_map(self) -> dict[CellId_t, CellConfig]:"""Get a mapping of cell IDs to their configurations.@@ -400,7 +428,9 @@ class CellManager:Returns:dict[CellId_t, CellConfig]: Dictionary mapping cell IDs to their configurations"""- return {cid: cd.config for cid, cd in self._cell_data.items()}+ return {+ nb_cell.id: nb_cell.config for nb_cell in self._document._cells+ }def cell_data(self) -> Iterable[CellData]:"""Get an iterator over all cell data.@@ -408,7 +438,8 @@ class CellManager:Returns:Iterable[CellData]: Iterator yielding CellData objects for all cells"""- return self._cell_data.values()+ for nb_cell in self._document._cells:+ yield self._synthesize_cell_data(nb_cell)def code_map(self) -> dict[CellId_t, str]:"""Get a mapping of cell IDs to their codes.@@ -416,7 +447,7 @@ class CellManager:Returns:dict[CellId_t, str]: Dictionary mapping cell IDs to their codes"""- return {cid: cd.code for cid, cd in self._cell_data.items()}+ return {nb_cell.id: nb_cell.code for nb_cell in self._document._cells}def cell_data_at(self, cell_id: CellId_t) -> CellData:"""Get the cell data for a specific cell ID.@@ -430,7 +461,7 @@ class CellManager:Raises:KeyError: If the cell_id doesn't exist"""- return self._cell_data[cell_id]+ return self._synthesize_cell_data(self._document.get_cell(cell_id))def get_cell_code(self, cell_id: CellId_t) -> str | None:"""Get the code for a cell by its ID.@@ -441,9 +472,10 @@ class CellManager:Returns:Optional[str]: The cell's code, or None if the cell doesn't exist"""- if cell_id not in self._cell_data:+ nb_cell = self._document.get(cell_id)+ if nb_cell is None:return None- return self._cell_data[cell_id].code+ return nb_cell.codedef get_cell_data(self, cell_id: CellId_t) -> CellData | None:"""Get the cell data for a specific cell ID.@@ -454,10 +486,11 @@ class CellManager:Returns:Optional[CellData]: The cell's data, or None if the cell doesn't exist"""- if cell_id not in self._cell_data:+ nb_cell = self._document.get(cell_id)+ if nb_cell is None:LOGGER.debug(f"Cell with ID '{cell_id}' not found in cell manager")return None- return self._cell_data[cell_id]+ return self._synthesize_cell_data(nb_cell)def get_cell_data_by_name(self, name: str) -> CellData | None:"""Find a cell ID by its name.@@ -469,9 +502,9 @@ class CellManager:Optional[CellData]: The data of the first cell with matching name,or None if no match is found"""- for cell_data in self._cell_data.values():- if cell_data.name.strip("*") == name:- return cell_data+ for nb_cell in self._document._cells:+ if nb_cell.name.strip("*") == name:+ return self._synthesize_cell_data(nb_cell)return Nonedef get_cell_id_by_code(self, code: str) -> CellId_t | None:@@ -484,11 +517,36 @@ class CellManager:Optional[CellId_t]: The ID of the first cell with matching code,or None if no match is found"""- for cell_id, cell_data in self._cell_data.items():- if cell_data.code == code:- return cell_id+ for nb_cell in self._document._cells:+ if nb_cell.code == code:+ return nb_cell.idreturn None+ def _replace_state_from(self, other: CellManager) -> None:+ """Overwrite this manager's content with ``other``'s, in place.++ Identity-preserving substitute for ``self = other``: the+ underlying ``NotebookDocument`` instance and the+ ``_compiled_cells`` dict instance are kept; only their contents+ are replaced. Any object holding a reference to this manager —+ most notably the owning ``Session`` (which holds+ ``cell_manager.document`` as ``session.document``) — continues+ to see live state without rebinding.++ ``unparsable`` is copied. ``_cell_id_generator.seen_ids`` is+ unioned (never narrowed) so we don't recycle an id seen+ previously even if it's gone from ``other``.++ Transitional helper: cell-list bulk-replace bypasses+ ``NotebookDocument.apply``. Goes away once full-document+ rebuilds are expressed as diff Transactions.+ """+ self._document._replace_cells(list(other._document._cells))+ self._compiled_cells.clear()+ self._compiled_cells.update(other._compiled_cells)+ self.unparsable = other.unparsable+ self._cell_id_generator.seen_ids |= other._cell_id_generator.seen_ids+def sort_cell_ids_by_similarity(self, prev_cell_manager: CellManager) -> None:@@ -501,14 +559,19 @@ class CellManager:# Create mapping from new to old idsid_mapping = match_cell_ids_by_similarity(prev_codes, current_codes)- # Update the cell data in place- new_cell_data: dict[CellId_t, CellData] = {}+ # Rebuild the document and compiled-cell sidecar with rekeyed entries.+ # structs_replace produces a fresh NotebookCell per remap rather than+ # mutating the existing instance's id, keeping each instance's+ # primary key stable from construction to disposal.+ new_cells: list[NotebookCell] = []+ new_compiled: dict[CellId_t, Cell | None] = {}for new_id, old_id in id_mapping.items():- prev_cell_data = self._cell_data[old_id]- prev_cell_data.cell_id = new_id- new_cell_data[new_id] = prev_cell_data+ old_cell = self._document._find_cell(old_id)+ new_cells.append(structs_replace(old_cell, id=new_id))+ new_compiled[new_id] = self._compiled_cells.get(old_id)- self._cell_data = new_cell_data+ self._document._cells = new_cells+ self._compiled_cells = new_compiled# Add the new ids to the set, so we don't reuse them in the futurefor _id in id_mapping:diff --git a/marimo/_messaging/notebook/document.py b/marimo/_messaging/notebook/document.pyindex 414843c612..4e9dfc478e 100644--- a/marimo/_messaging/notebook/document.py+++ b/marimo/_messaging/notebook/document.py@@ -228,6 +228,20 @@ class NotebookDocument:# Helpers# ------------------------------------------------------------------+ def _replace_cells(self, cells: list[NotebookCell]) -> None:+ """Bulk-replace the cell list in place, bypassing ``apply``.++ Transitional. Used for full-document rebuilds (save round-trip)+ until those flows are expressed as diff Transactions. The+ ``_cells`` attribute is reassigned (not mutated element-wise)+ so any external holder of the prior list keeps a snapshot of+ pre-rebuild state — useful for diff comparison. Bumps+ ``version`` so observers see the state change like they would+ after ``apply()``.+ """+ self._cells = cells+ self._version += 1+def _find_index(self, cell_id: CellId_t) -> int:for i, cell in enumerate(self._cells):if cell.id == cell_id:diff --git a/marimo/_server/api/endpoints/files.py b/marimo/_server/api/endpoints/files.pyindex 9acc54ac58..24ff145f29 100644--- a/marimo/_server/api/endpoints/files.py+++ b/marimo/_server/api/endpoints/files.py@@ -181,14 +181,6 @@ async def save(session = app_state.require_current_session()contents = session.app_file_manager.save(body)- # Rebuild the document from the updated cell manager so that- # reconnections (which read session.document) reflect the saved state.- from marimo._session.session import _document_from_cell_manager-- session.document = _document_from_cell_manager(- session.app_file_manager.app.cell_manager- )-return PlainTextResponse(content=contents)diff --git a/marimo/_session/file_change_handler.py b/marimo/_session/file_change_handler.pyindex 366c95b109..08573ae13a 100644--- a/marimo/_session/file_change_handler.py+++ b/marimo/_session/file_change_handler.py@@ -10,6 +10,8 @@ import asynciofrom dataclasses import dataclassfrom typing import TYPE_CHECKING, Protocol+from msgspec.structs import replace as structs_replace+from marimo import _loggersfrom marimo._config.manager import MarimoConfigManagerfrom marimo._messaging.notebook import DocumentChange@@ -36,6 +38,8 @@ LOGGER = _loggers.marimo_logger()if TYPE_CHECKING:from pathlib import Path+ from marimo._ast.cell_manager import CellManager+ from marimo._messaging.notebook.document import NotebookDocumentfrom marimo._session.types import Session@@ -48,16 +52,74 @@ class FileChangeResult:changed_cell_ids: set[CellId_t] | None = None+def _build_reload_transaction(+ prev_document: NotebookDocument, cell_manager: CellManager+) -> Transaction:+ """Diff the pre-reload document against the post-reload cell manager.++ Used by the file-watch reload path. ``AppFileManager.reload`` swaps in+ a fresh ``App`` whose document already reflects the new state, so the+ returned transaction is purely for broadcasting the diff to consumers+ — it is not applied to any document.+ """+ cell_ids = list(cell_manager.cell_ids())+ new_ids = set(cell_ids)+ doc_ids = set(prev_document)+ deleted = doc_ids - new_ids++ changes: list[DocumentChange] = []+ for cid in deleted:+ changes.append(DeleteCell(cell_id=cid))++ for cd in cell_manager.cell_data():+ if cd.cell_id not in doc_ids:+ changes.append(+ CreateCell(+ cell_id=cd.cell_id,+ code=cd.code,+ name=cd.name,+ config=cd.config,+ )+ )+ else:+ doc_cell = prev_document.get_cell(cd.cell_id)+ if cd.code != doc_cell.code:+ changes.append(SetCode(cell_id=cd.cell_id, code=cd.code))+ if cd.name != doc_cell.name:+ changes.append(SetName(cell_id=cd.cell_id, name=cd.name))+ if cd.config != doc_cell.config:+ changes.append(+ SetConfig(+ cell_id=cd.cell_id,+ column=cd.config.column,+ disabled=cd.config.disabled,+ hide_code=cd.config.hide_code,+ )+ )++ if tuple(cell_ids) != tuple(prev_document.cell_ids):+ changes.append(ReorderCells(cell_ids=tuple(cell_ids)))++ return Transaction(changes=tuple(changes), source="file-watch")++class ReloadStrategy(Protocol):"""Protocol for file reload strategies."""def handle_reload(- self, session: Session, *, changed_cell_ids: set[CellId_t]+ self,+ session: Session,+ *,+ transaction: Transaction,+ changed_cell_ids: set[CellId_t],) -> None:"""Handle reloading after file change.Args:session: The session to reload+ transaction: Pre-built diff from the pre-reload document to the+ post-reload state. Strategies that broadcast cell-level+ changes use this; full-reload strategies can ignore it.changed_cell_ids: Set of cell IDs that changed"""...@@ -74,7 +136,11 @@ class EditModeReloadStrategy(ReloadStrategy):self._config_manager = config_managerdef handle_reload(- self, session: Session, *, changed_cell_ids: set[CellId_t]+ self,+ session: Session,+ *,+ transaction: Transaction,+ changed_cell_ids: set[CellId_t],) -> None:"""Handle reload in edit mode with optional auto-run."""cell_manager = session.app_file_manager.app.cell_manager@@ -87,58 +153,22 @@ class EditModeReloadStrategy(ReloadStrategy):f"changed_cell_ids: {changed_cell_ids}")- # Build a transaction by diffing session.document vs new cell_manager.- doc = session.document- doc_ids = set(doc)- new_ids = set(cell_ids)- deleted = doc_ids - new_ids-- changes: list[DocumentChange] = []-- # Deletes- for cid in deleted:- changes.append(DeleteCell(cell_id=cid))-- # Creates and updates- for cd in cell_manager.cell_data():- if cd.cell_id not in doc_ids:- changes.append(- CreateCell(- cell_id=cd.cell_id,- code=cd.code,- name=cd.name,- config=cd.config,- )- )- else:- doc_cell = doc.get_cell(cd.cell_id)- if cd.code != doc_cell.code:- changes.append(SetCode(cell_id=cd.cell_id, code=cd.code))- if cd.name != doc_cell.name:- changes.append(SetName(cell_id=cd.cell_id, name=cd.name))- if cd.config != doc_cell.config:- changes.append(- SetConfig(- cell_id=cd.cell_id,- column=cd.config.column,- disabled=cd.config.disabled,- hide_code=cd.config.hide_code,- )- )-- # Reorder if the lists differ- if tuple(cell_ids) != tuple(doc.cell_ids):- changes.append(ReorderCells(cell_ids=tuple(cell_ids)))-- if changes:- # Broadcast transaction — document.apply() applies to- # document and stamps the version before forwarding.- transaction = Transaction(- changes=tuple(changes), source="file-watch"- )- applied = session.document.apply(transaction)+ deleted = {+ change.cell_id+ for change in transaction.changes+ if isinstance(change, DeleteCell)+ }++ if transaction.changes:+ # AppFileManager.reload already brought session.document to the+ # post-reload state, so we don't apply(); we only broadcast.+ # Bump the document version manually so the stamped transaction+ # is consistent with what apply() would produce.+ new_doc = session.document+ new_doc._version += 1+ stamped = structs_replace(transaction, version=new_doc._version)session.notify(- NotebookDocumentTransactionNotification(transaction=applied),+ NotebookDocumentTransactionNotification(transaction=stamped),from_consumer_id=None,)@@ -169,17 +199,21 @@ class EditModeReloadStrategy(ReloadStrategy):)-class RunModeReloadStrategy:+class RunModeReloadStrategy(ReloadStrategy):"""Reload strategy for run mode.In run mode, we simply send a reload operation to the frontend."""def handle_reload(- self, session: Session, *, changed_cell_ids: set[CellId_t]+ self,+ session: Session,+ *,+ transaction: Transaction,+ changed_cell_ids: set[CellId_t],) -> None:"""Handle reload in run mode by sending Reload operation."""- del changed_cell_ids+ del transaction, changed_cell_idssession.notify(ReloadNotification(), from_consumer_id=None)@@ -256,6 +290,11 @@ class FileChangeCoordinator:)return FileChangeResult(handled=False)+ # Snapshot the document before reload swaps in a fresh App. The+ # property would otherwise return the post-reload doc by the time+ # we diff, leaving the strategy with no "before" state to compare.+ prev_document = session.document+# Reload the file manager to get the latest codetry:changed_cell_ids = session.app_file_manager.reload()@@ -265,9 +304,15 @@ class FileChangeCoordinator:LOGGER.error(f"Error loading file: {e}")return FileChangeResult(handled=False, error=str(e))+ transaction = _build_reload_transaction(+ prev_document, session.app_file_manager.app.cell_manager+ )+# Delegate to the reload strategyself._reload_strategy.handle_reload(- session, changed_cell_ids=changed_cell_ids+ session,+ transaction=transaction,+ changed_cell_ids=changed_cell_ids,)return FileChangeResult(handled=True, changed_cell_ids=changed_cell_idsdiff --git a/marimo/_session/session.py b/marimo/_session/session.pyindex 87d02ef40e..6e4a88992d 100644--- a/marimo/_session/session.py+++ b/marimo/_session/session.py@@ -15,7 +15,7 @@ from uuid import uuid4from marimo import _loggersfrom marimo._cli.sandbox import SandboxModefrom marimo._config.manager import MarimoConfigManager, ScriptConfigManager-from marimo._messaging.notebook.document import NotebookCell, NotebookDocument+from marimo._messaging.notebook.document import NotebookDocumentfrom marimo._messaging.notification import (NotificationMessage,)@@ -65,7 +65,6 @@ from marimo._utils.repr import format_reprif TYPE_CHECKING:from collections.abc import Iterator, Mapping- from marimo._ast.cell_manager import CellManagerfrom marimo._runtime.virtual_file import VirtualFileStorageTypefrom marimo._server.models.models import InstantiateNotebookRequestfrom marimo._session.app_host import AppHostContext@@ -77,29 +76,6 @@ _DEFAULT_TTL_SECONDS = 120__all__ = ["Session", "SessionImpl"]-def _document_from_cell_manager(cell_manager: CellManager) -> NotebookDocument:- """Build a NotebookDocument from a CellManager's current state.-- TODO: CellManager and NotebookDocument track overlapping state (cell- ordering, code, names, configs). Once the document model is wired- into all consumers, we should reconcile these — either CellManager- wraps a NotebookDocument internally, or it is replaced by a- different composition. For now, the document is populated from the- cell manager at session startup and the two coexist.- """- return NotebookDocument(- [- NotebookCell(- id=cd.cell_id,- code=cd.code,- name=cd.name,- config=cd.config,- )- for cd in cell_manager.cell_data()- ]- )--class SessionImpl(Session):"""A client session.@@ -258,9 +234,6 @@ class SessionImpl(Session):self.ttl_seconds = (ttl_seconds if ttl_seconds is not None else _DEFAULT_TTL_SECONDS)- self.document = _document_from_cell_manager(- app_file_manager.app.cell_manager- )self.session_view = SessionView()self.config_manager = config_managerself.extensions = ExtensionRegistry()@@ -278,6 +251,19 @@ class SessionImpl(Session):# to avoid calling on_attach on the main consumer twice.self.connect_consumer(session_consumer, main=True)+ @property+ def document(self) -> NotebookDocument:+ """The notebook document this session reflects.++ Derived from ``self.app_file_manager.app.cell_manager.document``+ rather than stored, so any code path that swaps the underlying+ ``CellManager`` or ``app`` (save round-trip, file-watch reload,+ export reload) is automatically picked up — no rebinding needed+ at the call sites. Read-only by design: the document's identity+ belongs to the cell manager.+ """+ return self.app_file_manager.app.cell_manager.document+def _attach_extensions(self) -> None:"""Attach all extensions to the session."""for extension in self.extensions:diff --git a/marimo/_session/types.py b/marimo/_session/types.pyindex cf3e5f60f1..6df5b36490 100644--- a/marimo/_session/types.py+++ b/marimo/_session/types.py@@ -110,11 +110,15 @@ class Session(Protocol):initialization_id: strapp_file_manager: AppFileManagerconfig_manager: MarimoConfigManager- document: NotebookDocumentsession_view: SessionViewttl_seconds: intscratchpad_lock: asyncio.Lock+ @property+ def document(self) -> NotebookDocument:+ """The notebook document this session reflects."""+ ...+@propertydef consumers(self) -> Mapping[SessionConsumer, ConsumerId]:"""Get the consumers in the session."""diff --git a/tests/_ast/test_app.py b/tests/_ast/test_app.pyindex 0fbe07a65d..c91e4bb854 100644--- a/tests/_ast/test_app.py+++ b/tests/_ast/test_app.py@@ -19,6 +19,7 @@ from marimo._ast.app import (InternalApp,)from marimo._ast.app_config import _AppConfig+from marimo._ast.cell import CellConfigfrom marimo._ast.cell_id import is_external_cell_idfrom marimo._ast.errors import (CycleError,@@ -936,12 +937,12 @@ class TestApp:original_cell_ids = list(original_internal.cell_manager.cell_ids())cloned_cell_ids = list(cloned_internal.cell_manager.cell_ids())- original_cell = original_internal.cell_manager._cell_data[+ original_cell = original_internal.cell_manager.cell_data_at(original_cell_ids[0]- ].cell- cloned_cell = cloned_internal.cell_manager._cell_data[+ ).cell+ cloned_cell = cloned_internal.cell_manager.cell_data_at(cloned_cell_ids[0]- ].cell+ ).cellassert original_cell is not Noneassert cloned_cell is not None@@ -1566,7 +1567,7 @@ class TestAppComposition:with app1.setup:x = 1- setup_cell = app1._cell_manager._cell_data.get(setup_cell_id)+ setup_cell = app1._cell_manager.cell_data_at(setup_cell_id)assert setup_cell is not Noneassert setup_cell.config.hide_code is False@@ -1575,7 +1576,7 @@ class TestAppComposition:with app2.setup():x2 = 1- setup_cell = app2._cell_manager._cell_data.get(setup_cell_id)+ setup_cell = app2._cell_manager.cell_data_at(setup_cell_id)assert setup_cell is not Noneassert setup_cell.config.hide_code is False@@ -1584,7 +1585,7 @@ class TestAppComposition:with app3.setup(hide_code=True):y = 2- setup_cell = app3._cell_manager._cell_data.get(setup_cell_id)+ setup_cell = app3._cell_manager.cell_data_at(setup_cell_id)assert setup_cell is not Noneassert setup_cell.config.hide_code is True@@ -1593,7 +1594,7 @@ class TestAppComposition:with app4.setup(hide_code=False):z = 3- setup_cell = app4._cell_manager._cell_data.get(setup_cell_id)+ setup_cell = app4._cell_manager.cell_data_at(setup_cell_id)assert setup_cell is not Noneassert setup_cell.config.hide_code is False@@ -1713,6 +1714,116 @@ class TestAppComposition:assert is_external_cell_id(setup_cell_ids[0])+class TestInternalAppWithData:+ """``InternalApp.with_data`` rewrites the cell list from the+ frontend's snapshot during the save round-trip. It must mutate the+ existing cell manager in place — Session holds+ ``app.cell_manager.document`` as a property, so swapping in a fresh+ manager would orphan ``session.document``.+ """++ def test_preserves_cell_manager_identity(self) -> None:+ app = App()++ @app.cell+ def _():+ x = 1+ return (x,)++ internal_app = InternalApp(app)+ cell_manager = internal_app.cell_manager+ cell_ids = list(cell_manager.cell_ids())+ codes = list(cell_manager.codes())+ names = list(cell_manager.names())+ configs = list(cell_manager.configs())++ internal_app.with_data(+ cell_ids=cell_ids,+ codes=[c + " # edited" for c in codes],+ names=names,+ configs=configs,+ )++ assert internal_app.cell_manager is cell_manager++ def test_preserves_document_identity(self) -> None:+ app = App()++ @app.cell+ def _():+ x = 1+ return (x,)++ internal_app = InternalApp(app)+ document = internal_app.cell_manager.document+ cell_ids = list(internal_app.cell_manager.cell_ids())+ codes = list(internal_app.cell_manager.codes())+ names = list(internal_app.cell_manager.names())+ configs = list(internal_app.cell_manager.configs())++ internal_app.with_data(+ cell_ids=cell_ids,+ codes=[c + " # edited" for c in codes],+ names=names,+ configs=configs,+ )++ assert internal_app.cell_manager.document is document++ def test_carries_compiled_cells_for_surviving_ids(self) -> None:+ app = App()++ @app.cell+ def _():+ x = 1+ return (x,)++ internal_app = InternalApp(app)+ cell_id = next(iter(internal_app.cell_manager.cell_ids()))+ original_compiled = internal_app.cell_manager._compiled_cells[+ cell_id+ ]+ assert original_compiled is not None++ internal_app.with_data(+ cell_ids=[cell_id],+ codes=["x = 2 # renamed-only-here"],+ names=["__"],+ configs=[CellConfig()],+ )++ # Same cell id survived, so the compiled sidecar is preserved.+ # (The save round-trip doesn't recompile; that happens in the+ # kernel after the save lands.)+ assert (+ internal_app.cell_manager._compiled_cells[cell_id]+ is original_compiled+ )++ def test_writes_new_codes_and_names(self) -> None:+ app = App()++ @app.cell+ def _():+ x = 1+ return (x,)++ internal_app = InternalApp(app)+ cell_id = next(iter(internal_app.cell_manager.cell_ids()))++ internal_app.with_data(+ cell_ids=[cell_id],+ codes=["x = 99"],+ names=["renamed"],+ configs=[CellConfig()],+ )++ cd = internal_app.cell_manager.get_cell_data(cell_id)+ assert cd is not None+ assert cd.code == "x = 99"+ assert cd.name == "renamed"++class TestInternalAppOverrides:"""Tests for InternalApp.overrides() method."""diff --git a/tests/_ast/test_cell_manager.py b/tests/_ast/test_cell_manager.pyindex f2f44ded0e..5d0bc5e0cc 100644--- a/tests/_ast/test_cell_manager.py+++ b/tests/_ast/test_cell_manager.py@@ -82,6 +82,23 @@ class TestCellManager:cell_id = next(iter(cell_manager.cell_ids()))assert cell_id.startswith("test_")+ def test_register_cell_records_explicit_id_in_seen_ids(+ self, cell_manager: CellManager+ ) -> None:+ # Externally-supplied ids (e.g. from frontend save round-trip /+ # InternalApp.with_data) must be tracked so subsequent+ # create_cell_id() calls don't produce a colliding id.+ explicit_id = CellId_t("test_external")+ cell_manager.register_cell(+ cell_id=explicit_id,+ code="x = 1",+ config=CellConfig(),+ )++ assert explicit_id in cell_manager.seen_ids+ for _ in range(50):+ assert cell_manager.create_cell_id() != explicit_id+def test_ensure_one_cell(self, cell_manager: CellManager) -> None:assert len(list(cell_manager.cell_ids())) == 0cell_manager.ensure_one_cell()@@ -625,3 +642,176 @@ class TestSortCellIdsBySimilarity:manager = CellManager()code_map = manager.code_map()assert code_map == {}+++class TestDocumentProperty:+ """``cell_manager.document`` exposes the underlying NotebookDocument+ that holds canonical cell state. Identity matters: ``Session.document``+ is a property that reads through this; consumers diff against the same+ instance over time.+ """++ def test_document_is_stable_across_mutations(self) -> None:+ cm = CellManager()+ doc = cm.document+ cm.register_cell(CELL_A, "x = 1", CellConfig())+ cm.register_cell(CELL_B, "y = 2", CellConfig())+ assert cm.document is doc++ def test_document_reflects_registered_cells(self) -> None:+ cm = CellManager()+ cm.register_cell(CELL_A, "x = 1", CellConfig())+ cm.register_cell(CELL_B, "y = 2", CellConfig())+ assert list(cm.document.cell_ids) == [CELL_A, CELL_B]+++class TestGetCellDataView:+ """``get_cell_data`` returns a freshly synthesized ``CellData`` view+ over the stored ``NotebookCell``. The view is read-only by convention:+ rebinding a field on the returned object must not leak back into the+ document, since callers commonly use it as a scratch struct.+ """++ def test_returns_fresh_instance_each_call(self) -> None:+ cm = CellManager()+ cm.register_cell(CELL_A, "x = 1", CellConfig())+ first = cm.get_cell_data(CELL_A)+ second = cm.get_cell_data(CELL_A)+ assert first is not None+ assert second is not None+ assert first is not second++ def test_rebinding_code_does_not_persist(self) -> None:+ cm = CellManager()+ cm.register_cell(CELL_A, "x = 1", CellConfig())+ view = cm.get_cell_data(CELL_A)+ assert view is not None+ view.code = "MUTATED"+ refreshed = cm.get_cell_data(CELL_A)+ assert refreshed is not None+ assert refreshed.code == "x = 1"++ def test_returns_none_for_missing_cell(self) -> None:+ cm = CellManager()+ assert cm.get_cell_data(CELL_A) is None+++class TestReplaceStateFrom:+ """``_replace_state_from`` is the in-place substitute for+ ``self = other``. It preserves identity of ``_document`` and+ ``_compiled_cells`` so external holders of those references — most+ notably the owning ``Session`` — see the new state without any+ rebinding.+ """++ def test_preserves_document_identity(self) -> None:+ cm = CellManager()+ cm.register_cell(CELL_A, "x = 1", CellConfig())+ doc = cm.document++ other = CellManager()+ other.register_cell(CELL_B, "y = 2", CellConfig())+ cm._replace_state_from(other)++ assert cm.document is doc++ def test_preserves_compiled_cells_dict_identity(self) -> None:+ cm = CellManager()+ cm.register_cell(CELL_A, "x = 1", CellConfig())+ compiled = cm._compiled_cells++ other = CellManager()+ other.register_cell(CELL_B, "y = 2", CellConfig())+ cm._replace_state_from(other)++ assert cm._compiled_cells is compiled++ def test_replaces_cell_list_contents(self) -> None:+ cm = CellManager()+ cm.register_cell(CELL_A, "x = 1", CellConfig())++ other = CellManager()+ other.register_cell(CELL_B, "y = 2", CellConfig())+ other.register_cell(CELL_C, "z = 3", CellConfig())+ cm._replace_state_from(other)++ assert list(cm.cell_ids()) == [CELL_B, CELL_C]+ assert cm.get_cell_code(CELL_A) is None++ def test_unions_seen_ids_no_narrowing(self) -> None:+ cm = CellManager()+ cm.seen_ids.add(CELL_A)+ # CELL_A is in cm.seen_ids; CELL_B is not.++ other = CellManager()+ other.seen_ids.add(CELL_B)+ # other.seen_ids has CELL_B but not CELL_A.++ cm._replace_state_from(other)++ # Union: both are remembered. Generating new ids later should+ # not collide because seen_ids guards against id reuse.+ assert CELL_A in cm.seen_ids+ assert CELL_B in cm.seen_ids++ def test_carries_unparsable_flag(self) -> None:+ cm = CellManager()+ assert cm.unparsable is False++ other = CellManager()+ other.unparsable = True+ cm._replace_state_from(other)++ assert cm.unparsable is True+++class TestSortCellIdsByCompiledCells:+ """``sort_cell_ids_by_similarity`` rekeys ``_compiled_cells`` in+ lockstep with the document's cell ids. This matters because lookups+ in ``cell_data()`` join the two by id; drift between them surfaces as+ "cell exists but has no compiled form" or vice versa.+ """++ def test_compiled_cells_dict_keys_track_new_ids(self) -> None:+ prev = CellManager()+ prev.register_cell(CELL_A, "x = 1", CellConfig())++ curr = CellManager()+ curr.register_cell(CELL_X, "x = 1", CellConfig())+ compiled_cell = Cell(+ _name="cell", _cell=compile_cell("x = 1", cell_id=CELL_X)+ )+ curr._compiled_cells[CELL_X] = compiled_cell++ curr.sort_cell_ids_by_similarity(prev)++ # CELL_X was rekeyed to CELL_A (matching code); the compiled+ # sidecar follows.+ assert list(curr.cell_ids()) == [CELL_A]+ assert curr._compiled_cells.get(CELL_A) is compiled_cell+ assert CELL_X not in curr._compiled_cells++ @pytest.mark.xfail(+ reason=(+ "Latent: the inner Cell._cell.cell_id is set at compile time "+ "and is not rekeyed when sort_cell_ids_by_similarity remaps "+ "the dict key. Tracked separately."+ ),+ strict=True,+ )+ def test_inner_cell_id_tracks_outer_key(self) -> None:+ prev = CellManager()+ prev.register_cell(CELL_A, "x = 1", CellConfig())++ curr = CellManager()+ curr.register_cell(CELL_X, "x = 1", CellConfig())+ curr._compiled_cells[CELL_X] = Cell(+ _name="cell", _cell=compile_cell("x = 1", cell_id=CELL_X)+ )++ curr.sort_cell_ids_by_similarity(prev)++ outer_id = next(iter(curr.cell_ids()))+ compiled = curr._compiled_cells[outer_id]+ assert compiled is not None+ assert compiled._cell.cell_id == outer_iddiff --git a/tests/_messaging/notebook/test_document.py b/tests/_messaging/notebook/test_document.pyindex ca48f67dd2..1e48677e38 100644--- a/tests/_messaging/notebook/test_document.py+++ b/tests/_messaging/notebook/test_document.py@@ -419,6 +419,22 @@ class TestVersion:assert doc.version == 1assert applied.version == 1+ def test_replace_cells_bumps_version(self) -> None:+ doc = _doc("a", "b")+ starting = doc.version+ doc._replace_cells([_cell("c"), _cell("d")])+ assert doc.version == starting + 1++ def test_replace_cells_preserves_document_identity(self) -> None:+ doc = _doc("a")+ new_cells = [_cell("b"), _cell("c")]+ doc._replace_cells(new_cells)+ assert _ids(doc) == ["b", "c"]+ # Reassigning the cells list — not mutating in place — lets prior+ # holders (e.g. file-watch diff path) keep a snapshot of the+ # pre-rebuild state for comparison.+ assert doc._cells is new_cells+# ------------------------------------------------------------------# Combined opsdiff --git a/tests/_session/test_file_change_handler.py b/tests/_session/test_file_change_handler.pyindex c902429e35..1ba7459922 100644--- a/tests/_session/test_file_change_handler.py+++ b/tests/_session/test_file_change_handler.py@@ -31,6 +31,7 @@ from marimo._session.file_change_handler import (EditModeReloadStrategy,FileChangeCoordinator,RunModeReloadStrategy,+ _build_reload_transaction,)from marimo._session.notebook import AppFileManagerfrom marimo._types.ids import CellId_t@@ -106,12 +107,18 @@ def _run_reload("""afm = _make_app(tmp_path, content)mock_session.app_file_manager = afm- mock_session.document = (- document if document is not None else NotebookDocument()- )+ prev_document = document if document is not None else NotebookDocument()+ mock_session.document = prev_documentstrategy = EditModeReloadStrategy(config_manager)cell_ids = list(afm.app.cell_manager.cell_ids())- strategy.handle_reload(mock_session, changed_cell_ids=set(cell_ids))+ transaction = _build_reload_transaction(+ prev_document, afm.app.cell_manager+ )+ strategy.handle_reload(+ mock_session,+ transaction=transaction,+ changed_cell_ids=set(cell_ids),+ )return afm, cell_ids@@ -228,13 +235,16 @@ def test_edit_mode_reload_with_deleted_cells(afm = _make_app(tmp_path, SINGLE_CELL_NOTEBOOK)mock_session.app_file_manager = afmcell_ids = list(afm.app.cell_manager.cell_ids())- mock_session.document = _make_document_with_extra_cell(- cell_ids, deleted_id- )+ prev_document = _make_document_with_extra_cell(cell_ids, deleted_id)+ mock_session.document = prev_documentstrategy = EditModeReloadStrategy(config)+ transaction = _build_reload_transaction(+ prev_document, afm.app.cell_manager+ )strategy.handle_reload(mock_session,+ transaction=transaction,changed_cell_ids=set(cell_ids) | {deleted_id},)@@ -516,7 +526,9 @@ def test_reload_detects_only_changed_cell_in_multi_cell(def test_run_mode_reload_strategy(mock_session: MagicMock) -> None:RunModeReloadStrategy().handle_reload(- mock_session, changed_cell_ids={CellId_t("cell1")}+ mock_session,+ transaction=Transaction(changes=(), source="file-watch"),+ changed_cell_ids={CellId_t("cell1")},)mock_session.notify.assert_called_once()assert isinstance(mock_session.notify.call_args[0][0], ReloadNotification)