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.

13.3 KB
Raw Blame
# Copyright 2024 Marimo. All rights reserved.
from __future__ import annotations

import pytest

from marimo._ast.app import App, InternalApp
from marimo._convert.markdown.flavor import (
    markdown_output_filename,
)
from marimo._convert.markdown.from_ir import (
    _format_filename_title,
    _get_sql_options_from_cell,
    convert_from_ir_to_markdown,
)


def test_format_filename_title():
    """Test that filenames are formatted correctly into titles."""
    assert _format_filename_title("my_notebook.py") == "My Notebook"
    assert _format_filename_title("my-notebook.md") == "My Notebook"
    assert _format_filename_title("/path/to/my_notebook.py") == "My Notebook"
    assert _format_filename_title("simple.py") == "Simple"
    assert _format_filename_title("my-cool_notebook.md") == "My Cool Notebook"
    assert _format_filename_title("notebook.myst.md") == "Notebook"
    assert _format_filename_title("notebook.mdx") == "Notebook"


def test_get_sql_options_from_cell_basic():
    """Test extraction of SQL options from basic SQL code."""
    code = '_df = mo.sql("SELECT * FROM table")'
    options = _get_sql_options_from_cell(code)
    assert options is not None
    assert options["query"] == "_df"


def test_get_sql_options_from_cell_with_keywords():
    """Test extraction of SQL options with keyword arguments."""
    code = '_df = mo.sql("SELECT * FROM table", output=False)'
    options = _get_sql_options_from_cell(code)
    assert options is not None
    assert options["query"] == "_df"
    assert options["hide_output"] == "True"


def test_get_sql_options_from_cell_with_engine():
    """Test extraction of SQL options with engine parameter."""
    code = 'result = mo.sql("SELECT * FROM table", engine="my_engine")'
    options = _get_sql_options_from_cell(code)
    assert options is not None
    assert options["query"] == "result"
    assert options["engine"] == "my_engine"


def test_get_sql_options_from_cell_not_sql():
    """Test that non-SQL code returns None."""
    code = "x = 1 + 1"
    options = _get_sql_options_from_cell(code)
    assert options is None


def test_get_sql_options_from_cell_invalid():
    """Test that code without proper structure returns None."""
    code = 'x = mo.other_method("SELECT * FROM table")'
    options = _get_sql_options_from_cell(code)
    assert options is None


def test_get_sql_options_from_cell_not_assignment():
    """Test that code without assignment returns None."""
    code = 'mo.sql("SELECT * FROM table")'
    options = _get_sql_options_from_cell(code)
    assert options is None


def test_convert_from_ir_to_markdown_empty():
    """Test conversion of empty notebook to markdown."""
    app = App()
    internal_app = InternalApp(app)
    notebook = internal_app.to_ir()

    markdown = convert_from_ir_to_markdown(notebook)

    # Should have frontmatter
    assert markdown.startswith("---")
    assert "marimo-version" in markdown


def test_convert_from_ir_to_markdown_with_code():
    """Test conversion of notebook with code cells to markdown."""
    app = App()

    @app.cell()
    def test_cell():
        x = 1
        return (x,)

    internal_app = InternalApp(app)
    notebook = internal_app.to_ir()

    markdown = convert_from_ir_to_markdown(notebook)

    # Should have frontmatter
    assert markdown.startswith("---")
    assert "marimo-version" in markdown
    # Should have code block
    assert "```python" in markdown
    assert "x = 1" in markdown


def test_convert_from_ir_to_markdown_with_markdown_cell():
    """Test conversion of notebook with markdown cells."""
    app = App()

    @app.cell()
    def __():
        import marimo as mo

        return (mo,)

    @app.cell()
    def __(mo):
        mo.md("# Hello World")

    internal_app = InternalApp(app)
    notebook = internal_app.to_ir()

    markdown = convert_from_ir_to_markdown(notebook)

    # Should have the markdown content
    assert "# Hello World" in markdown


def test_convert_from_ir_to_markdown_with_sql():
    """Test conversion of notebook with SQL cells to markdown."""
    app = App()

    @app.cell()
    def __():
        import marimo as mo

        return (mo,)

    @app.cell()
    def __(mo):
        _df = mo.sql("SELECT * FROM my_table")
        return (_df,)

    internal_app = InternalApp(app)
    notebook = internal_app.to_ir()

    markdown = convert_from_ir_to_markdown(notebook)

    # Should have SQL code block
    assert "```sql" in markdown or "```python" in markdown
    assert "SELECT * FROM my_table" in markdown


