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.

9.8 KB
Raw Blame
from unittest.mock import patch

import pytest
from inline_snapshot import snapshot as inline_snapshot

from marimo._utils.docs import (
    MarkdownConverter,
    _process_code_block_content,
    google_docstring_to_markdown,
)
from tests.mocks import snapshotter

snapshot = snapshotter(__file__)


@pytest.mark.parametrize("with_args", [False, True])
@pytest.mark.parametrize(
    "docstring",
    [
        """Add exclamation marks after text.

Note: `shout_factor` supports all natural numbers.
If a `shout_factor` is a negative number, that number of
exclamation marks will be removed from the input text.

For example: `shout('hi!!!', shout_factor=-1)` will return `'hi!!'`.""",
        r"Use `a_b`, `[a_b]`, `*a_b*`, and `C:\some_path`.",
        "Code:\n\n```python\nshout_factor = 1\n```",
        "Use ``a`b_c`` to include a backtick.",
    ],
)
def test_pylsp_docstring_code_spans(docstring: str, with_args: bool) -> None:
    utils = pytest.importorskip("pylsp._utils")
    if with_args:
        docstring += (
            "\n\nArgs:\n    shout_factor: Number of exclamation marks."
        )

    assert utils.format_docstring(docstring, "markdown") == {
        "kind": "markdown",
        "value": (
            google_docstring_to_markdown(docstring) if with_args else docstring
        ),
    }


@pytest.mark.parametrize(
    "docstring",
    [
        "Use `shout_factor`.\n\n:param shout_factor: Number of exclamation marks.",
        (
            "Use `shout_factor`.\n\nParameters\n----------\n"
            "shout_factor : int\n    Number of exclamation marks."
        ),
        "Use :class:`My_Class`.",
        "Use `shout_factor`.\n\n>>> shout_factor = 1\n>>> shout_factor\n1",
        "Use shout_factor.",
        "Use `shout_factor.",
        r"Use \`shout_factor\`.",
        "Plain text.",
        "",
    ],
)
def test_pylsp_preserves_other_docstring_formats(
    docstring: str,
) -> None:
    utils = pytest.importorskip("pylsp._utils")
    # Compare with the installed upstream version's behavior before our fallback.
    with patch.object(MarkdownConverter, "can_convert", return_value=False):
        expected = utils.format_docstring(docstring, "markdown")
    assert utils.format_docstring(docstring, "markdown") == expected


@pytest.mark.parametrize(
    ("docstring", "expected"),
    [
        ("", False),
        ("Use `shout_factor`.", True),
        ("Use ``shout_factor``.", True),
        ("Use ``a`b_c``.", True),
        ("Code:\n```python\nshout_factor = 1\n```", True),
        ("Use shout_factor.", False),
        ("Use `shout_factor.", False),
        ("Use `shout_factor``.", False),
        (r"Use \`shout_factor\`.", False),
    ],
)
def test_markdown_converter_can_convert(
    docstring: str, expected: bool
) -> None:
    assert MarkdownConverter().can_convert(docstring) is expected


def test_google_docstring_to_markdown_summary():
    docstring = """This is the summary.

    Args:
        foo (str): Lorem ipsum
        bar (int): Dolor sit amet

    Attributes:
        baz (str): Lorem ipsum
        boo (int): Dolor sit amet

    Returns:
        bool: Return description

    Raises:
        ValueError: Something about the value

    Examples:
        ```python
        print("Hello, world!")
        print(foo, bar)
        ```
    """
    md_result = google_docstring_to_markdown(docstring)
    snapshot("docstring_summary.md", md_result)

    for substr in [
        "# Summary",
        "This is the summary.",
        "# Arguments",
        "`foo`",
        "`bar`",
        "# Attributes",
        "`baz`",
        "`boo`",
        "# Returns",
        "`bool`",
        "# Raises",
        "ValueError",
        "# Examples",
        "```python",
        'print("Hello, world!")',
    ]:
        assert substr in md_result


