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: add deserialize NotebookSerializer (#7925)

Myles Scolnick299659ddbfdd
diff --git a/marimo/_ast/load.py b/marimo/_ast/load.py
index 8d78143537..3518325144 100644
--- a/marimo/_ast/load.py
+++ b/marimo/_ast/load.py
@@ -11,14 +11,15 @@ from marimo import _loggers
from marimo._ast.app import App, InternalApp
from marimo._ast.parse import (
MarimoFileError,
+ NonMarimoPythonScriptError,
is_non_marimo_python_script,
- parse_notebook,
)
from marimo._schemas.serialization import (
CellDef,
NotebookSerialization,
UnparsableCell,
)
+from marimo._session.notebook.serializer import get_notebook_serializer
LOGGER = _loggers.marimo_logger()
@@ -83,25 +84,6 @@ def _dynamic_load(filename: str | Path) -> Optional[App]:
return app
-def _static_load(filepath: Path) -> Optional[App]:
- contents = _maybe_contents(filepath)
- if not contents:
- return None
-
- notebook = parse_notebook(contents, filepath=str(filepath))
-
- if notebook and is_non_marimo_python_script(notebook):
- # Should fail instead of overriding contents
- raise MarimoFileError(
- f"Python script {filepath} is not a marimo notebook."
- )
-
- if notebook is None or not notebook.valid:
- return None
-
- return load_notebook_ir(notebook, filepath=str(filepath))
-
-
def find_cell(filename: str, lineno: int) -> CellDef | None:
"""Find the cell at the given line number in the notebook.
@@ -157,16 +139,8 @@ def get_notebook_status(filename: str) -> LoadResult:
return LoadResult(status="empty", contents=contents)
notebook: Optional[NotebookSerialization] = None
- if path.suffix in (".md", ".qmd"):
- from marimo._convert.markdown.to_ir import (
- convert_from_md_to_marimo_ir,
- )
-
- notebook = convert_from_md_to_marimo_ir(contents)
- elif path.suffix == ".py":
- notebook = parse_notebook(contents, filepath=filename)
- else:
- raise MarimoFileError("File must end with .py, .md, or .qmd.")
+ handler = get_notebook_serializer(path)
+ notebook = handler.deserialize(contents, filepath=filename)
# NB. A invalid notebook can still be opened.
if notebook is None:
@@ -214,19 +188,27 @@ def load_app(filename: Optional[str | Path]) -> Optional[App]:
return None
path = Path(filename)
+ handler = get_notebook_serializer(path)
- if path.suffix in (".md", ".qmd"):
- contents = _maybe_contents(filename)
- if not contents:
- return None
- from marimo._convert.markdown.to_ir import convert_from_md_to_app
-
- return convert_from_md_to_app(contents) if contents else None
- elif not path.suffix == ".py":
- raise MarimoFileError("File must end with .py or .md")
+ contents = _maybe_contents(filename)
+ if not contents:
+ return None
try:
- return _static_load(path)
+ notebook_ir = handler.deserialize(contents, filepath=str(path))
+ if notebook_ir and is_non_marimo_python_script(notebook_ir):
+ # Should fail instead of overriding contents
+ raise NonMarimoPythonScriptError(
+ f"Python script {path} is not a marimo notebook."
+ )
+
+ if not notebook_ir.valid:
+ LOGGER.error(f"Notebook {path} is not a valid marimo notebook.")
+ return None
+
+ app = load_notebook_ir(notebook_ir)
+ app._cell_manager.ensure_one_cell()
+ return app
except MarimoFileError:
# Security advantages of static load are lost here, but reasonable
# fallback for now.
diff --git a/marimo/_ast/parse.py b/marimo/_ast/parse.py
index 6f6f83fd32..a5ca277211 100644
--- a/marimo/_ast/parse.py
+++ b/marimo/_ast/parse.py
@@ -96,6 +96,10 @@ class MarimoFileError(Exception):
pass
+class NonMarimoPythonScriptError(Exception):
+ pass
+
+
class Extractor:
"""Helper to extract AST nodes to schema/serialization ir."""
diff --git a/marimo/_convert/markdown/__init__.py b/marimo/_convert/markdown/__init__.py
index d45cad0294..b384c71496 100644
--- a/marimo/_convert/markdown/__init__.py
+++ b/marimo/_convert/markdown/__init__.py
@@ -10,7 +10,6 @@ from __future__ import annotations
from marimo._convert.markdown.from_ir import convert_from_ir_to_markdown
from marimo._convert.markdown.to_ir import (
- convert_from_md_to_app,
convert_from_md_to_marimo_ir,
extract_frontmatter,
formatted_code_block,
@@ -21,8 +20,7 @@ from marimo._convert.markdown.to_ir import (
__all__ = [
# Export (IR → Markdown)
"convert_from_ir_to_markdown",
- # Import (Markdown → IR/App)
- "convert_from_md_to_app",
+ # Import (Markdown → IR)
"convert_from_md_to_marimo_ir",
# Utilities
"extract_frontmatter",
diff --git a/marimo/_convert/markdown/to_ir.py b/marimo/_convert/markdown/to_ir.py
index aa6b8bbd00..509808ed87 100644
--- a/marimo/_convert/markdown/to_ir.py
+++ b/marimo/_convert/markdown/to_ir.py
@@ -10,7 +10,6 @@ from typing import (
Literal,
Optional,
TypeVar,
- Union,
cast,
)
@@ -32,9 +31,7 @@ from pymdownx.superfences import ( # type: ignore
)
from marimo import _loggers
-from marimo._ast.app import App, InternalApp
-from marimo._ast.cell import Cell, CellConfig
-from marimo._ast.compiler import compile_cell
+from marimo._ast.cell import CellConfig
from marimo._ast.names import DEFAULT_CELL_NAME
from marimo._convert.common.format import markdown_to_marimo, sql_to_marimo
from marimo._dependencies.dependencies import DependencyManager
@@ -50,7 +47,7 @@ LOGGER = _loggers.marimo_logger()
MARIMO_MD = "marimo-md"
MARIMO_CODE = "marimo-code"
-ConvertKeys = Union[Literal["marimo-ir"], Literal["marimo-app"]]
+ConvertKeys = Literal["marimo-ir"]
def backwards_compatible_sanitization(line: str) -> str:
@@ -197,42 +194,6 @@ class SafeWrap(Generic[T]):
return self.inner
-def _tree_to_app_obj(root: Element) -> SafeWrap[App]:
- app_config = app_config_from_root(root)
- app = InternalApp(App(**app_config))
-
- for child in root:
- name = child.get("name", DEFAULT_CELL_NAME)
- # Default to hiding markdown cells.
- cell_config = get_cell_config_from_tag(
- child, hide_code=child.tag == MARIMO_MD
- )
- source = get_source_from_tag(child)
-
- cell_id = app.cell_manager.create_cell_id()
- try:
- cell_impl = compile_cell(source, cell_id)
- cell_impl.configure(cell_config)
- cell = Cell(_name=name, _cell=cell_impl)
-
- app.cell_manager._register_cell(
- cell,
- app=app,
- )
- except SyntaxError:
- # Cannot use register_unparsable_cell, since there is an
- # expectation of a dedent and newlines.
- app.cell_manager.register_cell(
- cell_id=cell_id,
- code=source,
- config=cell_config,
- name=name or DEFAULT_CELL_NAME,
- cell=None,
- )
-
- return SafeWrap(app._app)
-
-
def _tree_to_ir(root: Element) -> SafeWrap[NotebookSerializationV1]:
app_config = app_config_from_root(root)
@@ -312,13 +273,12 @@ class MarimoMdParser(IdentityParser):
output_formats: dict[ConvertKeys, Callable[[Element], SafeWrap[Any]]] = { # type: ignore[assignment, misc]
"marimo-ir": _tree_to_ir,
- "marimo-app": _tree_to_app_obj,
}
def __init__(
self,
*args: Any,
- output_format: ConvertKeys,
+ output_format: ConvertKeys = "marimo-ir",
**kwargs: Any,
) -> None:
super().__init__(
@@ -518,22 +478,24 @@ class ExpandAndClassifyProcessor(BlockProcessor):
blocks.clear()
-def convert_from_md_to_app(text: str) -> App:
+def convert_from_md_to_marimo_ir(
+ text: str, filepath: Optional[str] = None
+) -> NotebookSerializationV1:
if not text.strip():
- app = App()
- else:
- app = cast(
- App, MarimoMdParser(output_format="marimo-app").convert(text)
+ return NotebookSerializationV1(
+ app=AppInstantiation(options={}), filename=filepath
)
-
- app._cell_manager.ensure_one_cell()
- return app
-
-
-def convert_from_md_to_marimo_ir(text: str) -> NotebookSerializationV1:
notebook = MarimoMdParser(output_format="marimo-ir").convert(text)
assert isinstance(notebook, NotebookSerializationV1)
- return notebook
+ return NotebookSerializationV1(
+ app=notebook.app,
+ filename=filepath,
+ cells=notebook.cells,
+ violations=notebook.violations,
+ valid=notebook.valid,
+ header=notebook.header,
+ version=notebook.version,
+ )
def extract_frontmatter(text: str) -> tuple[dict[str, str], str]:
diff --git a/marimo/_session/notebook/file_manager.py b/marimo/_session/notebook/file_manager.py
index 5e04b31d59..a2118eeabd 100644
--- a/marimo/_session/notebook/file_manager.py
+++ b/marimo/_session/notebook/file_manager.py
@@ -17,7 +17,7 @@ from marimo._runtime.layout.layout import (
)
from marimo._schemas.serialization import Header, NotebookSerializationV1
from marimo._server.app_defaults import AppDefaults
-from marimo._session.notebook.serializer import get_format_handler
+from marimo._session.notebook.serializer import get_notebook_serializer
from marimo._session.notebook.storage import (
FilesystemStorage,
StorageInterface,
@@ -179,7 +179,7 @@ class AppFileManager:
LOGGER.debug("Saving app to %s", path)
# Get the header in case it was modified by the user (e.g. package installation)
- handler = get_format_handler(path)
+ handler = get_notebook_serializer(path)
header: Optional[str] = None
if previous_path and previous_path.exists():
header = handler.extract_header(previous_path)
diff --git a/marimo/_session/notebook/serializer.py b/marimo/_session/notebook/serializer.py
index 8a4a2035fd..b5f35933f9 100644
--- a/marimo/_session/notebook/serializer.py
+++ b/marimo/_session/notebook/serializer.py
@@ -6,10 +6,10 @@ from __future__ import annotations
from pathlib import Path
from typing import Optional, Protocol
-from marimo._ast import codegen
-from marimo._convert.converters import MarimoConvert
-from marimo._convert.markdown import convert_from_ir_to_markdown
-from marimo._schemas.serialization import NotebookSerializationV1
+from marimo._schemas.serialization import (
+ AppInstantiation,
+ NotebookSerializationV1,
+)
class NotebookSerializer(Protocol):
@@ -28,6 +28,20 @@ class NotebookSerializer(Protocol):
"""
...
+ def deserialize(
+ self, content: str, filepath: Optional[str] = None
+ ) -> NotebookSerializationV1:
+ """Convert content string to notebook IR.
+
+ Args:
+ content: File content as string
+ filepath: Optional file path for error reporting
+
+ Returns:
+ Notebook in intermediate representation
+ """
+ ...
+
def extract_header(self, path: Path) -> Optional[str]:
"""Extract header/metadata from an existing file.
@@ -48,13 +62,26 @@ class PythonNotebookSerializer(NotebookSerializer):
Handles header preservation when converting from other formats.
"""
- contents = MarimoConvert.from_ir(notebook).to_py()
+ from marimo._ast.codegen import generate_filecontents_from_ir
- return contents
+ return generate_filecontents_from_ir(notebook)
+
+ def deserialize(
+ self, content: str, filepath: Optional[str] = None
+ ) -> NotebookSerializationV1:
+ """Deserialize Python notebook content to IR."""
+ from marimo._ast.parse import parse_notebook
+
+ notebook = parse_notebook(content, filepath=filepath or "<marimo>")
+ return notebook or NotebookSerializationV1(
+ app=AppInstantiation(options={}), filename=filepath
+ )
def extract_header(self, path: Path) -> Optional[str]:
"""Extract header comments from Python file."""
- return codegen.get_header_comments(path)
+ from marimo._ast.codegen import get_header_comments
+
+ return get_header_comments(path)
class MarkdownNotebookSerializer(NotebookSerializer):
@@ -62,8 +89,18 @@ class MarkdownNotebookSerializer(NotebookSerializer):
def serialize(self, notebook: NotebookSerializationV1) -> str:
"""Serialize notebook to Markdown format."""
+ from marimo._convert.markdown import convert_from_ir_to_markdown
+
return convert_from_ir_to_markdown(notebook)
+ def deserialize(
+ self, content: str, filepath: Optional[str] = None
+ ) -> NotebookSerializationV1:
+ """Deserialize Markdown notebook content to IR."""
+ from marimo._convert.markdown.to_ir import convert_from_md_to_marimo_ir
+
+ return convert_from_md_to_marimo_ir(content, filepath=filepath)
+
def extract_header(self, path: Path) -> Optional[str]:
"""Extract YAML frontmatter from Markdown file."""
from marimo._utils.inline_script_metadata import (
@@ -76,33 +113,33 @@ class MarkdownNotebookSerializer(NotebookSerializer):
# Default format handlers
-DEFAULT_FORMAT_HANDLERS = {
+DEFAULT_NOTEBOOK_SERIALIZERS = {
".py": PythonNotebookSerializer(),
".md": MarkdownNotebookSerializer(),
".qmd": MarkdownNotebookSerializer(),
}
-def get_format_handler(path: Path) -> NotebookSerializer:
- """Get the appropriate format handler for a file.
+def get_notebook_serializer(path: Path) -> NotebookSerializer:
+ """Get the appropriate notebook serializer for a file.
Args:
path: File path
Returns:
- Appropriate format handler
+ Appropriate notebook serializer
Raises:
- ValueError: If no handler supports the file format
+ ValueError: If no notebook serializer supports the file format
"""
# Ensure path is a Path object
if not isinstance(path, Path):
path = Path(path)
ext = path.suffix
- handler = DEFAULT_FORMAT_HANDLERS.get(ext)
+ handler = DEFAULT_NOTEBOOK_SERIALIZERS.get(ext)
if handler is None:
raise ValueError(
- f"No format handler found for {path}. Supported extensions: {list(DEFAULT_FORMAT_HANDLERS.keys())}"
+ f"No notebook serializer found for {path}. Supported extensions: {list(DEFAULT_NOTEBOOK_SERIALIZERS.keys())}"
)
return handler
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index 956d0d3836..7a1ac27afa 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -193,6 +193,9 @@ components:
title: AiModelConfig
type: object
AlertNotification:
+ description: "User-facing alert message.\n\n Attributes:\n title:\
+ \ Alert title.\n description: Alert body (may contain HTML).\n \
+ \ variant: Visual variant (e.g., \"danger\")."
properties:
description:
type: string
@@ -223,6 +226,10 @@ components:
title: AnthropicConfig
type: object
BannerNotification:
+ description: "Persistent banner message at top of notebook.\n\n Attributes:\n\
+ \ title: Banner title.\n description: Banner body (may contain\
+ \ HTML).\n variant: Visual variant (e.g., \"danger\").\n action:\
+ \ Optional user action (e.g., \"restart\")."
properties:
action:
anyOf:
@@ -288,7 +295,8 @@ components:
title: BedrockConfig
type: object
CacheClearedNotification:
- description: Result of clearing cache.
+ description: "Execution cache cleared result.\n\n Attributes:\n bytes_freed:\
+ \ Bytes freed by clearing cache."
properties:
bytes_freed:
type: integer
@@ -301,7 +309,10 @@ components:
title: CacheClearedNotification
type: object
CacheInfoNotification:
- description: Cache statistics information.
+ description: "Execution cache statistics.\n\n Attributes:\n hits:\
+ \ Cache hits.\n misses: Cache misses.\n time: Time spent on\
+ \ cache operations (seconds).\n disk_to_free: Disk space that could\
+ \ be freed (bytes).\n disk_total: Total disk space used (bytes)."
properties:
disk_to_free:
type: integer
@@ -356,14 +367,16 @@ components:
title: CellConfig
type: object
CellNotification:
- description: "Op to transition a cell.\n\n A CellNotification's data has\
- \ some optional fields:\n\n output - a CellOutput\n console \
- \ - a CellOutput (console msg to append), or a list of\n \
- \ CellOutputs\n status - execution status\n stale_inputs\
- \ - whether the cell has stale inputs (variables, modules, ...)\n run_id\
- \ - the run associated with this cell.\n serialization - the serialization\
- \ status of the cell\n\n Omitting a field means that its value should be\
- \ unchanged!\n\n And one required field:\n\n cell_id - the cell id"
+ description: "Updates a cell's state in the frontend.\n\n Only fields that\
+ \ are set (not None) will update the cell state.\n Omitting a field leaves\
+ \ that aspect unchanged.\n\n Attributes:\n cell_id: Unique identifier\
+ \ of the cell being updated.\n output: Cell's output. Use CellOutput.empty()\
+ \ to clear.\n console: Console messages. Single/list appends, [] clears,\
+ \ None unchanged.\n status: Execution status (idle/running/stale/queued/disabled-transitively).\n\
+ \ stale_inputs: Whether cell has stale inputs from changed dependencies.\n\
+ \ run_id: Execution run ID for tracing. Auto-set from context.\n \
+ \ serialization: Serialization status (TopLevelHints).\n timestamp:\
+ \ Creation timestamp, auto-set."
properties:
cell_id:
type: string
@@ -707,7 +720,7 @@ components:
title: ColumnStats
type: object
CompletedRunNotification:
- description: Written on run completion (of submitted cells and their descendants.
+ description: Run of submitted cells and descendants completed.
properties:
op:
enum:
@@ -775,7 +788,9 @@ components:
title: CompletionOption
type: object
CompletionResultNotification:
- description: Code completion result.
+ description: "Code completion result from language server.\n\n Attributes:\n\
+ \ completion_id: Request ID this responds to.\n prefix_length:\
+ \ Length of prefix to replace.\n options: Completion options to display."
properties:
completion_id:
type: string
@@ -880,7 +895,9 @@ components:
title: CycleError
type: object
DataColumnPreviewNotification:
- description: Preview of a column in a dataset.
+ description: "Data column preview with stats and visualization.\n\n Inherits\
+ \ all ColumnPreview attributes.\n\n Attributes:\n table_name: Table\
+ \ containing the column.\n column_name: Column being previewed."
properties:
chart_code:
anyOf:
@@ -964,6 +981,8 @@ components:
title: DataSourceConnection
type: object
DataSourceConnectionsNotification:
+ description: "Available data source connections for SQL cells.\n\n Attributes:\n\
+ \ connections: Available data source connections."
properties:
connections:
items:
@@ -1106,7 +1125,9 @@ components:
title: Database
type: object
DatasetsNotification:
- description: List of datasets.
+ description: "Available datasets for data explorer.\n\n Attributes:\n \
+ \ tables: Available data tables/datasets.\n clear_channel: If set,\
+ \ clears tables from this channel first."
properties:
clear_channel:
anyOf:
@@ -1760,6 +1781,8 @@ components:
title: FileUpdateResponse
type: object
FocusCellNotification:
+ description: "Focuses a cell (kiosk mode).\n\n Attributes:\n cell_id:\
+ \ Cell to focus."
properties:
cell_id:
type: string
@@ -1805,7 +1828,10 @@ components:
title: FormattingConfig
type: object
FunctionCallResultNotification:
- description: Result of calling a function.
+ description: "Result of a frontend-initiated function call.\n\n Attributes:\n\
+ \ function_call_id: ID matching the original request.\n return_value:\
+ \ Function return value as JSON.\n status: Human-readable success/failure\
+ \ status."
properties:
function_call_id:
type: string
@@ -1910,7 +1936,9 @@ components:
title: HTTPRequest
type: object
HumanReadableStatus:
- description: Human-readable status.
+ description: "Human-readable status for operation results.\n\n Attributes:\n\
+ \ code: Status code (\"ok\" or \"error\").\n title: Optional\
+ \ short title.\n message: Optional detailed description."
properties:
code:
enum:
@@ -1983,6 +2011,10 @@ components:
title: InstallPackagesRequest
type: object
InstallingPackageAlertNotification:
+ description: "Package installation progress with streaming logs.\n\n Attributes:\n\
+ \ packages: Package name to status (queued/installing/installed/failed).\n\
+ \ logs: Optional streaming logs per package.\n log_status: Log\
+ \ stream status (append/start/done)."
properties:
log_status:
anyOf:
@@ -2039,7 +2071,7 @@ components:
title: InstantiateNotebookRequest
type: object
InterruptedNotification:
- description: Written when the kernel is interrupted by the user.
+ description: Kernel was interrupted by user (SIGINT/Ctrl+C).
properties:
op:
enum:
@@ -2121,6 +2153,11 @@ components:
title: InvokeFunctionRequest
type: object
KernelCapabilitiesNotification:
+ description: "Kernel capabilities detected at startup.\n\n All fields auto-detected\
+ \ in __post_init__.\n\n Attributes:\n terminal: Terminal access\
+ \ (unavailable on Windows/Pyodide).\n pylsp: Python Language Server\
+ \ Protocol installed.\n ty: ty type checker installed.\n basedpyright:\
+ \ basedpyright type checker installed."
properties:
basedpyright:
default: false
@@ -2138,7 +2175,17 @@ components:
title: KernelCapabilitiesNotification
type: object
KernelReadyNotification:
- description: Kernel is ready for execution.
+ description: "Kernel ready for execution. First notification sent at startup.\n\
+ \n Attributes:\n cell_ids: Cell IDs in order.\n codes: Source\
+ \ code for each cell.\n names: Cell names/titles.\n layout:\
+ \ Notebook layout config.\n configs: Per-cell configuration.\n \
+ \ resumed: Whether resumed from previous session.\n ui_values: Previous\
+ \ UI element values if resumed.\n last_executed_code: Last executed\
+ \ code per cell if resumed.\n last_execution_time: Last execution time\
+ \ per cell if resumed.\n app_config: Application configuration.\n \
+ \ kiosk: Whether running in kiosk mode.\n capabilities: Available\
+ \ kernel capabilities.\n auto_instantiated: Whether cells already executed\
+ \ (run mode)."
properties:
app_config:
$ref: '#/components/schemas/_AppConfig'
@@ -2207,8 +2254,8 @@ components:
title: KernelReadyNotification
type: object
KernelStartupErrorNotification:
- description: Notification sent when kernel fails to start (e.g., sandbox build
- failure).
+ description: "Kernel failed to start.\n\n Attributes:\n error: Error\
+ \ message describing failure."
properties:
error:
type: string
@@ -2859,6 +2906,9 @@ components:
title: MarimoSyntaxError
type: object
MissingPackageAlertNotification:
+ description: "Alert for missing packages with install option.\n\n Attributes:\n\
+ \ packages: Missing package names.\n isolated: Whether in isolated\
+ \ environment."
properties:
isolated:
type: boolean
@@ -3142,6 +3192,8 @@ components:
title: PythonLanguageServerConfig
type: object
QueryParamsAppendNotification:
+ description: "Appends value to URL query parameter.\n\n Attributes:\n \
+ \ key: Query parameter key.\n value: Value to append."
properties:
key:
type: string
@@ -3157,6 +3209,7 @@ components:
title: QueryParamsAppendNotification
type: object
QueryParamsClearNotification:
+ description: Clears all URL query parameters.
properties:
op:
enum:
@@ -3166,6 +3219,9 @@ components:
title: QueryParamsClearNotification
type: object
QueryParamsDeleteNotification:
+ description: "Deletes URL query parameter values.\n\n Attributes:\n \
+ \ key: Query parameter key.\n value: Specific value to delete. If\
+ \ None, deletes all values for key."
properties:
key:
type: string
@@ -3183,7 +3239,8 @@ components:
title: QueryParamsDeleteNotification
type: object
QueryParamsSetNotification:
- description: Set query parameters.
+ description: "Sets URL query parameter, replacing existing values.\n\n Attributes:\n\
+ \ key: Query parameter key.\n value: Value(s) to set."
properties:
key:
type: string
@@ -3221,6 +3278,7 @@ components:
title: RecentFilesResponse
type: object
ReconnectedNotification:
+ description: WebSocket reconnection confirmed.
properties:
op:
enum:
@@ -3241,6 +3299,7 @@ components:
title: RefreshSecretsCommand
type: object
ReloadNotification:
+ description: Instructs frontend to reload the page.
properties:
op:
enum:
@@ -3263,7 +3322,9 @@ components:
title: RemovePackageRequest
type: object
RemoveUIElementsNotification:
- description: Invalidate UI elements for a given cell.
+ description: "Removes UI elements associated with a cell.\n\n Sent when cell\
+ \ is re-executed or deleted.\n\n Attributes:\n cell_id: Cell whose\
+ \ UI elements should be removed."
properties:
cell_id:
type: string
@@ -3399,7 +3460,9 @@ components:
title: RuntimeConfig
type: object
SQLMetadata:
- description: Metadata for a SQL database.
+ description: "SQL database and schema metadata.\n\n Attributes:\n \
+ \ connection: Connection identifier.\n database: Database name.\n \
+ \ schema: Schema name."
properties:
connection:
type: string
@@ -3418,7 +3481,9 @@ components:
title: SQLMetadata
type: object
SQLTableListPreviewNotification:
- description: Preview of a list of tables in a schema.
+ description: "List of SQL tables in a schema.\n\n Attributes:\n request_id:\
+ \ Request ID this responds to.\n metadata: Database and schema metadata.\n\
+ \ tables: Tables in schema.\n error: Error message if failed."
properties:
error:
anyOf:
@@ -3444,7 +3509,10 @@ components:
title: SQLTableListPreviewNotification
type: object
SQLTablePreviewNotification:
- description: Preview of a table in a SQL database.
+ description: "SQL table preview.\n\n Attributes:\n request_id: Request\
+ \ ID this responds to.\n metadata: Database and schema metadata.\n\
+ \ table: Table data (None if error).\n error: Error message\
+ \ if failed."
properties:
error:
anyOf:
@@ -3582,7 +3650,9 @@ components:
title: SchemaTable
type: object
SecretKeysResultNotification:
- description: Result of listing secret keys.
+ description: "Available secret keys from secret providers.\n\n Attributes:\n\
+ \ request_id: Request ID this responds to.\n secrets: Secret\
+ \ keys with provider info."
properties:
op:
enum:
@@ -3792,6 +3862,8 @@ components:
title: SqlParseResult
type: object
StartupLogsNotification:
+ description: "Streaming kernel startup logs.\n\n Attributes:\n content:\
+ \ Log content to display.\n status: Stream status (start/append/done)."
properties:
content:
type: string
@@ -3927,7 +3999,10 @@ components:
title: TyLanguageServerConfig
type: object
UIElementMessageNotification:
- description: Send a message to a UI element.
+ description: "Sends a message to a UI element/widget.\n\n Attributes:\n \
+ \ ui_element: UI element identifier (legacy).\n model_id: Widget\
+ \ model ID (newer architecture).\n message: Message payload as dictionary.\n\
+ \ buffers: Optional binary buffers for large data."
properties:
buffers:
anyOf:
@@ -3975,6 +4050,10 @@ components:
title: UnknownError
type: object
UpdateCellCodesNotification:
+ description: "Updates cell code contents (kiosk mode).\n\n Attributes:\n\
+ \ cell_ids: Cells to update.\n codes: New code for each cell.\n\
+ \ code_is_stale: If True, code was not executed on backend (output\
+ \ may not match)."
properties:
cell_ids:
items:
@@ -4025,12 +4104,8 @@ components:
title: UpdateCellConfigRequest
type: object
UpdateCellIdsNotification:
- description: 'Update the cell ID ordering of the cells in the notebook.
-
-
- Right now we send the entire list of cell IDs,
-
- but in the future we might want to send change-deltas.'
+ description: "Updates cell ordering in notebook.\n\n Attributes:\n \
+ \ cell_ids: Complete ordered list of cell IDs."
properties:
cell_ids:
items:
@@ -4284,6 +4359,10 @@ components:
title: ValidateSQLRequest
type: object
ValidateSQLResultNotification:
+ description: "SQL query validation result.\n\n Attributes:\n request_id:\
+ \ Request ID this responds to.\n parse_result: SQL parsing result.\n\
+ \ validate_result: Catalog validation result.\n error: Error\
+ \ message if failed."
properties:
error:
anyOf:
@@ -4324,6 +4403,9 @@ components:
title: VariableContext
type: object
VariableDeclarationNotification:
+ description: "Variable declaration and usage for dataflow graph.\n\n Attributes:\n\
+ \ name: Variable name.\n declared_by: Cell IDs that define this\
+ \ variable.\n used_by: Cell IDs that use this variable."
properties:
declared_by:
items:
@@ -4342,6 +4424,9 @@ components:
title: VariableDeclarationNotification
type: object
VariableValue:
+ description: "Variable value and type for variables panel.\n\n Attributes:\n\
+ \ name: Variable name.\n value: String representation of value.\n\
+ \ datatype: Data type as string."
properties:
datatype:
anyOf:
@@ -4360,7 +4445,8 @@ components:
title: VariableValue
type: object
VariableValuesNotification:
- description: List of variables and their types/values.
+ description: "Current variable values.\n\n Attributes:\n variables:\
+ \ Variables with current values and types."
properties:
op:
enum:
@@ -4375,7 +4461,8 @@ components:
title: VariableValuesNotification
type: object
VariablesNotification:
- description: List of variable declarations.
+ description: "Variable dataflow graph.\n\n Attributes:\n variables:\
+ \ Variable declarations and usage."
properties:
op:
enum:
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index eccd3a5452..1f7dc7661a 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -3095,7 +3095,15 @@ export interface components {
displayed_models: string[];
edit_model?: string;
};
- /** AlertNotification */
+ /**
+ * AlertNotification
+ * @description User-facing alert message.
+ *
+ * Attributes:
+ * title: Alert title.
+ * description: Alert body (may contain HTML).
+ * variant: Visual variant (e.g., "danger").
+ */
AlertNotification: {
description: string;
/** @enum {unknown} */
@@ -3115,7 +3123,16 @@ export interface components {
AnthropicConfig: {
api_key?: string;
};
- /** BannerNotification */
+ /**
+ * BannerNotification
+ * @description Persistent banner message at top of notebook.
+ *
+ * Attributes:
+ * title: Banner title.
+ * description: Banner body (may contain HTML).
+ * variant: Visual variant (e.g., "danger").
+ * action: Optional user action (e.g., "restart").
+ */
BannerNotification: {
/** @default null */
action?: "restart" | null;
@@ -3159,7 +3176,10 @@ export interface components {
};
/**
* CacheClearedNotification
- * @description Result of clearing cache.
+ * @description Execution cache cleared result.
+ *
+ * Attributes:
+ * bytes_freed: Bytes freed by clearing cache.
*/
CacheClearedNotification: {
bytes_freed: number;
@@ -3168,7 +3188,14 @@ export interface components {
};
/**
* CacheInfoNotification
- * @description Cache statistics information.
+ * @description Execution cache statistics.
+ *
+ * Attributes:
+ * hits: Cache hits.
+ * misses: Cache misses.
+ * time: Time spent on cache operations (seconds).
+ * disk_to_free: Disk space that could be freed (bytes).
+ * disk_total: Total disk space used (bytes).
*/
CacheInfoNotification: {
disk_to_free: number;
@@ -3207,23 +3234,20 @@ export interface components {
};
/**
* CellNotification
- * @description Op to transition a cell.
- *
- * A CellNotification's data has some optional fields:
- *
- * output - a CellOutput
- * console - a CellOutput (console msg to append), or a list of
- * CellOutputs
- * status - execution status
- * stale_inputs - whether the cell has stale inputs (variables, modules, ...)
- * run_id - the run associated with this cell.
- * serialization - the serialization status of the cell
+ * @description Updates a cell's state in the frontend.
*
- * Omitting a field means that its value should be unchanged!
+ * Only fields that are set (not None) will update the cell state.
+ * Omitting a field leaves that aspect unchanged.
*
- * And one required field:
- *
- * cell_id - the cell id
+ * Attributes:
+ * cell_id: Unique identifier of the cell being updated.
+ * output: Cell's output. Use CellOutput.empty() to clear.
+ * console: Console messages. Single/list appends, [] clears, None unchanged.
+ * status: Execution status (idle/running/stale/queued/disabled-transitively).
+ * stale_inputs: Whether cell has stale inputs from changed dependencies.
+ * run_id: Execution run ID for tracing. Auto-set from context.
+ * serialization: Serialization status (TopLevelHints).
+ * timestamp: Creation timestamp, auto-set.
*/
CellNotification: {
cell_id: string;
@@ -3409,7 +3433,7 @@ export interface components {
};
/**
* CompletedRunNotification
- * @description Written on run completion (of submitted cells and their descendants.
+ * @description Run of submitted cells and descendants completed.
*/
CompletedRunNotification: {
/** @enum {unknown} */
@@ -3447,7 +3471,12 @@ export interface components {
};
/**
* CompletionResultNotification
- * @description Code completion result.
+ * @description Code completion result from language server.
+ *
+ * Attributes:
+ * completion_id: Request ID this responds to.
+ * prefix_length: Length of prefix to replace.
+ * options: Completion options to display.
*/
CompletionResultNotification: {
completion_id: string;
@@ -3498,7 +3527,13 @@ export interface components {
};
/**
* DataColumnPreviewNotification
- * @description Preview of a column in a dataset.
+ * @description Data column preview with stats and visualization.
+ *
+ * Inherits all ColumnPreview attributes.
+ *
+ * Attributes:
+ * table_name: Table containing the column.
+ * column_name: Column being previewed.
*/
DataColumnPreviewNotification: {
/** @default null */
@@ -3540,7 +3575,13 @@ export interface components {
name: string;
source: string;
};
- /** DataSourceConnectionsNotification */
+ /**
+ * DataSourceConnectionsNotification
+ * @description Available data source connections for SQL cells.
+ *
+ * Attributes:
+ * connections: Available data source connections.
+ */
DataSourceConnectionsNotification: {
connections: components["schemas"]["DataSourceConnection"][];
/** @enum {unknown} */
@@ -3628,7 +3669,11 @@ export interface components {
};
/**
* DatasetsNotification
- * @description List of datasets.
+ * @description Available datasets for data explorer.
+ *
+ * Attributes:
+ * tables: Available data tables/datasets.
+ * clear_channel: If set, clears tables from this channel first.
*/
DatasetsNotification: {
/** @default null */
@@ -3985,7 +4030,13 @@ export interface components {
message?: string | null;
success: boolean;
};
- /** FocusCellNotification */
+ /**
+ * FocusCellNotification
+ * @description Focuses a cell (kiosk mode).
+ *
+ * Attributes:
+ * cell_id: Cell to focus.
+ */
FocusCellNotification: {
cell_id: string;
/** @enum {unknown} */
@@ -4017,7 +4068,12 @@ export interface components {
};
/**
* FunctionCallResultNotification
- * @description Result of calling a function.
+ * @description Result of a frontend-initiated function call.
+ *
+ * Attributes:
+ * function_call_id: ID matching the original request.
+ * return_value: Function return value as JSON.
+ * status: Human-readable success/failure status.
*/
FunctionCallResultNotification: {
function_call_id: string;
@@ -4101,7 +4157,12 @@ export interface components {
};
/**
* HumanReadableStatus
- * @description Human-readable status.
+ * @description Human-readable status for operation results.
+ *
+ * Attributes:
+ * code: Status code ("ok" or "error").
+ * title: Optional short title.
+ * message: Optional detailed description.
*/
HumanReadableStatus: {
/** @enum {unknown} */
@@ -4146,7 +4207,15 @@ export interface components {
[key: string]: string;
};
};
- /** InstallingPackageAlertNotification */
+ /**
+ * InstallingPackageAlertNotification
+ * @description Package installation progress with streaming logs.
+ *
+ * Attributes:
+ * packages: Package name to status (queued/installing/installed/failed).
+ * logs: Optional streaming logs per package.
+ * log_status: Log stream status (append/start/done).
+ */
InstallingPackageAlertNotification: {
/** @default null */
log_status?: ("append" | "done" | "start") | null;
@@ -4173,7 +4242,7 @@ export interface components {
};
/**
* InterruptedNotification
- * @description Written when the kernel is interrupted by the user.
+ * @description Kernel was interrupted by user (SIGINT/Ctrl+C).
*/
InterruptedNotification: {
/** @enum {unknown} */
@@ -4219,7 +4288,18 @@ export interface components {
functionName: string;
namespace: string;
};
- /** KernelCapabilitiesNotification */
+ /**
+ * KernelCapabilitiesNotification
+ * @description Kernel capabilities detected at startup.
+ *
+ * All fields auto-detected in __post_init__.
+ *
+ * Attributes:
+ * terminal: Terminal access (unavailable on Windows/Pyodide).
+ * pylsp: Python Language Server Protocol installed.
+ * ty: ty type checker installed.
+ * basedpyright: basedpyright type checker installed.
+ */
KernelCapabilitiesNotification: {
/** @default false */
basedpyright?: boolean;
@@ -4232,7 +4312,22 @@ export interface components {
};
/**
* KernelReadyNotification
- * @description Kernel is ready for execution.
+ * @description Kernel ready for execution. First notification sent at startup.
+ *
+ * Attributes:
+ * cell_ids: Cell IDs in order.
+ * codes: Source code for each cell.
+ * names: Cell names/titles.
+ * layout: Notebook layout config.
+ * configs: Per-cell configuration.
+ * resumed: Whether resumed from previous session.
+ * ui_values: Previous UI element values if resumed.
+ * last_executed_code: Last executed code per cell if resumed.
+ * last_execution_time: Last execution time per cell if resumed.
+ * app_config: Application configuration.
+ * kiosk: Whether running in kiosk mode.
+ * capabilities: Available kernel capabilities.
+ * auto_instantiated: Whether cells already executed (run mode).
*/
KernelReadyNotification: {
app_config: components["schemas"]["_AppConfig"];
@@ -4258,7 +4353,10 @@ export interface components {
};
/**
* KernelStartupErrorNotification
- * @description Notification sent when kernel fails to start (e.g., sandbox build failure).
+ * @description Kernel failed to start.
+ *
+ * Attributes:
+ * error: Error message describing failure.
*/
KernelStartupErrorNotification: {
error: string;
@@ -4610,7 +4708,14 @@ export interface components {
/** @enum {unknown} */
type: "syntax";
};
- /** MissingPackageAlertNotification */
+ /**
+ * MissingPackageAlertNotification
+ * @description Alert for missing packages with install option.
+ *
+ * Attributes:
+ * packages: Missing package names.
+ * isolated: Whether in isolated environment.
+ */
MissingPackageAlertNotification: {
isolated: boolean;
/** @enum {unknown} */
@@ -4784,19 +4889,36 @@ export interface components {
enable_ruff?: boolean;
enabled?: boolean;
};
- /** QueryParamsAppendNotification */
+ /**
+ * QueryParamsAppendNotification
+ * @description Appends value to URL query parameter.
+ *
+ * Attributes:
+ * key: Query parameter key.
+ * value: Value to append.
+ */
QueryParamsAppendNotification: {
key: string;
/** @enum {unknown} */
op: "query-params-append";
value: string;
};
- /** QueryParamsClearNotification */
+ /**
+ * QueryParamsClearNotification
+ * @description Clears all URL query parameters.
+ */
QueryParamsClearNotification: {
/** @enum {unknown} */
op: "query-params-clear";
};
- /** QueryParamsDeleteNotification */
+ /**
+ * QueryParamsDeleteNotification
+ * @description Deletes URL query parameter values.
+ *
+ * Attributes:
+ * key: Query parameter key.
+ * value: Specific value to delete. If None, deletes all values for key.
+ */
QueryParamsDeleteNotification: {
key: string;
/** @enum {unknown} */
@@ -4805,7 +4927,11 @@ export interface components {
};
/**
* QueryParamsSetNotification
- * @description Set query parameters.
+ * @description Sets URL query parameter, replacing existing values.
+ *
+ * Attributes:
+ * key: Query parameter key.
+ * value: Value(s) to set.
*/
QueryParamsSetNotification: {
key: string;
@@ -4821,7 +4947,10 @@ export interface components {
RecentFilesResponse: {
files: components["schemas"]["MarimoFile"][];
};
- /** ReconnectedNotification */
+ /**
+ * ReconnectedNotification
+ * @description WebSocket reconnection confirmed.
+ */
ReconnectedNotification: {
/** @enum {unknown} */
op: "reconnected";
@@ -4836,7 +4965,10 @@ export interface components {
/** @enum {unknown} */
type: "refresh-secrets";
};
- /** ReloadNotification */
+ /**
+ * ReloadNotification
+ * @description Instructs frontend to reload the page.
+ */
ReloadNotification: {
/** @enum {unknown} */
op: "reload";
@@ -4849,7 +4981,12 @@ export interface components {
};
/**
* RemoveUIElementsNotification
- * @description Invalidate UI elements for a given cell.
+ * @description Removes UI elements associated with a cell.
+ *
+ * Sent when cell is re-executed or deleted.
+ *
+ * Attributes:
+ * cell_id: Cell whose UI elements should be removed.
*/
RemoveUIElementsNotification: {
cell_id: string;
@@ -4946,7 +5083,12 @@ export interface components {
};
/**
* SQLMetadata
- * @description Metadata for a SQL database.
+ * @description SQL database and schema metadata.
+ *
+ * Attributes:
+ * connection: Connection identifier.
+ * database: Database name.
+ * schema: Schema name.
*/
SQLMetadata: {
connection: string;
@@ -4957,7 +5099,13 @@ export interface components {
};
/**
* SQLTableListPreviewNotification
- * @description Preview of a list of tables in a schema.
+ * @description List of SQL tables in a schema.
+ *
+ * Attributes:
+ * request_id: Request ID this responds to.
+ * metadata: Database and schema metadata.
+ * tables: Tables in schema.
+ * error: Error message if failed.
*/
SQLTableListPreviewNotification: {
/** @default null */
@@ -4971,7 +5119,13 @@ export interface components {
};
/**
* SQLTablePreviewNotification
- * @description Preview of a table in a SQL database.
+ * @description SQL table preview.
+ *
+ * Attributes:
+ * request_id: Request ID this responds to.
+ * metadata: Database and schema metadata.
+ * table: Table data (None if error).
+ * error: Error message if failed.
*/
SQLTablePreviewNotification: {
/** @default null */
@@ -5036,7 +5190,11 @@ export interface components {
};
/**
* SecretKeysResultNotification
- * @description Result of listing secret keys.
+ * @description Available secret keys from secret providers.
+ *
+ * Attributes:
+ * request_id: Request ID this responds to.
+ * secrets: Secret keys with provider info.
*/
SecretKeysResultNotification: {
/** @enum {unknown} */
@@ -5158,7 +5316,14 @@ export interface components {
errors: components["schemas"]["SqlParseError"][];
success: boolean;
};
- /** StartupLogsNotification */
+ /**
+ * StartupLogsNotification
+ * @description Streaming kernel startup logs.
+ *
+ * Attributes:
+ * content: Log content to display.
+ * status: Stream status (start/append/done).
+ */
StartupLogsNotification: {
content: string;
/** @enum {unknown} */
@@ -5242,7 +5407,13 @@ export interface components {
};
/**
* UIElementMessageNotification
- * @description Send a message to a UI element.
+ * @description Sends a message to a UI element/widget.
+ *
+ * Attributes:
+ * ui_element: UI element identifier (legacy).
+ * model_id: Widget model ID (newer architecture).
+ * message: Message payload as dictionary.
+ * buffers: Optional binary buffers for large data.
*/
UIElementMessageNotification: {
/** @default null */
@@ -5261,7 +5432,15 @@ export interface components {
/** @enum {unknown} */
type: "unknown";
};
- /** UpdateCellCodesNotification */
+ /**
+ * UpdateCellCodesNotification
+ * @description Updates cell code contents (kiosk mode).
+ *
+ * Attributes:
+ * cell_ids: Cells to update.
+ * codes: New code for each cell.
+ * code_is_stale: If True, code was not executed on backend (output may not match).
+ */
UpdateCellCodesNotification: {
cell_ids: string[];
code_is_stale: boolean;
@@ -5294,10 +5473,10 @@ export interface components {
};
/**
* UpdateCellIdsNotification
- * @description Update the cell ID ordering of the cells in the notebook.
+ * @description Updates cell ordering in notebook.
*
- * Right now we send the entire list of cell IDs,
- * but in the future we might want to send change-deltas.
+ * Attributes:
+ * cell_ids: Complete ordered list of cell IDs.
*/
UpdateCellIdsNotification: {
cell_ids: string[];
@@ -5455,7 +5634,16 @@ export interface components {
query: string;
requestId: string;
};
- /** ValidateSQLResultNotification */
+ /**
+ * ValidateSQLResultNotification
+ * @description SQL query validation result.
+ *
+ * Attributes:
+ * request_id: Request ID this responds to.
+ * parse_result: SQL parsing result.
+ * validate_result: Catalog validation result.
+ * error: Error message if failed.
+ */
ValidateSQLResultNotification: {
/** @default null */
error?: string | null;
@@ -5473,13 +5661,29 @@ export interface components {
previewValue: unknown;
valueType: string;
};
- /** VariableDeclarationNotification */
+ /**
+ * VariableDeclarationNotification
+ * @description Variable declaration and usage for dataflow graph.
+ *
+ * Attributes:
+ * name: Variable name.
+ * declared_by: Cell IDs that define this variable.
+ * used_by: Cell IDs that use this variable.
+ */
VariableDeclarationNotification: {
declared_by: string[];
name: string;
used_by: string[];
};
- /** VariableValue */
+ /**
+ * VariableValue
+ * @description Variable value and type for variables panel.
+ *
+ * Attributes:
+ * name: Variable name.
+ * value: String representation of value.
+ * datatype: Data type as string.
+ */
VariableValue: {
datatype: string | null;
name: string;
@@ -5487,7 +5691,10 @@ export interface components {
};
/**
* VariableValuesNotification
- * @description List of variables and their types/values.
+ * @description Current variable values.
+ *
+ * Attributes:
+ * variables: Variables with current values and types.
*/
VariableValuesNotification: {
/** @enum {unknown} */
@@ -5496,7 +5703,10 @@ export interface components {
};
/**
* VariablesNotification
- * @description List of variable declarations.
+ * @description Variable dataflow graph.
+ *
+ * Attributes:
+ * variables: Variable declarations and usage.
*/
VariablesNotification: {
/** @enum {unknown} */
diff --git a/tests/_ast/test_load.py b/tests/_ast/test_load.py
index dcc64ba15b..06bad56c5c 100644
--- a/tests/_ast/test_load.py
+++ b/tests/_ast/test_load.py
@@ -9,7 +9,7 @@ import pytest
from marimo import _loggers
from marimo._ast import load
-from marimo._ast.parse import MarimoFileError
+from marimo._ast.parse import MarimoFileError, NonMarimoPythonScriptError
DIR_PATH = os.path.dirname(os.path.realpath(__file__))
@@ -18,18 +18,62 @@ def get_filepath(name: str) -> str:
return os.path.join(DIR_PATH, f"codegen_data/{name}.py")
+def test_filename_propagation_python(tmp_path):
+ """Test that filename is propagated through Python deserialization."""
+ notebook_path = tmp_path / "test_notebook.py"
+ notebook_path.write_text(
+ """import marimo
+__generated_with = "0.1.0"
+app = marimo.App()
+
+def __():
+ x = 1
+ return x,
+""",
+ encoding="utf-8",
+ )
+
+ result = load.get_notebook_status(str(notebook_path))
+
+ assert result.notebook is not None
+ assert result.notebook.filename == str(notebook_path)
+
+
+def test_filename_propagation_markdown(tmp_path):
+ """Test that filename is propagated through Markdown deserialization."""
+ notebook_path = tmp_path / "test_notebook.md"
+ notebook_path.write_text(
+ """# Test Notebook
+
+```python {.marimo}
+x = 1
+```
+""",
+ encoding="utf-8",
+ )
+
+ result = load.get_notebook_status(str(notebook_path))
+
+ assert result.notebook is not None
+ assert result.notebook.filename == str(notebook_path)
+
+
@pytest.fixture
-def static_load():
- return load._static_load
+def unified_load():
+ """Uses the new unified load_app path with deserialization."""
+ return load.load_app
@pytest.fixture
def dynamic_load():
+ """Direct dynamic load for backward compatibility testing."""
return load._dynamic_load
[email protected](params=["static_load", "dynamic_load"])
[email protected](params=["unified_load", "dynamic_load"])
def load_app(request):
+ """Parametrized fixture to test both load paths."""
return request.getfixturevalue(request.param)
@@ -221,15 +265,17 @@ class TestGetCodes:
assert app is None
@staticmethod
- def test_get_codes_non_marimo_python_script(static_load) -> None:
- with pytest.raises(MarimoFileError, match="is not a marimo notebook."):
- static_load(
+ def test_get_codes_non_marimo_python_script() -> None:
+ with pytest.raises(
+ NonMarimoPythonScriptError, match="is not a marimo notebook."
+ ):
+ load.load_app(
get_filepath("test_get_codes_non_marimo_python_script")
)
@staticmethod
- def test_import_alias(static_load) -> None:
- app = static_load(get_filepath("test_get_alias_import"))
+ def test_import_alias() -> None:
+ app = load.load_app(get_filepath("test_get_alias_import"))
assert app is not None
cell_manager = app._cell_manager
assert list(cell_manager.names()) == ["one"]
@@ -283,16 +329,17 @@ class TestGetCodes:
# Don't worry about the discrepancy since dynamic_load should not be in
# prod.
- if load_app == load._static_load:
+ if load_app == load.load_app:
assert len(caplog.records) == 2
assert "fake_kwarg" in caplog.text
else:
+ # dynamic_load fallback
assert len(caplog.records) == 1
assert "kwarg_that_doesnt_exist" in caplog.text
@staticmethod
- def test_get_app_with_decorator(static_load) -> None:
- app = static_load(get_filepath("test_with_decorator"))
+ def test_get_app_with_decorator() -> None:
+ app = load.load_app(get_filepath("test_with_decorator"))
assert app is not None
assert app._cell_manager.get_cell_data_by_name("wrap").cell.defs == {
"wrap"
diff --git a/tests/_convert/markdown/test_markdown_conversion.py b/tests/_convert/markdown/test_markdown_conversion.py
index 275cdb5f9e..1491dd0b5c 100644
--- a/tests/_convert/markdown/test_markdown_conversion.py
+++ b/tests/_convert/markdown/test_markdown_conversion.py
@@ -10,8 +10,9 @@ import pytest
from marimo import __version__
from marimo._ast.app import InternalApp
+from marimo._ast.load import load_notebook_ir
from marimo._convert.converters import MarimoConvert
-from marimo._convert.markdown.to_ir import convert_from_md_to_app
+from marimo._convert.markdown.to_ir import convert_from_md_to_marimo_ir
# Just a handful of scripts to test
from marimo._tutorials import dataflow, for_jupyter_users, sql
@@ -101,7 +102,8 @@ def test_markdown_frontmatter() -> None:
snapshot("frontmatter-test.py.txt", output)
# As python object
- app = InternalApp(convert_from_md_to_app(script))
+ notebook_ir = convert_from_md_to_marimo_ir(script)
+ app = InternalApp(load_notebook_ir(notebook_ir))
assert app.config.app_title == "My Title"
ids = list(app.cell_manager.cell_ids())
assert len(ids) == 2
@@ -132,7 +134,8 @@ def test_no_frontmatter() -> None:
snapshot("no-frontmatter.py.txt", output)
# As python object
- app = InternalApp(convert_from_md_to_app(script))
+ notebook_ir = convert_from_md_to_marimo_ir(script)
+ app = InternalApp(load_notebook_ir(notebook_ir))
# TODO: Ideally extract notebook title.
# i.e. assert app.config.app_title == "My Notebook"
ids = list(app.cell_manager.cell_ids())
@@ -160,7 +163,9 @@ def test_markdown_just_frontmatter() -> None:
snapshot("frontmatter-only.py.txt", output)
# As python object
- app = InternalApp(convert_from_md_to_app(script))
+ notebook_ir = convert_from_md_to_marimo_ir(script)
+ app = InternalApp(load_notebook_ir(notebook_ir))
+ app.cell_manager.ensure_one_cell()
assert app.config.app_title == "My Title"
ids = list(app.cell_manager.cell_ids())
assert len(ids) == 1
@@ -200,7 +205,8 @@ def test_markdown_with_sql() -> None:
snapshot("sql-notebook.py.txt", output)
# As python object
- app = InternalApp(convert_from_md_to_app(script))
+ notebook_ir = convert_from_md_to_marimo_ir(script)
+ app = InternalApp(load_notebook_ir(notebook_ir))
assert app.config.app_title == "My Title"
ids = list(app.cell_manager.cell_ids())
assert len(ids) == 4
@@ -221,7 +227,9 @@ def test_markdown_empty() -> None:
assert md_to_py("") == ""
# As python object
- app = InternalApp(convert_from_md_to_app(""))
+ notebook_ir = convert_from_md_to_marimo_ir("")
+ app = InternalApp(load_notebook_ir(notebook_ir))
+ app.cell_manager.ensure_one_cell()
assert app.config.app_title is None
ids = list(app.cell_manager.cell_ids())
assert len(ids) == 1
diff --git a/tests/_session/notebook/test_serializer.py b/tests/_session/notebook/test_serializer.py
index 474579ca78..519dcaa451 100644
--- a/tests/_session/notebook/test_serializer.py
+++ b/tests/_session/notebook/test_serializer.py
@@ -14,10 +14,10 @@ from marimo._schemas.serialization import (
NotebookSerializationV1,
)
from marimo._session.notebook.serializer import (
- DEFAULT_FORMAT_HANDLERS,
+ DEFAULT_NOTEBOOK_SERIALIZERS,
MarkdownNotebookSerializer,
PythonNotebookSerializer,
- get_format_handler,
+ get_notebook_serializer,
)
@@ -102,6 +102,60 @@ class TestPythonNotebookSerializer:
assert "import marimo" in result
assert "x = 1" in result
+ def test_deserialize_basic(self) -> None:
+ """Test deserializing Python notebook content."""
+ serializer = PythonNotebookSerializer()
+ content = """import marimo
+
+__generated_with = "0.1.0"
+app = marimo.App()
+
+def __():
+ x = 1
+ return x,
+"""
+
+ result = serializer.deserialize(content)
+
+ assert result is not None
+ assert len(result.cells) == 1
+ assert "x = 1" in result.cells[0].code
+ # When no filepath is provided, defaults to "<marimo>"
+ assert result.filename == "<marimo>"
+
+ def test_deserialize_with_filepath(self) -> None:
+ """Test that filepath is propagated through deserialization."""
+ serializer = PythonNotebookSerializer()
+ content = """import marimo
+
+__generated_with = "0.1.0"
+app = marimo.App()
+
+def __():
+ x = 1
+ return x,
+"""
+ filepath = "/path/to/notebook.py"
+
+ result = serializer.deserialize(content, filepath=filepath)
+
+ assert result is not None
+ assert result.filename == filepath
+ assert len(result.cells) == 1
+
+ def test_deserialize_empty_content(self) -> None:
+ """Test deserializing empty content returns empty notebook with filepath."""
+ serializer = PythonNotebookSerializer()
+ filepath = "/path/to/empty.py"
+
+ result = serializer.deserialize("", filepath=filepath)
+
+ assert result is not None
+ assert result.filename == filepath
+ assert len(result.cells) == 0
+
class TestMarkdownNotebookSerializer:
def test_serialize_basic(self) -> None:
@@ -148,33 +202,100 @@ header: |
assert header is None or header == ""
+ def test_deserialize_basic(self) -> None:
+ """Test deserializing Markdown notebook content."""
+ serializer = MarkdownNotebookSerializer()
+ content = """# My Notebook
+
+```python {.marimo}
+x = 1
+```
+"""
+
+ result = serializer.deserialize(content)
+
+ assert result is not None
+ assert len(result.cells) == 2 # markdown cell + code cell
+ assert result.filename is None
+
+ def test_deserialize_with_filepath(self) -> None:
+ """Test that filepath is propagated through markdown deserialization."""
+ serializer = MarkdownNotebookSerializer()
+ content = """# My Notebook
+
+```python {.marimo}
+x = 1
+```
+"""
+ filepath = "/path/to/notebook.md"
+
+ result = serializer.deserialize(content, filepath=filepath)
+
+ assert result is not None
+ assert result.filename == filepath
+ assert len(result.cells) == 2
+
+ def test_deserialize_empty_content(self) -> None:
+ """Test deserializing empty markdown returns empty notebook with filepath."""
+ serializer = MarkdownNotebookSerializer()
+ filepath = "/path/to/empty.md"
+
+ result = serializer.deserialize("", filepath=filepath)
+
+ assert result is not None
+ assert result.filename == filepath
+ assert len(result.cells) == 0
+
+ def test_deserialize_with_frontmatter(self) -> None:
+ """Test deserializing markdown with frontmatter preserves filepath and metadata."""
+ serializer = MarkdownNotebookSerializer()
+ content = """---
+title: "Test Notebook"
+---
+
+# Content
+
+```python {.marimo}
+print("hello")
+```
+"""
+ filepath = "/path/to/notebook.md"
+
+ result = serializer.deserialize(content, filepath=filepath)
+
+ assert result is not None
+ assert result.filename == filepath
+ assert len(result.cells) == 2
+ # Frontmatter title is parsed and set in app options
+ assert result.app.options.get("app_title") == "Test Notebook"
+
class TestGetFormatHandler:
def test_get_python_handler(self, tmp_path: Path) -> None:
path = tmp_path / "notebook.py"
- handler = get_format_handler(path)
+ handler = get_notebook_serializer(path)
assert isinstance(handler, PythonNotebookSerializer)
def test_get_markdown_handler(self, tmp_path: Path) -> None:
path = tmp_path / "notebook.md"
- handler = get_format_handler(path)
+ handler = get_notebook_serializer(path)
assert isinstance(handler, MarkdownNotebookSerializer)
def test_get_qmd_handler(self, tmp_path: Path) -> None:
path = tmp_path / "notebook.qmd"
- handler = get_format_handler(path)
+ handler = get_notebook_serializer(path)
assert isinstance(handler, MarkdownNotebookSerializer)
def test_get_handler_with_string_path(self, tmp_path: Path) -> None:
path_str = str(tmp_path / "notebook.py")
- handler = get_format_handler(Path(path_str))
+ handler = get_notebook_serializer(Path(path_str))
assert isinstance(handler, PythonNotebookSerializer)
@@ -182,13 +303,74 @@ class TestGetFormatHandler:
path = tmp_path / "notebook.txt"
with pytest.raises(ValueError) as exc_info:
- get_format_handler(path)
+ get_notebook_serializer(path)
- assert "No format handler found" in str(exc_info.value)
+ assert "No notebook serializer found" in str(exc_info.value)
assert ".txt" in str(exc_info.value)
def test_default_handlers_registered(self) -> None:
- assert ".py" in DEFAULT_FORMAT_HANDLERS
- assert ".md" in DEFAULT_FORMAT_HANDLERS
- assert ".qmd" in DEFAULT_FORMAT_HANDLERS
- assert len(DEFAULT_FORMAT_HANDLERS) == 3
+ assert ".py" in DEFAULT_NOTEBOOK_SERIALIZERS
+ assert ".md" in DEFAULT_NOTEBOOK_SERIALIZERS
+ assert ".qmd" in DEFAULT_NOTEBOOK_SERIALIZERS
+
+
+class TestDeserializationWithFilenames:
+ """Test that filenames are propagated through the deserialization chain."""
+
+ def test_python_notebook_filepath_propagation(
+ self, tmp_path: Path
+ ) -> None:
+ """Test Python notebook filepath propagation through get_notebook_serializer."""
+ filepath = tmp_path / "test.py"
+ content = """import marimo
+__generated_with = "0.1.0"
+app = marimo.App()
+
+def __():
+ x = 1
+ return x,
+"""
+ filepath.write_text(content, encoding="utf-8")
+
+ handler = get_notebook_serializer(filepath)
+ result = handler.deserialize(content, filepath=str(filepath))
+
+ assert result.filename == str(filepath)
+ assert len(result.cells) == 1
+
+ def test_markdown_notebook_filepath_propagation(
+ self, tmp_path: Path
+ ) -> None:
+ """Test Markdown notebook filepath propagation through get_notebook_serializer."""
+ filepath = tmp_path / "test.md"
+ content = """# Test
+
+```python {.marimo}
+x = 1
+```
+"""
+ filepath.write_text(content, encoding="utf-8")
+
+ handler = get_notebook_serializer(filepath)
+ result = handler.deserialize(content, filepath=str(filepath))
+
+ assert result.filename == str(filepath)
+ assert len(result.cells) == 2
+
+ def test_qmd_notebook_filepath_propagation(self, tmp_path: Path) -> None:
+ """Test QMD notebook filepath propagation."""
+ filepath = tmp_path / "test.qmd"
+ content = """# Test
+
+```python {.marimo}
+x = 1
+```
+"""
+ filepath.write_text(content, encoding="utf-8")
+
+ handler = get_notebook_serializer(filepath)
+ result = handler.deserialize(content, filepath=str(filepath))
+
+ assert result.filename == str(filepath)
+ assert isinstance(handler, MarkdownNotebookSerializer)