def test_convert_from_ir_to_markdown_preserves_cell_names():
    """Test that cell names are preserved in markdown."""
    app = App()

    @app.cell()
    def my_cell():
        x = 1
        return (x,)

    internal_app = InternalApp(app)
    notebook = internal_app.to_ir()

    markdown = convert_from_ir_to_markdown(notebook)

    # Should have cell name in attributes
    assert "name=my_cell" in markdown or 'name="my_cell"' in markdown


def test_convert_from_ir_to_markdown_with_cell_config():
    """Test that cell configurations are preserved."""
    app = App()

    @app.cell(hide_code=True)
    def __():
        x = 1
        return (x,)

    internal_app = InternalApp(app)
    notebook = internal_app.to_ir()

    markdown = convert_from_ir_to_markdown(notebook)

    # Should have hide_code in attributes
    assert 'hide_code="true"' in markdown or "hide_code=true" in markdown


def test_convert_from_ir_to_markdown_with_app_title():
    """Test that app title is preserved in frontmatter."""
    app = App(app_title="My Test App")

    @app.cell()
    def __():
        return

    internal_app = InternalApp(app)
    notebook = internal_app.to_ir()

    markdown = convert_from_ir_to_markdown(notebook)

    # Should have title in frontmatter
    assert "title: My Test App" in markdown


def test_convert_from_ir_to_markdown_consecutive_markdown_cells():
    """Test that consecutive markdown cells are separated with HTML comments."""
    app = App()

    @app.cell()
    def __():
        import marimo as mo

        return (mo,)

    @app.cell()
    def __(mo):
        mo.md("# First markdown")

    @app.cell()
    def __(mo):
        mo.md("# Second markdown")

    internal_app = InternalApp(app)
    notebook = internal_app.to_ir()

    markdown = convert_from_ir_to_markdown(notebook)

    # Should have HTML comment separator between markdown cells
    assert "<!---->" in markdown
    assert "# First markdown" in markdown
    assert "# Second markdown" in markdown


def test_convert_from_ir_to_markdown_with_column():
    """Test that cells with column configuration force markdown to code."""
    app = App()

    @app.cell()
    def __():
        import marimo as mo

        return (mo,)

    @app.cell(column=1)
    def __(mo):
        mo.md("# Markdown in column")

    internal_app = InternalApp(app)
    notebook = internal_app.to_ir()

    markdown = convert_from_ir_to_markdown(notebook)

    # Markdown should be forced to code block due to column
    assert "```python" in markdown
    assert "column=1" in markdown or 'column="1"' in markdown


def test_convert_from_ir_to_markdown_unparsable_cell():
    """Test that unparsable cells are marked with unparsable attribute."""
    from marimo._schemas.serialization import (
        AppInstantiation,
        CellDef,
        NotebookSerializationV1,
    )

    # Create a notebook with an unparsable cell by directly constructing the IR
    notebook = NotebookSerializationV1(
        app=AppInstantiation(options={}),
        cells=[
            CellDef(
                name="__",
                code="this is { not valid python",
                options={},
            )
        ],
        violations=[],
        valid=True,
        filename="notebook.py",
    )

    markdown = convert_from_ir_to_markdown(notebook)

    # Should mark as unparsable
    assert 'unparsable="true"' in markdown or "unparsable=true" in markdown
    assert "this is { not valid python" in markdown


def test_convert_from_ir_to_markdown_qmd_format():
    """Test that .qmd files use Quarto-compatible fence format."""
    app = App()

    @app.cell()
    def test_cell():
        x = 1
        return (x,)

    internal_app = InternalApp(app)
    notebook = internal_app.to_ir()

    # Test .qmd filename produces Quarto format
    markdown_qmd = convert_from_ir_to_markdown(
        notebook, filename="notebook.qmd"
    )
    assert "```{marimo .python" in markdown_qmd

    markdown_mystmd = convert_from_ir_to_markdown(
        notebook, filename="notebook.myst.md"
    )
    assert "```{marimo} python" in markdown_mystmd

    # Test .md filename produces standard format
    markdown_md = convert_from_ir_to_markdown(notebook, filename="notebook.md")
    assert "```python {.marimo" in markdown_md


def test_convert_from_ir_to_markdown_mdx_format():
    """Test that .mdx files use mdx-marimo fence format."""
    from marimo._schemas.serialization import (
        AppInstantiation,
        CellDef,
        Header,
        NotebookSerializationV1,
    )

    notebook = NotebookSerializationV1(
        app=AppInstantiation(options={"app_title": "MDX Demo"}),
        cells=[
            CellDef(
                name="setup",
                code="import marimo as mo",
                options={"hide_code": True},
            ),
            CellDef(
                name="view",
                code='mo.md("# Ready")',
                options={},
            ),
        ],
        header=Header(
            value=(
                '# /// script\n# dependencies = ["polars"]\n# ///\nimport os'
            )
        ),
        violations=[],
        valid=True,
        filename="notebook.py",
    )

    markdown = convert_from_ir_to_markdown(notebook, filename="notebook.mdx")

    assert markdown.startswith("---\ntitle: MDX Demo\n")
    assert '```marimo-config\ndependencies = ["polars"]\n```' in markdown
    assert "```python marimo include=false\nimport os\n```" in markdown
    assert "```python marimo hide-code=true name=setup" in markdown
    assert "# Ready" in markdown


def test_convert_from_ir_to_markdown_explicit_flavor():
    """Test that explicit flavors override filename inference."""
    app = App()

    @app.cell()
    def test_cell():
        x = 1
        return (x,)

    internal_app = InternalApp(app)
    notebook = internal_app.to_ir()

    markdown_qmd = convert_from_ir_to_markdown(
        notebook, filename="notebook.md", flavor="qmd"
    )
    assert "```{marimo .python" in markdown_qmd

    markdown_md = convert_from_ir_to_markdown(
        notebook, filename="notebook.qmd", flavor="pymdown"
    )
    assert "```python {.marimo" in markdown_md


@pytest.mark.parametrize(
    ("filename", "flavor", "expected"),
    [
        ("source.py", "pymdown", "source.md"),
        ("source.py", "qmd", "source.qmd"),
        ("source.py", "mystmd", "source.myst.md"),
        ("source.py", "mdx", "source.mdx"),
        ("source.qmd", "pymdown", "source.md"),
        ("source.mdx", "pymdown", "source.md"),
        ("source.myst.md", "pymdown", "source.md"),
        ("source.myst.md", "mystmd", "source.myst.md"),
        (None, "qmd", "notebook.qmd"),
        (None, "mdx", "notebook.mdx"),
    ],
)
def test_markdown_output_filename(filename, flavor, expected):
    assert markdown_output_filename(filename, flavor) == expected


def test_markdown_output_filename_rejects_unknown_flavor():
    with pytest.raises(
        ValueError,
        match="Unsupported markdown flavor: 'bogus'",
    ):
        markdown_output_filename("nb.md", "bogus")  # type: ignore[arg-type]


@pytest.mark.parametrize(
    ("filename", "flavor", "expected_head", "expected_name"),
    [
        (
            "notebook.md",
            "pymdown",
            "```python",
            'name="a&quot;b &amp; &lt;c&gt;"',
        ),
        (
            "notebook.qmd",
            "qmd",
            "```{marimo .python",
            'name="a&quot;b &amp; &lt;c&gt;"',
        ),
        (
            "notebook.mdx",
            "mdx",
            "```python marimo",
            "name='a\"b & <c>'",
        ),
    ],
)
def test_convert_from_ir_to_markdown_escapes_code_cell_attributes(
    filename: str,
    flavor: str,
    expected_head: str,
    expected_name: str,
) -> None:
    from marimo._schemas.serialization import (
        AppInstantiation,
        CellDef,
        NotebookSerializationV1,
    )

    notebook = NotebookSerializationV1(
        app=AppInstantiation(options={}),
        cells=[
            CellDef(
                name='a"b & <c>',
                code="x = 1",
                options={},
            )
        ],
        violations=[],
        valid=True,
        filename="notebook.py",
    )

    markdown = convert_from_ir_to_markdown(
        notebook, filename=filename, flavor=flavor
    )

    assert expected_head in markdown
    assert expected_name in markdown


def test_convert_from_ir_to_markdown_mdx_escapes_quoted_options() -> None:
    from marimo._schemas.serialization import (
        AppInstantiation,
        CellDef,
        NotebookSerializationV1,
    )

    notebook = NotebookSerializationV1(
        app=AppInstantiation(options={}),
        cells=[
            CellDef(
                name="a\"b'c\\d",
                code="x = 1",
                options={},
            )
        ],
        violations=[],
        valid=True,
        filename="notebook.py",
    )

    markdown = convert_from_ir_to_markdown(
        notebook, filename="notebook.mdx", flavor="mdx"
    )

    assert 'name="a\\"b\'c\\\\d"' in markdown