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
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>"