🐛 fix(annotations): expand aliases from unread modules (#765)

Author: gaborbernat

src/sphinx_autodoc_typehints/__init__.py

@@ -6,6 +6,7 @@
 import re
 import types
 from contextlib import contextmanager
+from functools import partial
 from typing import TYPE_CHECKING, Any, TypeVar
 
 from docutils import nodes
@@ -36,6 +37,7 @@
     get_descriptor_type_hint,
     get_instance_var_annotations,
     get_obj_location,
+    resolve_type_guarded_imports,
 )
 from .patches import _OVERLOADS_CACHE, install_patches
 from .version import __version__
@@ -203,6 +205,7 @@ def process_docstring(  # ruff:ignore[too-many-arguments, too-many-positional-ar
         _annotation_globals=getattr(obj, "__globals__", {}),
         _typehints_env=env,
         _typehints_module_prefix=module_prefix,
+        _typehints_resolve_guarded_imports=partial(resolve_type_guarded_imports, app.config.autodoc_mock_imports),
     ):
         has_overloads = _inject_overload_signatures(app, what, name, obj, lines)
         _inject_types_to_docstring(type_hints, signature, original_obj, app, what, name, lines, has_overloads)

src/sphinx_autodoc_typehints/_annotations.py

@@ -171,6 +171,8 @@ def _format_node(  # ruff:ignore[complex-structure, too-many-return-statements,
     if isinstance(annotation, TypeAliasType):
         if (crossref := _type_alias_crossref(annotation, config)) is not None:
             return crossref
+        if not _can_expand_alias(annotation, config):
+            return _alias_name_reference(annotation, config)
         return (yield annotation.__value__)
 
     if isinstance(alias := get_origin(annotation), TypeAliasType | TypeAliasForwardRef):
@@ -182,9 +184,9 @@ def _format_node(  # ruff:ignore[complex-structure, too-many-return-statements,
             rendered_alias = yield alias
         elif (crossref := _type_alias_crossref(alias, config)) is not None:
             rendered_alias = crossref
-        elif _matches_type_params(alias, args):  # an undocumented alias: expand its value, with args substituted
+        elif _matches_type_params(alias, args) and _can_expand_alias(alias, config):  # undocumented: expand its value
             return (yield _substitute_type_params(alias, args))
-        else:  # a wrong-arity subscript cannot expand, so name the alias instead of leaking its type params
+        else:  # cannot expand, so name the alias instead of leaking its type params
             rendered_alias = _alias_name_reference(alias, config)
         parts = []
         for arg in args:
@@ -390,6 +392,30 @@ def _underlying_type_alias(annotation: Any) -> TypeAliasType | None:
     return None
 
 
+def _can_expand_alias(alias: TypeAliasType, config: Config) -> bool:
+    """
+    Whether the alias' lazily evaluated value is available.
+
+    A module reached only through an annotation has not had its ``if TYPE_CHECKING`` block executed, so the names
+    the value uses can still be missing; run that block before giving up, so what we render does not depend on the
+    order Sphinx reads modules in (#764).
+    """
+    if _alias_value_evaluates(alias):
+        return True
+    if (resolve_guarded_imports := getattr(config, "_typehints_resolve_guarded_imports", None)) is None:
+        return False
+    resolve_guarded_imports(inspect.getmodule(alias))
+    return _alias_value_evaluates(alias)
+
+
+def _alias_value_evaluates(alias: TypeAliasType) -> bool:
+    try:
+        _ = alias.__value__
+    except NameError:
+        return False
+    return True
+
+
 def _matches_type_params(alias: TypeAliasType, args: tuple[Any, ...]) -> bool:
     """Whether ``args`` can be substituted: the runtime accepts a wrong-arity subscript, so check it here."""
     params = alias.__type_params__

src/sphinx_autodoc_typehints/_resolver/__init__.py

@@ -5,7 +5,7 @@
 from ._attrs import backfill_attrs_annotations
 from ._instance_vars import get_instance_var_annotations
 from ._type_comments import backfill_type_hints
-from ._type_hints import get_all_type_hints, get_descriptor_type_hint
+from ._type_hints import get_all_type_hints, get_descriptor_type_hint, resolve_type_guarded_imports
 from ._util import collect_documented_type_aliases, get_obj_location
 
 __all__ = [
@@ -16,4 +16,5 @@
     "get_descriptor_type_hint",
     "get_instance_var_annotations",
     "get_obj_location",
+    "resolve_type_guarded_imports",
 ]

src/sphinx_autodoc_typehints/_resolver/_type_hints.py

@@ -127,7 +127,7 @@ def _resolve_string_annotations(
 
 
 def _get_type_hint(autodoc_mock_imports: list[str], name: str, obj: Any, localns: Mapping[str, Any]) -> dict[str, Any]:
-    _resolve_type_guarded_imports(autodoc_mock_imports, obj)
+    resolve_type_guarded_imports(autodoc_mock_imports, obj)
     localns = _build_localns(obj, localns)
     try:
         if getattr(obj, "__no_type_check__", False):
@@ -171,7 +171,8 @@ def _get_forward_ref_annotations(obj: Any) -> dict[str, Any]:  # pragma: >=3.14
         return {}
 
 
-def _resolve_type_guarded_imports(autodoc_mock_imports: list[str], obj: Any) -> None:
+def resolve_type_guarded_imports(autodoc_mock_imports: list[str], obj: Any) -> None:
+    """Execute the ``if TYPE_CHECKING`` block of *obj*'s module, binding the names it guards."""
     if _should_skip_guarded_import_resolution(obj):
         return
 
@@ -189,7 +190,7 @@ def _resolve_type_guarded_imports(autodoc_mock_imports: list[str], obj: Any) ->
 
 def _should_skip_guarded_import_resolution(obj: Any) -> bool:
     if isinstance(obj, types.ModuleType):
-        return False
+        return obj.__name__ in _TYPE_GUARD_IMPORTS_RESOLVED
 
     if not hasattr(obj, "__globals__"):
         return True
@@ -260,7 +261,7 @@ def _run_guarded_import(autodoc_mock_imports: list[str], obj: Any, guarded_code:
     except ImportError as exc:
         if not exc.name:
             return
-        _resolve_type_guarded_imports(autodoc_mock_imports, importlib.import_module(exc.name))
+        resolve_type_guarded_imports(autodoc_mock_imports, importlib.import_module(exc.name))
         try:
             with mock(autodoc_mock_imports):
                 exec(guarded_code, ns)  # ruff:ignore[exec-builtin]
@@ -303,4 +304,7 @@ def _future_annotations_imported(obj: Any) -> bool:
     return bool(annotations_.compiler_flag == 0x1000000)  # ruff:ignore[magic-value-comparison]
 
 
-__all__ = ["get_all_type_hints"]
+__all__ = [
+    "get_all_type_hints",
+    "resolve_type_guarded_imports",
+]

tests/test_pep695.py

@@ -574,6 +574,90 @@ def some_func(some_param: RecType) -> None:
     assert '"int" | "list"["RecType"]' in result
 
 
+@pytest.mark.parametrize(
+    ("package", "alias", "annotation", "expected"),
+    [
+        pytest.param(
+            "pkg_764",
+            "type Alias = int | Sequence[str]",
+            "Alias | None",
+            '"int" | "Sequence"["str"] | "None"',
+            id="plain",
+        ),
+        pytest.param(
+            "pkg_764_generic",
+            "type Alias[T] = Sequence[T]",
+            "Alias[int]",
+            '"Sequence"["int"]',
+            id="generic",
+        ),
+    ],
+)
+@pytest.mark.sphinx("text", testroot="integration")
+def test_type_alias_value_needs_guarded_import(
+    app: SphinxTestApp,
+    status: StringIO,
+    warning: StringIO,
+    monkeypatch: pytest.MonkeyPatch,
+    package: str,
+    alias: str,
+    annotation: str,
+    expected: str,
+) -> None:
+    """An alias expands even when its value needs the guarded imports of the module defining it (#764)."""
+    pkg = Path(app.srcdir) / package
+    pkg.mkdir()
+    (pkg / "__init__.py").touch()
+    (pkg / "_types.py").write_text(
+        dedent(f"""\
+        from __future__ import annotations
+
+        from typing import TYPE_CHECKING
+
+        if TYPE_CHECKING:
+            from collections.abc import Sequence
+
+        {alias}
+        """)
+    )
+    (pkg / "api.py").write_text(
+        dedent(f"""\
+        from __future__ import annotations
+
+        from typing import TYPE_CHECKING
+
+        if TYPE_CHECKING:
+            from ._types import Alias
+
+
+        def f(x: {annotation}) -> None:
+            \"\"\"Do nothing.
+
+            :param x: an argument.
+            \"\"\"
+        """)
+    )
+    (Path(app.srcdir) / "index.rst").write_text(f".. autofunction:: {package}.api.f\n")
+    monkeypatch.syspath_prepend(str(app.srcdir))
+    app.build()
+    assert "build succeeded" in status.getvalue()
+    assert not warning.getvalue().strip()
+
+    result = normalize_sphinx_text((Path(app.srcdir) / "_build/text/index.txt").read_text())
+    assert expected in result
+
+
+_mod_unresolvable = types.ModuleType("mod_unresolvable")
+_mod_unresolvable.__file__ = __file__
+exec("type Broken = Missing\n", _mod_unresolvable.__dict__)  # ruff:ignore[exec-builtin]
+
+
+def test_alias_whose_value_never_evaluates_renders_as_its_name() -> None:
+    """An alias nothing can evaluate falls back to a reference to its own name (#764)."""
+    formatted = format_annotation(_mod_unresolvable.Broken, create_autospec(Config))
+    assert formatted == ":py:type:`~mod_unresolvable.Broken`"
+
+
 @pytest.mark.sphinx("text", testroot="integration")
 def test_eager_annotations(
     app: SphinxTestApp,

tests/test_resolver/test_type_hints.py

@@ -29,18 +29,18 @@
     _future_annotations_imported,
     _get_type_hint,
     _resolve_string_annotations,
-    _resolve_type_guarded_imports,
     _run_guarded_import,
     _should_skip_guarded_import_resolution,
     get_all_type_hints,
     get_descriptor_type_hint,
+    resolve_type_guarded_imports,
 )
 
 STUB_ROOT = Path(__file__).parent.parent / "roots" / "test-pyi-stubs"
 
 
 def test_no_source_code_type_guard() -> None:
-    _resolve_type_guarded_imports([], Error)
+    resolve_type_guarded_imports([], Error)
 
 
 def test_future_annotations_not_imported() -> None: