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.

refactor: consolidate `CellManager` and `NotebookDocument` (#9405)

Kiran Gadhave981b3e686043
diff --git a/marimo/_ast/app.py b/marimo/_ast/app.py
index 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 self
async 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.py
index 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 _loggers
from marimo._ast.cell import Cell, CellConfig
from marimo._ast.cell_id import CellIdGenerator
@@ -23,6 +25,7 @@ from marimo._ast.models import CellData
from marimo._ast.names import DEFAULT_CELL_NAME, SETUP_CELL_NAME
from marimo._ast.parse import fixed_dedent
from marimo._ast.pytest import process_for_pytest
+from marimo._messaging.notebook.document import NotebookCell, NotebookDocument
from 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 = prefix
self.unparsable = False
self._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] = cell
def 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_id
else:
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).name
def 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.name
def 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.code
def 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.config
def 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.id
def 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_ids
def 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._document
def 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.code
def 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 None
def 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.id
return 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 ids
id_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 future
for _id in id_mapping:
diff --git a/marimo/_messaging/notebook/document.py b/marimo/_messaging/notebook/document.py
index 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.py
index 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.py
index 366c95b109..08573ae13a 100644
--- a/marimo/_session/file_change_handler.py
+++ b/marimo/_session/file_change_handler.py
@@ -10,6 +10,8 @@ import asyncio
from dataclasses import dataclass
from typing import TYPE_CHECKING, Protocol
+from msgspec.structs import replace as structs_replace
+
from marimo import _loggers
from marimo._config.manager import MarimoConfigManager
from 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 NotebookDocument
from 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_manager
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 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_ids
session.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 code
try:
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 strategy
self._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_ids
diff --git a/marimo/_session/session.py b/marimo/_session/session.py
index 87d02ef40e..6e4a88992d 100644
--- a/marimo/_session/session.py
+++ b/marimo/_session/session.py
@@ -15,7 +15,7 @@ from uuid import uuid4
from marimo import _loggers
from marimo._cli.sandbox import SandboxMode
from marimo._config.manager import MarimoConfigManager, ScriptConfigManager
-from marimo._messaging.notebook.document import NotebookCell, NotebookDocument
+from marimo._messaging.notebook.document import NotebookDocument
from marimo._messaging.notification import (
NotificationMessage,
)
@@ -65,7 +65,6 @@ from marimo._utils.repr import format_repr
if TYPE_CHECKING:
from collections.abc import Iterator, Mapping
- from marimo._ast.cell_manager import CellManager
from marimo._runtime.virtual_file import VirtualFileStorageType
from marimo._server.models.models import InstantiateNotebookRequest
from 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_manager
self.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.py
index cf3e5f60f1..6df5b36490 100644
--- a/marimo/_session/types.py
+++ b/marimo/_session/types.py
@@ -110,11 +110,15 @@ class Session(Protocol):
initialization_id: str
app_file_manager: AppFileManager
config_manager: MarimoConfigManager
- document: NotebookDocument
session_view: SessionView
ttl_seconds: int
scratchpad_lock: asyncio.Lock
+ @property
+ def document(self) -> NotebookDocument:
+ """The notebook document this session reflects."""
+ ...
+
@property
def consumers(self) -> Mapping[SessionConsumer, ConsumerId]:
"""Get the consumers in the session."""
diff --git a/tests/_ast/test_app.py b/tests/_ast/test_app.py
index 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 CellConfig
from marimo._ast.cell_id import is_external_cell_id
from 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
+ ).cell
assert original_cell is not None
assert 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 None
assert 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 None
assert 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 None
assert 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 None
assert 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.py
index 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())) == 0
cell_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_id
diff --git a/tests/_messaging/notebook/test_document.py b/tests/_messaging/notebook/test_document.py
index 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 == 1
assert 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 ops
diff --git a/tests/_session/test_file_change_handler.py b/tests/_session/test_file_change_handler.py
index 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 AppFileManager
from 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_document
strategy = 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 = afm
cell_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_document
strategy = 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)