🐛 fix(stubs): resolve stub imports for type hint evaluation (#654)

When stub annotations reference types only imported in the `.pyi` file
(e.g., `Sequence`, `Optional`, `Callable`), `get_type_hints()` raises
`NameError` because those names aren't in the runtime module's
namespace. The fallback returns raw strings, and `format_annotation()`
can't create cross-reference links — so rendered docs show plain text
with no hyperlinks for any non-builtin type from a stub. 🐛 This is the
issue @agronholm identified in #652.

The fix extracts the stub's top-level import statements from the AST,
resolves them via `importlib.import_module`, and passes the resulting
namespace as `localns` to `get_type_hints()`. This complements the
runtime module's `__dict__` (which already provides self-references and
cross-class refs defined in the module) with the stub-specific imports
needed for evaluation.

### Why not `eval` the AST annotation nodes directly?

We investigated using `eval(compile(ast.Expression(body=annotation),
...))` instead of `ast.unparse` + `get_type_hints()`. This fails on the
most common cases because class definitions in the stub aren't imports —
they're AST nodes with no corresponding object in the eval namespace:

| Scenario | `eval` | string + `get_type_hints()` |
|---|---|---|
| Self-reference (`Foo.method() -> Foo`) | `NameError` | Works via
runtime `__dict__` |
| Cross-class ref (`Bar.get_foo() -> Foo`) | `NameError` | Works |
| Compound (`Optional[Foo]`) | `NameError` | Works |
| Forward ref (class defined later in stub) | `NameError` | Works |

### How other tools handle this

