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.

fix(completion): infer arg types from signature for Google docstrings (#10085)

Shahmir Varqhab1c8c00c8f4b
diff --git a/marimo/_runtime/complete.py b/marimo/_runtime/complete.py
index 1525cf3fb2..f846b0bbf1 100644
--- a/marimo/_runtime/complete.py
+++ b/marimo/_runtime/complete.py
@@ -23,7 +23,7 @@ from marimo._output.md import _md
from marimo._runtime import dataflow
from marimo._runtime.commands import CodeCompletionCommand
from marimo._types.ids import RequestId
-from marimo._utils.docs import MarimoConverter
+from marimo._utils.docs import MarimoConverter, google_docstring_to_markdown
from marimo._utils.format_signature import format_signature
from marimo._utils.rst_to_html import convert_rst_to_html
@@ -106,6 +106,7 @@ def _build_docstring_cached(
signature_strings: tuple[str, ...],
raw_body: str | None,
init_docstring: str | None,
+ param_types: tuple[tuple[str, str], ...] = (),
) -> str:
"""Builds the docstring that includes signatures and body."""
if not signature_strings:
@@ -138,7 +139,9 @@ def _build_docstring_cached(
).text
body_converted = (
- _convert_docstring_to_markdown(raw_body) if raw_body else ""
+ _convert_docstring_to_markdown(raw_body, dict(param_types))
+ if raw_body
+ else ""
)
if signature_text and body_converted:
@@ -155,7 +158,9 @@ def _build_docstring_cached(
doc_convert = MarimoConverter()
-def _convert_docstring_to_markdown(raw_docstring: str) -> str:
+def _convert_docstring_to_markdown(
+ raw_docstring: str, param_types: dict[str, str] | None = None
+) -> str:
"""
Convert raw docstring to markdown then to HTML.
"""
@@ -163,6 +168,15 @@ def _convert_docstring_to_markdown(raw_docstring: str) -> str:
def as_md_html(raw: str) -> str:
return _md(raw, apply_markdown_class=False).text
+ # Prefer our Google converter when applicable so signature types can
+ # fill in missing Args table types.
+ if doc_convert.can_convert(raw_docstring):
+ return as_md_html(
+ google_docstring_to_markdown(
+ raw_docstring, param_types=param_types
+ )
+ )
+
# Prefer using docstring_to_markdown if available
# which uses our custom MarimoConverter
if DependencyManager.docstring_to_markdown.has():
@@ -176,10 +190,6 @@ def _convert_docstring_to_markdown(raw_docstring: str) -> str:
"falling back",
)
- # Then try our custom MarimoConverter
- if doc_convert.can_convert(raw_docstring):
- return as_md_html(doc_convert.convert(raw_docstring))
-
# Prefer markdown rendering when math syntax is present.
# This ensures ``.. math::`` and markdown delimiters are interpreted by
# the same TeX pipeline used elsewhere in marimo output.
@@ -204,6 +214,26 @@ def _convert_docstring_to_markdown(raw_docstring: str) -> str:
)
+def _param_types_from_signatures(
+ signatures: list[jedi.api.classes.Signature],
+) -> dict[str, str]:
+ """Extract parameter type hints from a Jedi signature."""
+ if not signatures:
+ return {}
+ params = getattr(signatures[0], "params", None)
+ if not params:
+ return {}
+ param_types: dict[str, str] = {}
+ for param in params:
+ try:
+ type_hint = cast(str, param.get_type_hint())
+ except Exception:
+ continue
+ if type_hint:
+ param_types[param.name] = type_hint
+ return param_types
+
+
def _get_docstring(completion: jedi.api.classes.BaseName) -> str:
try:
raw_body = cast(str, completion.docstring(raw=True))
@@ -213,9 +243,10 @@ def _get_docstring(completion: jedi.api.classes.BaseName) -> str:
# Glean raw signatures
try:
- signature_strings = tuple(
- s.to_string() for s in completion.get_signatures()
- )
+ signature_objects = completion.get_signatures()
+ signature_strings = tuple(s.to_string() for s in signature_objects)
+ param_types = _param_types_from_signatures(signature_objects)
+ sorted_param_types = sorted(param_types.items())
except Exception:
LOGGER.debug("Maybe failed getting signature for %s", completion.name)
return ""
@@ -245,6 +276,7 @@ def _get_docstring(completion: jedi.api.classes.BaseName) -> str:
signature_strings,
raw_body,
init_docstring or None,
+ tuple(sorted_param_types),
)
diff --git a/marimo/_utils/docs.py b/marimo/_utils/docs.py
index 99027a282e..8f589d2b3a 100644
--- a/marimo/_utils/docs.py
+++ b/marimo/_utils/docs.py
@@ -3,16 +3,42 @@ from __future__ import annotations
import re
from textwrap import dedent
+from typing import TYPE_CHECKING
from marimo._runtime.patches import patch_jedi_parameter_completion
+if TYPE_CHECKING:
+ from collections.abc import Mapping
-def google_docstring_to_markdown(docstring: str) -> str:
+
+def _fill_missing_param_types(
+ table: list[tuple[str, str, str]],
+ param_types: Mapping[str, str] | None,
+) -> None:
+ """Fill empty type cells from signature annotations."""
+ if not param_types:
+ return
+ for index, (name, arg_type, description) in enumerate(table):
+ if arg_type:
+ continue
+ # Varargs rows are stored as `*args`/`**kwargs`, but signatures report
+ # them as `args`/`kwargs`, so strip leading stars before matching.
+ lookup = name.lstrip("*")
+ if lookup in param_types:
+ table[index] = (name, param_types[lookup], description)
+
+
+def google_docstring_to_markdown(
+ docstring: str,
+ param_types: Mapping[str, str] | None = None,
+) -> str:
"""
Converts a Google-style docstring to a rough Markdown format.
Args:
docstring (str): The raw Google-style docstring.
+ param_types (Mapping[str, str] | None): Optional parameter types from
+ the function signature, used when the docstring omits inline types.
Returns:
str: A Markdown string that can be consumed by our doc-to-HTML converter.
@@ -43,22 +69,15 @@ def google_docstring_to_markdown(docstring: str) -> str:
def _handle_arg_or_attribute(
table: list[tuple[str, str, str]], stripped: str
) -> None:
- # Parse standard parameters: "arg_name (arg_type): description" or "arg_name: description"
- # This handles both typed and untyped parameters, with or without description
- match = re.match(r"^(\w+)(?:\s*\(([^)]+)\))?:\s*(.*)", stripped)
+ # Parse parameters, including varargs: "var_name", "*var_name", or "**var_name",
+ # each optionally "(type)" and optionally ": description". This handles
+ # typed and untyped params, with or without a description.
+ match = re.match(r"^(\*{0,2}\w+)(?:\s*\(([^)]+)\))?:\s*(.*)", stripped)
if match:
arg_name, arg_type, description = match.groups()
table.append((arg_name, arg_type or "", description.strip()))
return
- # Parse special parameters: "*args: description" or "**kwargs: description"
- if stripped.startswith("*args:"):
- table.append(("*args", "", stripped[6:].strip()))
- return
- if stripped.startswith("**kwargs:"):
- table.append(("**kwargs", "", stripped[9:].strip()))
- return
-
# Handle continuation lines
if not table:
return
@@ -190,6 +209,8 @@ def google_docstring_to_markdown(docstring: str) -> str:
# Otherwise, treat it as summary or normal text
parsed_lines.append(stripped)
+ _fill_missing_param_types(arg_table, param_types)
+
# Build final output
output: list[str] = []
if parsed_lines:
diff --git a/tests/_runtime/snapshots/docstrings_function_google.txt b/tests/_runtime/snapshots/docstrings_function_google.txt
index efc915a4c8..893fab71ae 100644
--- a/tests/_runtime/snapshots/docstrings_function_google.txt
+++ b/tests/_runtime/snapshots/docstrings_function_google.txt
@@ -1,4 +1,4 @@
-<div class="language-python3 codehilite"><pre><span></span><code><span class="k">def</span><span class="w"> </span><span class="nf">my_func</span><span class="p">(</span><span class="n">arg1</span><span class="p">,</span> <span class="n">arg2</span><span class="p">)</span>
+<div class="language-python3 codehilite"><pre><span></span><code><span class="k">def</span><span class="w"> </span><span class="nf">my_func</span><span class="p">(</span><span class="n">arg1</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">arg2</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span>
</code></pre></div>
<h1 id="arguments">Arguments</h1>
@@ -13,12 +13,12 @@
<tbody>
<tr>
<td><code>arg1</code></td>
-<td>``</td>
+<td><code>str</code></td>
<td>Description of arg1.</td>
</tr>
<tr>
<td><code>arg2</code></td>
-<td>``</td>
+<td><code>int</code></td>
<td>Description of arg2.</td>
</tr>
</tbody>
diff --git a/tests/_runtime/test_complete.py b/tests/_runtime/test_complete.py
index 3a6514fcc7..969436e629 100644
--- a/tests/_runtime/test_complete.py
+++ b/tests/_runtime/test_complete.py
@@ -55,7 +55,7 @@ def test_docstring_function_with_google_style():
result = _build_docstring_cached(
completion_type="function",
completion_name="my_func",
- signature_strings=("my_func(arg1, arg2)",),
+ signature_strings=("my_func(arg1: str, arg2: int)",),
raw_body="""
Args:
arg1: Description of arg1.
@@ -65,14 +65,64 @@ def test_docstring_function_with_google_style():
HTML: A description of the return value.
""",
init_docstring=None,
+ param_types=(("arg1", "str"), ("arg2", "int")),
)
assert "Description of arg1" in result
assert "Description of arg2" in result
assert "A description of the return value" in result
+ assert "<code>str</code>" in result
+ assert "<code>int</code>" in result
snapshot("docstrings_function_google.txt", result)
+def test_docstring_function_with_google_style_infers_types_from_jedi() -> None:
+ patch_jedi_parameter_completion()
+
+ code = '''def func(arg: int) -> None:
+ """Do something
+
+ Args:
+ arg: An integer argument
+ """
+ return
+
+func'''
+ script = jedi.Script(code)
+ completions = script.complete(line=9, column=4)
+ func_completion = next(c for c in completions if c.name == "func")
+ result = _get_docstring(func_completion)
+
+ assert "<code>int</code>" in result
+ assert "An integer argument" in result
+
+
+def test_docstring_function_infers_varargs_types_from_jedi() -> None:
+ patch_jedi_parameter_completion()
+
+ code = '''def func(*args: str, **kwargs: float) -> None:
+ """Do something
+
+ Args:
+ *args: extra positionals
+ **kwargs: extra keywords
+ """
+ return
+
+func'''
+ script = jedi.Script(code)
+ completions = script.complete(line=10, column=4)
+ func_completion = next(c for c in completions if c.name == "func")
+ result = _get_docstring(func_completion)
+
+ assert "extra positionals" in result
+ assert "extra keywords" in result
+ # Jedi reports varargs as container types (`args`/`kwargs` without stars);
+ # they should still populate the `*args`/`**kwargs` rows.
+ assert "<code>Tuple[str]</code>" in result
+ assert "<code>Dict[str, float]</code>" in result
+
+
def test_docstring_math_directive_is_normalized():
result = _build_docstring_cached(
completion_type="function",
diff --git a/tests/_utils/test_docs.py b/tests/_utils/test_docs.py
index bb9b6b34f3..61c88b3035 100644
--- a/tests/_utils/test_docs.py
+++ b/tests/_utils/test_docs.py
@@ -1,3 +1,5 @@
+from inline_snapshot import snapshot as inline_snapshot
+
from marimo._utils.docs import (
_process_code_block_content,
google_docstring_to_markdown,
@@ -130,6 +132,78 @@ def test_google_docstring_to_markdown_oneliner():
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."""