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.

feat: generate islands from notebook IR (#9988)

Péter Gyarmati1a56d9329e11
diff --git a/marimo/_islands/_island_generator.py b/marimo/_islands/_island_generator.py
index 0938803f0b..37cfffb9a5 100644
--- a/marimo/_islands/_island_generator.py
+++ b/marimo/_islands/_island_generator.py
@@ -13,19 +13,24 @@ from marimo._ast.app import App, InternalApp
from marimo._ast.app_config import _AppConfig
from marimo._ast.cell import Cell, CellConfig
from marimo._ast.compiler import compile_cell
+from marimo._ast.load import load_notebook_ir
from marimo._messaging.cell_output import CellOutput
from marimo._output.utils import uri_encode_component
+from marimo._schemas.serialization import NotebookSerialization
from marimo._session.notebook import AppFileManager, load_notebook
from marimo._types.ids import CellId_t
+from marimo._utils.marimo_path import MarimoPath
from marimo._version import __version__
if sys.platform == "win32": # handling for windows
asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
if TYPE_CHECKING:
+ from marimo._ast.models import CellData
from marimo._session.state.session_view import SessionView
LOGGER = _loggers.marimo_logger()
+IN_MEMORY_FILENAME = "<marimo>.py"
class MarimoIslandStub:
@@ -255,6 +260,11 @@ class MarimoIslandGenerator:
# resolve to the notebook rather than to the host process.
self._source_filename: str | None = None
+ @property
+ def stubs(self) -> tuple[MarimoIslandStub, ...]:
+ """Return a snapshot of the generated per-cell island renderers."""
+ return tuple(self._stubs)
+
@staticmethod
def from_file(
filename: str,
@@ -290,6 +300,49 @@ class MarimoIslandGenerator:
return generator
+ @staticmethod
+ def _from_ir(
+ notebook: NotebookSerialization,
+ *,
+ app_id: str = "main",
+ filepath: str | None = None,
+ display_code: bool = False,
+ ) -> MarimoIslandGenerator:
+ """Create a generator from serialized marimo notebook data.
+
+ Args:
+ notebook: Serialized notebook IR.
+ app_id: App identifier written to rendered island DOM.
+ filepath: Source path used for `__file__` and `mo.notebook_dir()`.
+ display_code: Whether generated stubs render code by default.
+ """
+ ir_filepath = filepath if filepath is not None else notebook.filename
+ source_filename = _source_filename(ir_filepath)
+ app = load_notebook_ir(
+ notebook,
+ filepath=_load_filepath(source_filename or ir_filepath),
+ )
+
+ generator = MarimoIslandGenerator(app_id=app_id)
+ generator._source_filename = source_filename
+ internal_app = InternalApp(app)
+ generator._app = internal_app
+ generator._config = internal_app.config
+ cells = list(generator._app.cell_manager.cell_data())
+ disabled_cell_ids = _disabled_cell_ids(cells)
+ generator._stubs = [
+ MarimoIslandStub(
+ cell_id=data.cell_id,
+ app_id=generator._app_id,
+ code=data.code,
+ display_code=display_code,
+ is_reactive=data.cell_id not in disabled_cell_ids,
+ )
+ for data in cells
+ ]
+
+ return generator
+
def add_code(
self,
code: str,
@@ -597,3 +650,36 @@ class MarimoIslandGenerator:
def remove_empty_lines(text: str) -> str:
return "\n".join([line for line in text.split("\n") if line.strip() != ""])
+
+
+def _source_filename(filename: str | None) -> str | None:
+ if filename is None or filename == IN_MEMORY_FILENAME:
+ return None
+ return os.path.abspath(filename)
+
+
+def _load_filepath(filename: str | None) -> str:
+ if filename and MarimoPath.is_valid_path(filename):
+ return filename
+ return IN_MEMORY_FILENAME
+
+
+def _disabled_cell_ids(cell_data: list[CellData]) -> set[CellId_t]:
+ from marimo._runtime.dataflow.graph import DirectedGraph
+
+ disabled_cell_ids = {
+ data.cell_id for data in cell_data if data.cell is None
+ }
+ graph = DirectedGraph()
+
+ for data in cell_data:
+ cell = data.cell
+ if cell is not None:
+ graph.register_cell(data.cell_id, cell._cell)
+
+ for data in cell_data:
+ cell = data.cell
+ if cell is not None and graph.is_disabled(data.cell_id):
+ disabled_cell_ids.add(data.cell_id)
+
+ return disabled_cell_ids
diff --git a/tests/_islands/test_island_generator.py b/tests/_islands/test_island_generator.py
index cea31016de..c4ab31b411 100644
--- a/tests/_islands/test_island_generator.py
+++ b/tests/_islands/test_island_generator.py
@@ -1,6 +1,6 @@
from __future__ import annotations
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, get_type_hints
import pytest
@@ -9,6 +9,11 @@ from marimo._ast.app_config import _AppConfig
from marimo._islands._island_generator import (
MarimoIslandGenerator,
)
+from marimo._schemas.serialization import (
+ AppInstantiation,
+ CellDef,
+ NotebookSerialization,
+)
from tests.mocks import snapshotter
if TYPE_CHECKING:
@@ -17,6 +22,19 @@ if TYPE_CHECKING:
snapshot = snapshotter(__file__)
+def _notebook(
+ cells: list[CellDef],
+ *,
+ options: dict[str, object] | None = None,
+ filename: str | None = None,
+) -> NotebookSerialization:
+ return NotebookSerialization(
+ app=AppInstantiation(options=options or {}),
+ cells=cells,
+ filename=filename,
+ )
+
+
def test_add_code():
generator = MarimoIslandGenerator()
generator.add_code("print('Hello, World!')")
@@ -243,6 +261,235 @@ def __(mo):
assert str(other_dir / "nb.py") not in data
+async def test_from_ir_builds_notebook_serialization() -> None:
+ notebook = _notebook(
+ [
+ CellDef(code="import marimo as mo"),
+ CellDef(code='mo.md("# Hello, IR!")'),
+ ],
+ )
+
+ generator = MarimoIslandGenerator._from_ir(notebook, app_id="page-a")
+ stubs = generator.stubs
+
+ assert len(stubs) == 2
+ assert stubs[0].code == "import marimo as mo"
+ assert stubs[1].code == 'mo.md("# Hello, IR!")'
+ body_html = generator.render_body(include_init_island=False)
+ assert 'data-app-id="page-a"' in body_html
+ for cell_id in generator._app.cell_manager.cell_ids():
+ assert f'data-cell-id="{cell_id}"' in body_html
+
+ await generator.build()
+
+ stub = generator.stubs[1]
+ assert stub.output is not None
+ assert "Hello, IR!" in stub.output.data
+
+
+def test_stubs_returns_read_only_snapshot() -> None:
+ generator = MarimoIslandGenerator()
+ generator.add_code("x = 1")
+
+ stubs = generator.stubs
+ assert len(stubs) == 1
+ assert stubs[0].code == "x = 1"
+
+ generator.add_code("y = 2")
+ assert len(stubs) == 1
+ assert len(generator.stubs) == 2
+
+
+def test_from_ir_type_hints_resolve() -> None:
+ hints = get_type_hints(MarimoIslandGenerator._from_ir)
+
+ assert hints["notebook"] is NotebookSerialization
+ assert hints["return"] is MarimoIslandGenerator
+
+
+def test_from_ir_applies_display_code_to_stubs() -> None:
+ notebook = _notebook([CellDef(code="x = 1")])
+
+ generator = MarimoIslandGenerator._from_ir(
+ notebook,
+ display_code=True,
+ )
+
+ html = generator.stubs[0].render()
+ assert "<marimo-cell-code hidden>" not in html
+ assert "x = 1" in html
+
+
+def test_from_ir_preserves_app_config() -> None:
+ notebook = _notebook(
+ [],
+ options={"width": "medium", "app_title": "IR App"},
+ )
+
+ generator = MarimoIslandGenerator._from_ir(notebook)
+
+ body_html = generator.render_body()
+ assert 'style="margin: auto; max-width: 1110px;"' in body_html
+
+ html = generator.render_html()
+ assert "<title> IR App </title>" in html
+
+
+def test_from_ir_sanitizes_markdown_app_config() -> None:
+ notebook = _notebook(
+ [],
+ options={"width": "medium", "author": "Marimo"},
+ filename="notebook.md",
+ )
+
+ generator = MarimoIslandGenerator._from_ir(notebook)
+
+ body_html = generator.render_body()
+ assert 'style="margin: auto; max-width: 1110px;"' in body_html
+
+
+async def test_from_ir_propagates_ir_filename_to_cells(tmp_path: Path) -> None:
+ notebook_file = tmp_path / "nb.py"
+ notebook_file.write_text("")
+ notebook = _notebook(
+ [
+ CellDef(code="import marimo as mo"),
+ CellDef(
+ code=('mo.md(f"FILE={__file__} | DIR={mo.notebook_dir()}")')
+ ),
+ ],
+ filename=str(notebook_file),
+ )
+
+ generator = MarimoIslandGenerator._from_ir(notebook)
+ await generator.build()
+
+ captured = generator.stubs[1].output
+ assert captured is not None
+ data = captured.data
+ assert str(notebook_file) in data, (
+ f"expected __file__ to resolve to {notebook_file}, got: {data}"
+ )
+ assert str(notebook_file.parent) in data, (
+ f"expected notebook_dir() to resolve to {notebook_file.parent}, "
+ f"got: {data}"
+ )
+
+
+async def test_from_ir_resolves_relative_path_at_capture_time(
+ tmp_path: Path,
+) -> None:
+ import os
+
+ notebook_dir = tmp_path / "notebooks"
+ notebook_dir.mkdir()
+ notebook_file = notebook_dir / "nb.py"
+ notebook_file.write_text("")
+ notebook = _notebook(
+ [
+ CellDef(code="import marimo as mo"),
+ CellDef(code='mo.md(f"FILE={__file__}")'),
+ ],
+ )
+ other_dir = tmp_path / "elsewhere"
+ other_dir.mkdir()
+
+ original_cwd = os.getcwd()
+ try:
+ os.chdir(notebook_dir)
+ generator = MarimoIslandGenerator._from_ir(notebook, filepath="nb.py")
+ os.chdir(other_dir)
+ await generator.build()
+ finally:
+ os.chdir(original_cwd)
+
+ captured = generator.stubs[1].output
+ assert captured is not None
+ data = captured.data
+ assert str(notebook_file) in data, (
+ f"expected __file__ to resolve to {notebook_file}, got: {data}"
+ )
+ assert str(other_dir / "nb.py") not in data
+
+
+async def test_from_ir_filepath_overrides_ir_filename(
+ tmp_path: Path,
+) -> None:
+ ir_file = tmp_path / "ir.py"
+ source_file = tmp_path / "source.ipynb"
+ ir_file.write_text("")
+ source_file.write_text("")
+ notebook = _notebook(
+ [
+ CellDef(code="import marimo as mo"),
+ CellDef(
+ code=('mo.md(f"FILE={__file__} | DIR={mo.notebook_dir()}")')
+ ),
+ ],
+ filename=str(ir_file),
+ )
+
+ generator = MarimoIslandGenerator._from_ir(
+ notebook, filepath=str(source_file)
+ )
+ await generator.build()
+
+ captured = generator.stubs[1].output
+ assert captured is not None
+ data = captured.data
+ assert str(source_file) in data, (
+ f"expected __file__ to resolve to {source_file}, got: {data}"
+ )
+ assert str(source_file.parent) in data, (
+ f"expected notebook_dir() to resolve to {source_file.parent}, "
+ f"got: {data}"
+ )
+ assert str(ir_file) not in data
+
+
+async def test_from_ir_preserves_disabled_cell_config() -> None:
+ notebook = _notebook(
+ [
+ CellDef(code="'disabled output'", options={"disabled": True}),
+ CellDef(code="'active output'"),
+ ],
+ )
+
+ generator = MarimoIslandGenerator._from_ir(notebook)
+
+ body_html = generator.render_body(include_init_island=False)
+ assert 'data-reactive="false"' in body_html
+ assert 'data-reactive="true"' in body_html
+
+ await generator.build()
+
+ disabled_stub = generator.stubs[0]
+ active_stub = generator.stubs[1]
+ assert disabled_stub.output is None
+ assert active_stub.output is not None
+ assert "active output" in active_stub.output.data
+
+
+async def test_from_ir_marks_transitively_disabled_cells_static() -> None:
+ notebook = _notebook(
+ [
+ CellDef(code="x = 1", options={"disabled": True}),
+ CellDef(code="x + 1"),
+ ],
+ )
+
+ generator = MarimoIslandGenerator._from_ir(notebook)
+
+ rendered = [stub.render() for stub in generator.stubs]
+ assert all('data-reactive="false"' in html for html in rendered)
+ assert "x%20%2B%201" not in rendered[1]
+
+ await generator.build()
+
+ assert generator.stubs[0].output is None
+ assert generator.stubs[1].output is None
+
+
def test_render_head():
generator = MarimoIslandGenerator()
head_html = generator.render_head()