Handle parsing errors

Author: manzt

foo.py

@@ -0,0 +1,12 @@
+# /// script
+# requires-python = ">=3.13"
+# dependencies = []
+# ///
+
+
+def main() -> None:
+    print("Hello from foo.py!")
+
+
+if __name__ == "__main__":
+    main()

marimo/_ast/load.py

@@ -10,6 +10,7 @@
 from marimo._ast.app import App, InternalApp
 from marimo._ast.parse import (
     MarimoFileError,
+    is_non_marimo_python_script,
     parse_notebook,
 )
 from marimo._schemas.serialization import NotebookSerialization, UnparsableCell
@@ -67,9 +68,16 @@ def _static_load(filepath: Path) -> Optional[App]:
     contents = _maybe_contents(filepath)
     if not contents:
         return None
+
     notebook = parse_notebook(contents)
+
+    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
+
     app = App(**notebook.app.options, _filename=str(filepath))
     for cell in notebook.cells:
         if isinstance(cell, UnparsableCell):
@@ -90,7 +98,6 @@ def get_notebook_status(filename: str) -> NotebookStatus:
 
     Raises:
         SyntaxError: If the file contains a syntax error
-        UnknownPythonScriptError: If the file is an unrecognized Python script format
     """
     path = Path(filename)
 
@@ -153,8 +160,7 @@ def load_app(filename: Optional[str]) -> Optional[App]:
         from marimo._convert.markdown.markdown import convert_from_md_to_app
 
         return convert_from_md_to_app(contents) if contents else None
-
-    if not path.suffix == ".py":
+    elif not path.suffix == ".py":
         raise MarimoFileError("File must end with .py or .md")
 
     try:

marimo/_ast/parse.py

@@ -841,10 +841,10 @@ def parse_notebook(contents: str) -> Optional[NotebookSerialization]:
 
         remaining = parser.extractor.contents[len(header.value) :]
         if len(remaining.strip()) != 0:
+            # just a header is fine, anything else we would ignore and override
             violations.append(
-                # TODO: Could be more specific if we have violation nums
                 Violation(
-                    _unknown_content_violation_description,
+                    _non_marimo_python_script_violation_description,
                     lineno=header.end_lineno + 2 if header.value else 1,
                 )
             )
@@ -906,11 +906,13 @@ def parse_notebook(contents: str) -> Optional[NotebookSerialization]:
     )
 
 
-_unknown_content_violation_description = "Unknown content beyond header"
+_non_marimo_python_script_violation_description = (
+    "non-marimo Python content beyond header"
+)
 
 
-def is_unknown_python_script(notebook: NotebookSerialization) -> bool:
+def is_non_marimo_python_script(notebook: NotebookSerialization) -> bool:
     return any(
-        (v.description == _unknown_content_violation_description)
+        (v.description == _non_marimo_python_script_violation_description)
         for v in notebook.violations
     )

marimo/_cli/cli.py

@@ -11,6 +11,7 @@
 
 import click
 
+from marimo._ast.parse import is_non_marimo_python_script
 import marimo._cli.cli_validators as validators
 from marimo import __version__, _loggers
 from marimo._ast import codegen
@@ -56,21 +57,8 @@ def helpful_usage_error(self: Any, file: Any = None) -> None:
 
 
 def check_app_correctness(filename: str) -> None:
-    from marimo._ast.load import UnknownPythonScriptError
-
     try:
         status = get_notebook_status(filename)
-    except UnknownPythonScriptError:
-        import os
-
-        stem = os.path.splitext(os.path.basename(filename))[0]
-        raise click.ClickException(
-            f"Unknown script - {filename} not recognized as a marimo notebook.\n\n"
-            f"  {green('Tip:')} Try converting with"
-            "\n\n"
-            f"    marimo convert {filename} -o {stem}_nb.py\n\n"
-            f"  then open with marimo edit {stem}_nb.py"
-        ) from None
     except SyntaxError:
         import traceback
 
@@ -83,6 +71,19 @@ def check_app_correctness(filename: str) -> None:
         click.echo(f"Failed to parse notebook: {filename}\n", err=True)
         raise click.ClickException(traceback.format_exc(limit=0)) from None
 
+    if status == "invalid" and filename.endswith(".py"):
+        # fail for python scripts, almost certainly do not want to override contents
+        import os
+
+        stem = os.path.splitext(os.path.basename(filename))[0]
+        raise click.ClickException(
+            f"Python script not recognized as a marimo notebook.\n\n"
+            f"  {green('Tip:')} Try converting with"
+            "\n\n"
+            f"    marimo convert {filename} -o {stem}_nb.py\n\n"
+            f"  then open with marimo edit {stem}_nb.py"
+        ) from None
+
     if status == "invalid":
         click.echo(
             green("tip")
@@ -99,6 +100,7 @@ def check_app_correctness(filename: str) -> None:
             default=False,
             abort=True,
         )
+
     if status == "has_errors":
         # Provide a warning, but allow the user to open the notebook
         _loggers.marimo_logger().warning(

marimo/_cli/convert/commands.py

@@ -88,33 +88,24 @@ def convert(
             echo("File is already a valid marimo notebook.")
             return
 
-        # Check if it has the violation indicating it's an unknown Python script
-        if parsed and any(
-            v.description == "Unknown content beyond header"
-            for v in parsed.violations
-        ):
-            try:
-                notebook = MarimoConvert.from_non_marimo_py_script(
-                    text
-                ).to_py()
-            except ImportError as e:
-                # Check if jupytext is the missing module in the cause chain
-                if (
-                    e.__cause__
-                    and getattr(e.__cause__, "name", None) == "jupytext"
-                ):
-                    from marimo._cli.print import green
-
-                    raise click.ClickException(
-                        f"{e}\n\n"
-                        f"  {green('Tip:')} If you're using uv, run:\n\n"
-                        f"    uvx --with=jupytext marimo convert {filename}"
-                    ) from e
-                raise
-        else:
-            # File has other issues (syntax errors, etc.)
-            echo("File cannot be converted. It may have syntax errors.")
-            return
+        try:
+            notebook = MarimoConvert.from_non_marimo_python_script(
+                text
+            ).to_py()
+        except ImportError as e:
+            # Check if jupytext is the missing module in the cause chain
+            if (
+                e.__cause__
+                and getattr(e.__cause__, "name", None) == "jupytext"
+            ):
+                from marimo._cli.print import green
+
+                raise click.ClickException(
+                    f"{e}\n\n"
+                    f"  {green('Tip:')} If you're using uv, run:\n\n"
+                    f"    uvx --with=jupytext marimo convert {filename}"
+                ) from e
+            raise
 
     if output:
         output_path = Path(output)

marimo/_convert/converters.py

@@ -50,7 +50,9 @@ def from_py(source: str) -> MarimoConverterIntermediate:
         return MarimoConverterIntermediate(ir)
 
     @staticmethod
-    def from_non_marimo_py_script(source: str) -> MarimoConverterIntermediate:
+    def from_non_marimo_python_script(
+        source: str,
+    ) -> MarimoConverterIntermediate:
         """Convert from a non-marimo Python script to marimo notebook.
 
         This should only be used when the .py file is not already a valid

