A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
refactor: add deserialize NotebookSerializer (#7925)
Myles Scolnick299659ddbfdd
diff --git a/marimo/_ast/load.py b/marimo/_ast/load.pyindex 8d78143537..3518325144 100644--- a/marimo/_ast/load.py+++ b/marimo/_ast/load.py@@ -11,14 +11,15 @@ from marimo import _loggersfrom marimo._ast.app import App, InternalAppfrom 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_serializerLOGGER = _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 Nonepath = 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 Nonetry:- 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 appexcept 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.pyindex 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__.pyindex d45cad0294..b384c71496 100644--- a/marimo/_convert/markdown/__init__.py+++ b/marimo/_convert/markdown/__init__.py@@ -10,7 +10,6 @@ from __future__ import annotationsfrom marimo._convert.markdown.from_ir import convert_from_ir_to_markdownfrom 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.pyindex 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 CellConfigfrom marimo._ast.names import DEFAULT_CELL_NAMEfrom marimo._convert.common.format import markdown_to_marimo, sql_to_marimofrom 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.pyindex 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, NotebookSerializationV1from marimo._server.app_defaults import AppDefaults-from marimo._session.notebook.serializer import get_format_handler+from marimo._session.notebook.serializer import get_notebook_serializerfrom 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] = Noneif 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.pyindex 8a4a2035fd..b5f35933f9 100644--- a/marimo/_session/notebook/serializer.py+++ b/marimo/_session/notebook/serializer.py@@ -6,10 +6,10 @@ from __future__ import annotationsfrom pathlib import Pathfrom 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 pathReturns:- Appropriate format handler+ Appropriate notebook serializerRaises:- ValueError: If no handler supports the file format+ ValueError: If no notebook serializer supports the file format"""# Ensure path is a Path objectif 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 handlerdiff --git a/packages/openapi/api.yaml b/packages/openapi/api.yamlindex 956d0d3836..7a1ac27afa 100644--- a/packages/openapi/api.yaml+++ b/packages/openapi/api.yaml@@ -193,6 +193,9 @@ components:title: AiModelConfigtype: objectAlertNotification:+ 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: AnthropicConfigtype: objectBannerNotification:+ 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: BedrockConfigtype: objectCacheClearedNotification:- 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: CacheClearedNotificationtype: objectCacheInfoNotification:- 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: CellConfigtype: objectCellNotification:- 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: ColumnStatstype: objectCompletedRunNotification:- 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: CompletionOptiontype: objectCompletionResultNotification:- 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: CycleErrortype: objectDataColumnPreviewNotification:- 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: DataSourceConnectiontype: objectDataSourceConnectionsNotification:+ 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: Databasetype: objectDatasetsNotification:- 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: FileUpdateResponsetype: objectFocusCellNotification:+ 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: FormattingConfigtype: objectFunctionCallResultNotification:- 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: HTTPRequesttype: objectHumanReadableStatus:- 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: InstallPackagesRequesttype: objectInstallingPackageAlertNotification:+ 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: InstantiateNotebookRequesttype: objectInterruptedNotification:- 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: InvokeFunctionRequesttype: objectKernelCapabilitiesNotification:+ 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: KernelCapabilitiesNotificationtype: objectKernelReadyNotification:- 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: KernelReadyNotificationtype: objectKernelStartupErrorNotification:- 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: MarimoSyntaxErrortype: objectMissingPackageAlertNotification:+ 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: PythonLanguageServerConfigtype: objectQueryParamsAppendNotification:+ 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: QueryParamsAppendNotificationtype: objectQueryParamsClearNotification:+ description: Clears all URL query parameters.properties:op:enum:@@ -3166,6 +3219,9 @@ components:title: QueryParamsClearNotificationtype: objectQueryParamsDeleteNotification:+ 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: QueryParamsDeleteNotificationtype: objectQueryParamsSetNotification:- 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: RecentFilesResponsetype: objectReconnectedNotification:+ description: WebSocket reconnection confirmed.properties:op:enum:@@ -3241,6 +3299,7 @@ components:title: RefreshSecretsCommandtype: objectReloadNotification:+ description: Instructs frontend to reload the page.properties:op:enum:@@ -3263,7 +3322,9 @@ components:title: RemovePackageRequesttype: objectRemoveUIElementsNotification:- 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: RuntimeConfigtype: objectSQLMetadata:- 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: SQLMetadatatype: objectSQLTableListPreviewNotification:- 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: SQLTableListPreviewNotificationtype: objectSQLTablePreviewNotification:- 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: SchemaTabletype: objectSecretKeysResultNotification:- 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: SqlParseResulttype: objectStartupLogsNotification:+ 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: TyLanguageServerConfigtype: objectUIElementMessageNotification:- 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: UnknownErrortype: objectUpdateCellCodesNotification:+ 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: UpdateCellConfigRequesttype: objectUpdateCellIdsNotification:- 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: ValidateSQLRequesttype: objectValidateSQLResultNotification:+ 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: VariableContexttype: objectVariableDeclarationNotification:+ 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: VariableDeclarationNotificationtype: objectVariableValue:+ 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: VariableValuetype: objectVariableValuesNotification:- 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: VariableValuesNotificationtype: objectVariablesNotification:- 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.tsindex 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.pyindex dcc64ba15b..06bad56c5c 100644--- a/tests/_ast/test_load.py+++ b/tests/_ast/test_load.py@@ -9,7 +9,7 @@ import pytestfrom marimo import _loggersfrom marimo._ast import load-from marimo._ast.parse import MarimoFileError+from marimo._ast.parse import MarimoFileError, NonMarimoPythonScriptErrorDIR_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.fixturedef 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 Nonecell_manager = app._cell_managerassert 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) == 2assert "fake_kwarg" in caplog.textelse:+ # dynamic_load fallbackassert len(caplog.records) == 1assert "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 Noneassert 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.pyindex 275cdb5f9e..1491dd0b5c 100644--- a/tests/_convert/markdown/test_markdown_conversion.py+++ b/tests/_convert/markdown/test_markdown_conversion.py@@ -10,8 +10,9 @@ import pytestfrom marimo import __version__from marimo._ast.app import InternalApp+from marimo._ast.load import load_notebook_irfrom 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 testfrom 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 Noneids = list(app.cell_manager.cell_ids())assert len(ids) == 1diff --git a/tests/_session/notebook/test_serializer.py b/tests/_session/notebook/test_serializer.pyindex 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 resultassert "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)