def test_google_docstring_to_markdown_complex():
    docstring = """
    Stack items vertically, in a column.
    Combine with `hstack` to build a grid of items.

    Examples:
        Build a column of items:
        ```python
        # Build a column of items
        mo.vstack([mo.md("..."), mo.ui.text_area()])
        ```
        Build a grid:
        ```python
        # Build a grid.
        mo.vstack(
            [
                mo.hstack([mo.md("..."), mo.ui.text_area()]),
                mo.hstack([mo.ui.checkbox(), mo.ui.text(), mo.ui.date()]),
            ]
        )
        ```

    Args:
        items (Sequence[object]): A list of items.
        align (Literal["start", "end", "center", "stretch"], optional): Align items horizontally: start, end, center, or stretch.
        justify (Literal["start", "center", "end", "space-between", "space-around"]):
            Justify items vertically: start, center, end, space-between, or space-around.
            Defaults to "start".
        gap (float, optional): Gap between items as a float in rem. 1rem is 16px by default.
            Defaults to 0.5.
        heights (Union[Literal["equal"], Sequence[float]], optional): "equal" to give items
            equal height; or a list of relative heights with same length as `items`,
            eg, [1, 2] means the second item is twice as tall as the first;
            or None for a sensible default.
        custom_css (dict[str, str], optional): Custom CSS styles for each column. Keys include:
            - width
            - height
            - background_color
            - border
            - border_radius
            - padding
        typeless: Pass unknown types to the stack.
        *args: positional arguments passed to stack
        code_block (str): Render a code block in the stack.
            ```
            mo.vstack(),
            mo.hstack()
            ```
        second_code_block (str): Render a second code block in the stack.
            ```python
            mo.vstack([])
            ```
        **kwargs: keyword arguments passed to stack

    Returns:
        Html: An Html object.
    """
    md_result = google_docstring_to_markdown(docstring)

    assert "<pre><code>mo.vstack(),<br>mo.hstack()</code></pre>" in md_result
    assert "<pre><code>mo.vstack([])</code></pre>" in md_result

    snapshot("docstring_complex.md", md_result)


def test_google_docstring_to_markdown_oneliner():
    docstring = """One-liner docstring"""
    md_result = google_docstring_to_markdown(docstring)
    snapshot("docstring_one_liner.md", md_result)

    for substr in [
        "# Summary",
        "One-liner docstring",
    ]:
        assert substr in md_result


def test_google_docstring_infers_types_from_signature() -> None:
    docstring = """Do something

    Args:
        arg: An integer argument
    """
    md_result = google_docstring_to_markdown(
        docstring, param_types={"arg": "int"}
    )
    assert "| `arg` | `int` | An integer argument |" in md_result


def test_google_docstring_preserves_explicit_types() -> None:
    docstring = """Args:
        arg (str): A string argument
    """
    md_result = google_docstring_to_markdown(
        docstring, param_types={"arg": "int"}
    )
    assert "| `arg` | `str` | A string argument |" in md_result


def test_google_docstring_infers_varargs_types_from_signature() -> None:
    docstring = """Args:
        *args: extra positionals
        **kwargs: extra keywords
    """
    # Signatures report varargs without the star prefixes.
    md_result = google_docstring_to_markdown(
        docstring,
        param_types={"args": "Tuple[str]", "kwargs": "Dict[str, float]"},
    )
    assert md_result == inline_snapshot(
        """\

# Arguments
| Parameter | Type | Description |
|-----------|------|-------------|
| `*args` | `Tuple[str]` | extra positionals |
| `**kwargs` | `Dict[str, float]` | extra keywords |"""
    )


def test_google_docstring_custom_named_varargs() -> None:
    docstring = """Print a greeting for each name.

    Args:
        greeting: The greeting to print.
        *names: Names to greet.
        **options: Extra options.
    """
    md_result = google_docstring_to_markdown(
        docstring,
        param_types={
            "greeting": "str",
            "names": "Tuple[list[str]]",
        },
    )
    assert md_result == inline_snapshot(
        """\
# Summary
Print a greeting for each name.

# Arguments
| Parameter | Type | Description |
|-----------|------|-------------|
| `greeting` | `str` | The greeting to print. |
| `*names` | `Tuple[list[str]]` | Names to greet. |
| `**options` | `` | Extra options. |"""
    )


def test_process_code_block_content():
    """Test the _process_code_block_content function with various inputs."""

    # Test with no code blocks
    result = _process_code_block_content("Simple description")
    assert result == "Simple description"

    # Test with a simple code block
    result = _process_code_block_content(
        "Description with ```python\ncode here\n```"
    )
    assert result == "Description with <pre><code>code here</code></pre>"

    # Test with code block without language
    result = _process_code_block_content(
        "Description with ```\ncode here\n```"
    )
    assert result == "Description with <pre><code>code here</code></pre>"

    # Test with multiple code blocks
    result = _process_code_block_content(
        "First ```python\ncode1\n``` Second ```\ncode2\n```"
    )
    assert (
        result
        == "First <pre><code>code1</code></pre> Second <pre><code>code2</code></pre>"
    )

    # Test with text after code block
    result = _process_code_block_content(
        "Description ```python\ncode\n``` and more text"
    )
    assert result == "Description <pre><code>code</code></pre> and more text"

    # Test with language identifier
    result = _process_code_block_content(
        "Description ```python\ncode here\n```"
    )
    assert result == "Description <pre><code>code here</code></pre>"

    # Test with empty code block
    result = _process_code_block_content("Description ```\n\n```")
    assert result == "Description <pre><code></code></pre>"