tests/_ast/codegen_data/test_get_codes_non_marimo_python_script.py

@@ -0,0 +1,11 @@
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+#     "altair==5.4.1",
+#     "duckdb==1.1.3",
+#     "marimo",
+# ]
+# ///
+
+def hello():
+    print("hello, world")

tests/_ast/test_load.py

@@ -9,6 +9,7 @@
 
 from marimo import _loggers
 from marimo._ast import load
+from marimo._ast.parse import MarimoFileError
 
 DIR_PATH = os.path.dirname(os.path.realpath(__file__))
 
@@ -216,6 +217,13 @@ def test_get_codes_app_with_only_comments(load_app) -> None:
         app = load_app(get_filepath("test_app_with_only_comments"))
         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(
+                get_filepath("test_get_codes_non_marimo_python_script")
+            )
+
     @staticmethod
     def test_get_codes_app_with_no_cells(load_app) -> None:
         app = load_app(get_filepath("test_app_with_no_cells"))
@@ -310,66 +318,3 @@ def test_get_status_warn() -> None:
             )
             == "has_errors"
         )
-
-    @staticmethod
-    def test_non_marimo_file_error(tmp_path) -> None:
-        """Test loading a marimo Python script raises UnknownPythonScriptError."""
-        regular_python = textwrap.dedent(
-            """
-            import numpy as np
-
-            def main():
-                x = np.array([1, 2, 3])
-                print(x)
-
-            if __name__ == "__main__":
-                main()
-            """
-        ).strip()
-
-        filepath = tmp_path / "regular_script.py"
-        filepath.write_text(regular_python)
-
-        with pytest.raises(
-            load.UnknownPythonScriptError, match="is not a marimo notebook"
-        ):
-            load.get_notebook_status(str(filepath))
-
-    @staticmethod
-    def test_python_script_metadata_and_imports_error(tmp_path) -> None:
-        """Test loading a file with metadata and imports raises UnknownPythonScriptError."""
-        metadata_only = textwrap.dedent(
-            """
-            # /// script
-            # dependencies = ["numpy", "pandas"]
-            # requires-python = ">=3.8"
-            # ///
-
-            import numpy as np
-            """
-        ).strip()
-
-        filepath = tmp_path / "imports_and_metadata_only.py"
-        filepath.write_text(metadata_only)
-
-        with pytest.raises(
-            load.UnknownPythonScriptError, match="is not a marimo notebook"
-        ):
-            load.get_notebook_status(str(filepath))
-
-    @staticmethod
-    def test_script_metadata_only_file(tmp_path) -> None:
-        """Test that files with only script metadata are allowed."""
-        metadata_only = textwrap.dedent(
-            """
-            # /// script
-            # dependencies = ["numpy", "pandas"]
-            # requires-python = ">=3.8"
-            # ///
-            """
-        ).strip()
-
-        filepath = tmp_path / "metadata_only.py"
-        filepath.write_text(metadata_only)
-
-        assert load.get_notebook_status(str(filepath)) == "invalid"