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
jedi: resolve definitions and get docstring (#9838)
Shahmir Varqha9c586ebd1771
diff --git a/marimo/_runtime/complete.py b/marimo/_runtime/complete.pyindex 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 docstringreturn _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.pyindex 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, Streamfrom marimo._runtime.commands import CodeCompletionCommandfrom 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 = nameself._type = completion_typeself._raise_on_type = raise_on_type+ self._inferred = inferred or []self.type_access_count = 0self.docstring_called = False+ self.infer_count = 0@propertydef type(self) -> str:@@ -746,6 +750,16 @@ class _FakeCompletion:self.docstring_called = Truereturn ""+ 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:])