- **pdoc** imports the entire `.pyi` as a Python module via
[`SourceFileLoader`](https://github.com/mitmproxy/pdoc/blob/main/pdoc/doc_pyi.py)
— creates real objects but shadows runtime classes, breaking Sphinx's
ability to link to the documented types
- **griffe** builds a custom [expression
tree](https://github.com/mkdocstrings/griffe/blob/main/src/_griffe/expressions.py)
from AST nodes, reimplementing all name resolution independently of
Python's runtime — effective but massive complexity for our use case
- **sphinx autodoc** (built-in) had no native stub support for C
extensions until
[v8.2.0](sphinx-doc/sphinx#13253) (see
[#7630](sphinx-doc/sphinx#7630))

No standalone library exists for "resolve stub imports into a namespace"
— the operation is ~20 lines of `importlib.import_module` + `getattr`,
and every tool that needs it has different requirements. Our
implementation keeps it minimal and focused.

Author: gaborbernat

pyproject.toml

@@ -134,6 +134,9 @@ lint.per-file-ignores."tests/roots/test-pyi-stubs/stub_mod.py" = [
   "PLR6301", # method must be instance method to test stub resolution
   "RUF029",  # async function must be async to test async stub resolution
 ]
+lint.per-file-ignores."tests/roots/test-pyi-stubs/stub_mod.pyi" = [
+  "I002", # stub files don't use `from __future__ import annotations`
+]
 lint.per-file-ignores."tests/test_resolver/test_type_comments.py" = [
   "ANN001", # type comment fixtures intentionally omit annotations
   "ARG001", # type comment fixtures have intentionally unused args

src/sphinx_autodoc_typehints/_resolver/_stubs.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import ast
+import contextlib
+import importlib
 import inspect
 from pathlib import Path
 from typing import Any
@@ -18,6 +20,37 @@ def _backfill_from_stub(obj: Any) -> dict[str, str]:
     return {}
 
 
+def _get_stub_localns(obj: Any) -> dict[str, Any]:
+    if (stub_path := _find_stub_path(obj)) and (tree := _parse_stub_ast(stub_path)):
+        return _resolve_stub_imports(tree)
+    return {}
+
+
+def _resolve_stub_imports(tree: ast.Module) -> dict[str, Any]:
+    ns: dict[str, Any] = {}
+    for node in tree.body:
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                with contextlib.suppress(ImportError):
+                    if alias.asname:
+                        ns[alias.asname] = importlib.import_module(alias.name)
+                    else:
+                        top = alias.name.split(".")[0]
+                        ns[top] = importlib.import_module(top)
+        elif isinstance(node, ast.ImportFrom) and node.module:
+            try:
+                mod = importlib.import_module(node.module)
+            except ImportError:
+                continue
+            for alias in node.names:
+                if alias.name == "*":
+                    continue
+                name = alias.asname or alias.name
+                if (val := getattr(mod, alias.name, None)) is not None:
+                    ns[name] = val
+    return ns
+
+
 def _find_stub_path(obj: Any) -> Path | None:
     if (module := inspect.getmodule(obj)) is None:
         return None

src/sphinx_autodoc_typehints/_resolver/_type_hints.py

@@ -13,7 +13,7 @@
 from sphinx.ext.autodoc.mock import mock
 from sphinx.util import logging
 
-from ._stubs import _backfill_from_stub
+from ._stubs import _backfill_from_stub, _get_stub_localns
 from ._type_comments import backfill_type_hints
 from ._util import get_obj_location
 
@@ -45,14 +45,17 @@ def get_all_type_hints(
     result = _get_type_hint(autodoc_mock_imports, name, obj, localns)
     if not result:
         result = backfill_type_hints(obj, name)
+        stub_localns: dict[str, Any] = {}
         if not result:
             result = _backfill_from_stub(obj)
+            if result:
+                stub_localns = _get_stub_localns(obj)
         try:
             obj.__annotations__ = result
         except (AttributeError, TypeError):
             pass
         else:
-            result = _get_type_hint(autodoc_mock_imports, name, obj, localns)
+            result = _get_type_hint(autodoc_mock_imports, name, obj, {**localns, **stub_localns})
     return result
 
 

tests/roots/test-pyi-stubs/conf.py

@@ -9,6 +9,9 @@
 
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx_autodoc_typehints",
 ]
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}

tests/roots/test-pyi-stubs/index.rst

@@ -1,2 +1,7 @@
-Test
-====
+
+.. autofunction:: stub_mod.greet
+
+.. autoclass:: stub_mod.Calculator
+   :members:
+
+.. autofunction:: stub_mod.fetch

tests/roots/test-pyi-stubs/stub_mod.py

@@ -19,3 +19,7 @@ def process(self, data):
 
 async def fetch(url):
     return url
+
+
+def transform(value):
+    return value

tests/roots/test-pyi-stubs/stub_mod.pyi

@@ -1,3 +1,5 @@
+from collections.abc import Sequence
+
 def greet(name: str, greeting: str) -> str: ...
 
 class Calculator:
@@ -7,3 +9,4 @@ class Calculator:
         def process(self, data: bytes) -> bytes: ...
 
 async def fetch(url: str) -> str: ...
+def transform(value: Sequence[int]) -> list[str]: ...

tests/test_resolver/test_stubs.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
 import ast
+import os
 import sys
 import types
+from collections.abc import Sequence
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Optional
 from unittest.mock import MagicMock, patch
 
 import pytest
@@ -18,7 +20,9 @@
     _extract_func_annotations,
     _find_ast_node,
     _find_stub_path,
+    _get_stub_localns,
     _parse_stub_ast,
+    _resolve_stub_imports,
 )
 
 if TYPE_CHECKING:
@@ -285,6 +289,7 @@ def test_extract_annotations_from_stub_no_qualname() -> None:
         pytest.param("greet", {"name": "str", "greeting": "str", "return": "str"}, id="function"),
         pytest.param("Calculator.Inner.process", {"data": "bytes", "return": "bytes"}, id="nested_class"),
         pytest.param("fetch", {"url": "str", "return": "str"}, id="async_function"),
+        pytest.param("transform", {"value": "Sequence[int]", "return": "list[str]"}, id="typing_imports"),
     ],
 )
 def test_backfill_from_stub(stub_mod: Any, attr: str, expected: dict[str, str]) -> None:
@@ -298,6 +303,36 @@ def test_backfill_from_stub_no_stub() -> None:
     assert _backfill_from_stub(test_backfill_from_stub_no_stub) == {}
 
 
+@pytest.mark.parametrize(
+    ("source", "expected"),
+    [
+        pytest.param("import os\nimport sys\n", {"os": os, "sys": sys}, id="basic_import"),
+        pytest.param("import os as operating_system\n", {"operating_system": os}, id="import_as"),
+        pytest.param("import os.path\n", {"os": os}, id="dotted_import"),
+        pytest.param("from typing import Optional, Any\n", {"Optional": Optional, "Any": Any}, id="from_import"),
+        pytest.param("from typing import Optional as Opt\n", {"Opt": Optional}, id="from_import_as"),
+        pytest.param("from typing import *\n", {}, id="star_import_skipped"),
+        pytest.param("import nonexistent_xyz\nfrom nonexistent_abc import Foo\n", {}, id="missing_module_skipped"),
+        pytest.param("from typing import NonExistentThing\n", {}, id="missing_attr_skipped"),
+    ],
+)
+def test_resolve_stub_imports(source: str, expected: dict[str, Any]) -> None:
+    ns = _resolve_stub_imports(ast.parse(source))
+    for key, val in expected.items():
+        assert ns[key] is val
+    if not expected:
+        assert ns == {}
+
+
+def test_get_stub_localns_returns_imports(stub_mod: Any) -> None:
+    ns = _get_stub_localns(stub_mod.transform)
+    assert ns["Sequence"] is Sequence
+
+
+def test_get_stub_localns_returns_empty_for_no_stub() -> None:
+    assert _get_stub_localns(test_get_stub_localns_returns_empty_for_no_stub) == {}
+
+
 @pytest.mark.sphinx("text", testroot="pyi-stubs")
 def test_sphinx_build_uses_stub_types(app: SphinxTestApp, status: StringIO, warning: StringIO) -> None:
     template = """\
@@ -307,11 +342,28 @@ def test_sphinx_build_uses_stub_types(app: SphinxTestApp, status: StringIO, warn
    :members:
 
 .. autofunction:: stub_mod.fetch
+
+.. autofunction:: stub_mod.transform
 """
     (Path(app.srcdir) / "index.rst").write_text(template)
     app.build()
     assert "build succeeded" in status.getvalue()
     result = normalize_sphinx_text((Path(app.srcdir) / "_build/text/index.txt").read_text())
     assert "str" in result
+    assert "list" in result
     warn_text = warning.getvalue()
     assert "stub_mod" not in warn_text or "forward reference" not in warn_text
+    sys.modules.pop("stub_mod", None)
+
+
+@pytest.mark.sphinx("pseudoxml", testroot="pyi-stubs")
+def test_sphinx_build_stub_types_produce_crossrefs(app: SphinxTestApp, status: StringIO) -> None:
+    template = """\
+.. autofunction:: stub_mod.transform
+"""
+    (Path(app.srcdir) / "index.rst").write_text(template)
+    app.build()
+    assert "build succeeded" in status.getvalue()
+    result = (Path(app.srcdir) / "_build/pseudoxml/index.pseudoxml").read_text()
+    assert 'classes="xref py py-class"' in result
+    assert "docs.python.org" in result