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.

jedi: resolve definitions and get docstring (#9838)

Shahmir Varqha9c586ebd1771
diff --git a/marimo/_runtime/complete.py b/marimo/_runtime/complete.py
index 3b73ceacf0..6d44418261 100644
--- a/marimo/_runtime/complete.py
+++ b/marimo/_runtime/complete.py
@@ -257,19 +257,48 @@ def _get_type_hint(completion: jedi.api.classes.BaseName) -> str:
return ""
+# Jedi types that carry a signature/docstring worth surfacing in live docs.
+_DOCUMENTABLE_TYPES = ("function", "class", "module")
+
+
+def _resolve_aliased_definition(
+ completion: jedi.api.classes.BaseName,
+) -> jedi.api.classes.BaseName | None:
+ """Follow an assignment statement to its underlying definition.
+
+ Aliases such as `func = another_func` are reported by Jedi as a `statement`
+ with no docstring of their own, so we infer the assignment to surface the
+ docstring and signature of the function/class/module it points at.
+
+ Only an unambiguous, single definition is resolved; multiple candidates
+ (e.g. a conditional assignment) would mean guessing which docs to show, so
+ we defer to the type hint instead.
+ """
+ try:
+ inferred = completion.infer()
+ except Exception:
+ return None
+ documentable = [d for d in inferred if d.type in _DOCUMENTABLE_TYPES]
+ if len(documentable) == 1:
+ return documentable[0]
+ return None
+
+
def _get_completion_info(completion: jedi.api.classes.BaseName) -> str:
- if completion.type != "statement":
- try:
- return _get_docstring(completion)
- except Exception as e:
- LOGGER.debug("jedi failed to get docstring: %s", str(e))
- return ""
- else:
- try:
+ try:
+ if completion.type == "statement":
+ definition = _resolve_aliased_definition(completion)
+ # Fall back to the type hint when the alias has no resolvable
+ # definition, or when its docstring comes back empty.
+ if definition is not None:
+ docstring = _get_docstring(definition)
+ if docstring:
+ return docstring
return _get_type_hint(completion)
- except Exception as e:
- LOGGER.debug("jedi failed to get type hint: %s", str(e))
- return ""
+ return _get_docstring(completion)
+ except Exception as e:
+ LOGGER.debug("jedi failed to get completion info: %s", str(e))
+ return ""
def _get_completion_option(
diff --git a/tests/_runtime/test_complete.py b/tests/_runtime/test_complete.py
index a0b9cb4290..e33ba7e04c 100644
--- a/tests/_runtime/test_complete.py
+++ b/tests/_runtime/test_complete.py
@@ -20,6 +20,7 @@ from marimo._messaging.types import KernelMessage, Stream
from marimo._runtime.commands import CodeCompletionCommand
from marimo._runtime.complete import (
_build_docstring_cached,
+ _get_completion_info,
_get_completion_option,
_get_completion_options,
_get_docstring,
@@ -717,8 +718,8 @@ def test_resolve_chained_key_path(
class _FakeCompletion:
"""Stand-in for jedi.api.classes.Completion.
- Tracks whether `type` was accessed so we can assert we didn't pay the
- (expensive) jedi inference cost in the fast path.
+ Tracks whether `type` was accessed and how often `infer()` ran so we can
+ assert we didn't pay the (expensive) jedi inference cost in the fast path.
"""
def __init__(
@@ -726,12 +727,15 @@ class _FakeCompletion:
name: str,
completion_type: str = "function",
raise_on_type: bool = False,
+ inferred: list[Any] | None = None,
) -> None:
self.name = name
self._type = completion_type
self._raise_on_type = raise_on_type
+ self._inferred = inferred or []
self.type_access_count = 0
self.docstring_called = False
+ self.infer_count = 0
@property
def type(self) -> str:
@@ -746,6 +750,16 @@ class _FakeCompletion:
self.docstring_called = True
return ""
+ def get_signatures(self) -> list[Any]:
+ return []
+
+ def get_type_hint(self) -> str:
+ return "int"
+
+ def infer(self) -> list[Any]:
+ self.infer_count += 1
+ return self._inferred
+
def test_get_completion_option_skips_type_when_compute_type_false() -> None:
completion = _FakeCompletion("foo", raise_on_type=True)
@@ -869,3 +883,158 @@ def test_get_completion_options_respects_prefix_filter() -> None:
)
assert [opt.name for opt in options] == ["public"]
+
+
+def _completion_for(code: str, name: str) -> Any:
+ """Return the Jedi completion named `name` at the end of `code`."""
+ script = jedi.Script(code=code)
+ lines = code.split("\n")
+ completions = script.complete(line=len(lines), column=len(lines[-1]))
+ matches = [c for c in completions if c.name == name]
+ assert matches, (
+ f"no completion named {name!r}; got {[c.name for c in completions]}"
+ )
+ return matches[0]
+
+
+def test_completion_info_resolves_aliased_function() -> None:
+ """Aliases to a function show the underlying docstring + signature.
+
+ Regression test for #9822: `alias = func` is reported by Jedi as a
+ `statement`, which previously fell through to a bare type hint, dropping
+ the docstring and signature highlighting in live docs / hover.
+ """
+ code = (
+ "def my_documented_func(arg: int) -> None:\n"
+ ' """Docstring for the aliased function."""\n'
+ " print(arg)\n"
+ "\n"
+ "alias = my_documented_func\n"
+ "alias"
+ )
+ completion = _completion_for(code, "alias")
+ assert completion.type == "statement"
+
+ info = _get_completion_info(completion)
+ assert "Docstring for the aliased function." in info
+ # Signature is rendered as a highlighted python code block.
+ assert "codehilite" in info
+ assert "my_documented_func" in info
+
+
+def test_completion_info_resolves_aliased_class() -> None:
+ code = (
+ "class MyDocumentedClass:\n"
+ ' """Docstring for the aliased class."""\n'
+ "\n"
+ "Alias = MyDocumentedClass\n"
+ "Alias"
+ )
+ completion = _completion_for(code, "Alias")
+ assert completion.type == "statement"
+
+ info = _get_completion_info(completion)
+ assert "Docstring for the aliased class." in info
+
+
+def test_completion_info_plain_value_statement_uses_type_hint() -> None:
+ """Statements resolving to plain values keep the type-hint fallback rather
+ than surfacing a builtin's docstring."""
+ code = "answer = 42\nanswer"
+ completion = _completion_for(code, "answer")
+ assert completion.type == "statement"
+
+ info = _get_completion_info(completion)
+ assert info == "answer: int"
+ assert "codehilite" not in info
+
+
+def test_completion_info_ambiguous_alias_falls_back_to_type_hint() -> None:
+ """When `infer()` resolves to multiple definitions (e.g. a conditional
+ assignment), don't guess a docstring — defer to the type hint."""
+ code = (
+ "import random\n"
+ "\n"
+ "def foo(a: int) -> int:\n"
+ ' """Foo docstring."""\n'
+ " return a\n"
+ "\n"
+ "def bar(b: str) -> str:\n"
+ ' """Bar docstring."""\n'
+ " return b\n"
+ "\n"
+ "chosen = foo if random.random() > 0.5 else bar\n"
+ "chosen"
+ )
+ completion = _completion_for(code, "chosen")
+ assert completion.type == "statement"
+
+ info = _get_completion_info(completion)
+ assert info.startswith("chosen: ")
+ assert "Foo docstring." not in info
+ assert "Bar docstring." not in info
+ assert "codehilite" not in info
+
+
+def test_infer_skipped_for_statements_past_limit() -> None:
+ """The docstring limit must prevent `.infer()` fan-out.
+
+ Aliased-statement resolution calls `jedi`'s `infer()`, which "follows all
+ results" and is very slow across large completion sets (e.g. `np.`). The
+ `len(completions) <= limit` gate has to keep us out of that path entirely.
+ """
+ completions = [
+ _FakeCompletion(f"v{i}", completion_type="statement")
+ for i in range(10)
+ ]
+
+ _get_completion_options(
+ completions, mock.MagicMock(), prefix="", limit=5, timeout=5.0
+ )
+
+ assert all(c.infer_count == 0 for c in completions)
+
+
+def test_infer_only_runs_for_statements_under_budget() -> None:
+ """Within budget, only statement completions infer (once each); other
+ types go straight to `_get_docstring` and never touch `infer()`."""
+ statements = [
+ _FakeCompletion(f"s{i}", completion_type="statement") for i in range(3)
+ ]
+ functions = [
+ _FakeCompletion(f"f{i}", completion_type="function") for i in range(3)
+ ]
+
+ _get_completion_options(
+ statements + functions,
+ mock.MagicMock(),
+ prefix="",
+ limit=100,
+ timeout=5.0,
+ )
+
+ assert all(c.infer_count == 1 for c in statements)
+ assert all(c.infer_count == 0 for c in functions)
+
+
+def test_infer_skipped_once_timeout_elapsed() -> None:
+ """Once the time budget is blown, remaining statements skip `.infer()`
+ just like they skip type/docstring inference."""
+ completions = [
+ _FakeCompletion(f"v{i}", completion_type="statement") for i in range(4)
+ ]
+
+ original_monotonic = time.monotonic
+ times = iter([0.0, 0.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0])
+
+ with mock.patch(
+ "marimo._runtime.complete.time.monotonic",
+ side_effect=lambda: next(times, original_monotonic()),
+ ):
+ _get_completion_options(
+ completions, mock.MagicMock(), prefix="", limit=100, timeout=1.0
+ )
+
+ # First completion is under budget and infers; the rest are skipped.
+ assert completions[0].infer_count == 1
+ assert all(c.infer_count == 0 for c in completions[1:])