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
fix(completion): infer arg types from signature for Google docstrings (#10085)
Shahmir Varqhab1c8c00c8f4b
diff --git a/marimo/_runtime/complete.py b/marimo/_runtime/complete.pyindex 1525cf3fb2..f846b0bbf1 100644--- a/marimo/_runtime/complete.py+++ b/marimo/_runtime/complete.py@@ -23,7 +23,7 @@ from marimo._output.md import _mdfrom marimo._runtime import dataflowfrom marimo._runtime.commands import CodeCompletionCommandfrom marimo._types.ids import RequestId-from marimo._utils.docs import MarimoConverter+from marimo._utils.docs import MarimoConverter, google_docstring_to_markdownfrom marimo._utils.format_signature import format_signaturefrom 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().textbody_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 MarimoConverterif 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 signaturestry:- 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.pyindex 99027a282e..8f589d2b3a 100644--- a/marimo/_utils/docs.py+++ b/marimo/_utils/docs.py@@ -3,16 +3,42 @@ from __future__ import annotationsimport refrom textwrap import dedent+from typing import TYPE_CHECKINGfrom 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 linesif not table:return@@ -190,6 +209,8 @@ def google_docstring_to_markdown(docstring: str) -> str:# Otherwise, treat it as summary or normal textparsed_lines.append(stripped)+ _fill_missing_param_types(arg_table, param_types)+# Build final outputoutput: list[str] = []if parsed_lines:diff --git a/tests/_runtime/snapshots/docstrings_function_google.txt b/tests/_runtime/snapshots/docstrings_function_google.txtindex 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.pyindex 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 resultassert "Description of arg2" in resultassert "A description of the return value" in result+ assert "<code>str</code>" in result+ assert "<code>int</code>" in resultsnapshot("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.pyindex 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."""