🐛 fix(resolver): survive PEP 649 lazy annotation evaluation errors (#713)

Documenting a function annotated with a non-subscriptable generic such
as `DiGraph[int]` from `networkx` crashes the whole Sphinx build on
Python 3.14. PEP 649 makes annotations lazy, so the module imports fine,
but the first `__annotations__` access runs `__annotate__` and the
`TypeError` from the annotation expression escapes through
`process_signature`. The existing guards only caught the `NameError`
raised by `TYPE_CHECKING`-only names.

The guards in `process_signature` and `collect_documented_type_aliases`
now cover the errors annotation expressions raise at runtime:
`NameError`, `TypeError` and `AttributeError`. 🛟 When
`typing.get_type_hints` raises `TypeError`, the resolver retries with
`annotationlib`'s `FORWARDREF` format, which wraps unevaluatable
expressions in `ForwardRef` proxies, so the parameter still renders as
its source text (`g (DiGraph[int])`) instead of being dropped.
`RecursionError` keeps returning no hints because re-evaluating after a
recursion blowup is unsafe.

Behavior on Python 3.13 and earlier is unchanged; eager annotation
evaluation raises at import time there, before this code runs.

Fixes #712.

Author: gaborbernat

src/sphinx_autodoc_typehints/__init__.py

@@ -67,11 +67,10 @@ def process_signature(  # noqa: C901, PLR0911, PLR0912, PLR0913, PLR0917
     obj = getattr(obj, "__init__", getattr(obj, "__new__", None)) if inspect.isclass(obj) else obj
     try:
         has_annotations = getattr(obj, "__annotations__", None)
-    except NameError:
-        # PEP 649 (Python 3.14+): accessing __annotations__ may raise NameError when annotations
-        # reference TYPE_CHECKING-only names. Setting __annotations__ clears __annotate__, so we
-        # only reach here when annotations come from the original function definition. If __annotate__
-        # is callable, the function has annotations; proceed so sphinx_signature can use FORWARDREF.
+    except (NameError, TypeError, AttributeError):
+        # PEP 649 (Python 3.14+): annotation expressions only run on access and may fail at runtime
+        # (TYPE_CHECKING-only names, subscripting a non-generic class). __annotate__ still signals
+        # annotations exist, and sphinx_signature renders them without evaluation via FORWARDREF.
         has_annotations = getattr(obj, "__annotate__", None)
     if not has_annotations:
         return None

src/sphinx_autodoc_typehints/_resolver/_type_hints.py

@@ -121,6 +121,8 @@ def _get_type_hint(
             isinstance(exc, TypeError) and _future_annotations_imported(obj) and "unsupported operand type" in str(exc)
         ):  # pragma: <3.14 cover
             result = obj.__annotations__
+        elif isinstance(exc, TypeError) and sys.version_info >= (3, 14):  # pragma: >=3.14 cover
+            result = _get_forward_ref_annotations(obj)
         else:
             result = {}
     except NameError as exc:
@@ -140,6 +142,14 @@ def _get_type_hint(
     return result
 
 
+def _get_forward_ref_annotations(obj: Any) -> dict[str, Any]:  # pragma: >=3.14 cover
+    # ForwardRef proxies keep unevaluatable annotations renderable as their source text — see #712
+    try:
+        return annotationlib.get_annotations(obj, format=annotationlib.Format.FORWARDREF)
+    except (NameError, TypeError, AttributeError, RecursionError):
+        return {}
+
+
 def _resolve_type_guarded_imports(autodoc_mock_imports: list[str], obj: Any) -> None:
     if _should_skip_guarded_import_resolution(obj):
         return

src/sphinx_autodoc_typehints/_resolver/_util.py

@@ -31,11 +31,11 @@ def collect_documented_type_aliases(
     deferred = _collect_module_type_aliases(module_prefix, py_objects)
     eager: dict[int, MyTypeAliasForwardRef] = {}
 
-    # In Python 3.14+, accessing __annotations__ evaluates lazy annotations (PEP 649) and
-    # may raise NameError for TYPE_CHECKING-only names before imports are resolved.
+    # PEP 649 (Python 3.14+): annotation expressions only run on access and may fail at runtime
+    # (TYPE_CHECKING-only names, subscripting a non-generic class)
     try:
         raw_annotations = getattr(obj, "__annotations__", {})
-    except NameError:
+    except (NameError, TypeError, AttributeError):
         return deferred, eager
     if not raw_annotations:
         return deferred, eager

tests/test_init.py

@@ -357,14 +357,21 @@ def test_process_docstring_trailing_underscore_param(
     assert any(line.startswith(":type ") and expected_type_name in line and "float" in line for line in lines)
 
 
-def test_process_signature_annotations_name_error() -> None:
-    """PEP 649 lazy annotations raising NameError must not propagate from process_signature."""
+@pytest.mark.parametrize(
+    "error",
+    [
+        pytest.param(NameError("Callable"), id="name-error"),
+        pytest.param(TypeError("type 'DiGraph' is not subscriptable"), id="type-error"),
+    ],
+)
+def test_process_signature_annotations_error(error: Exception) -> None:
+    """PEP 649 lazy annotation evaluation raising (NameError for TYPE_CHECKING-only names, TypeError
+    for subscripting a non-generic class) must not propagate from process_signature (issue #712)."""
 
     class _Func:
         @property
         def __annotations__(self) -> dict[str, object]:  # noqa: PLW3201
-            msg = "Callable"
-            raise NameError(msg)
+            raise error
 
         def __call__(self) -> None: ...
 

tests/test_pep695.py

@@ -534,3 +534,36 @@ def test_forward_ref_builds_without_errors(  # pragma: >=3.14 cover
     assert "build succeeded" in status.getvalue()
     result = normalize_sphinx_text((Path(app.srcdir) / "_build/text/index.txt").read_text())
     assert "Tree" in result
+
+
+@pytest.mark.skipif(sys.version_info < (3, 14), reason="PEP 649 lazy annotation evaluation is Python 3.14+")
+@pytest.mark.sphinx("text", testroot="integration")
+def test_non_subscriptable_generic_annotation(  # pragma: >=3.14 cover
+    app: SphinxTestApp,
+    status: StringIO,
+    warning: StringIO,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Regression test for #712: annotations whose lazy evaluation raises (here TypeError from
+    subscripting a non-generic class) must not crash the build; the hint degrades to its source text."""
+    mod = types.ModuleType("mod_712")
+    mod.__file__ = __file__
+    source = dedent("""\
+    class DiGraph:
+        pass
+
+
+    def add_node_between_nodes(g: DiGraph[int]) -> None:
+        \"\"\"Stub.\"\"\"
+    """)
+    # dont_inherit keeps this file's `from __future__ import annotations` (PEP 563) out of the
+    # compiled module so its annotations stay lazily evaluated (PEP 649)
+    exec(compile(source, "<mod_712>", "exec", dont_inherit=True), mod.__dict__)  # noqa: S102
+    (Path(app.srcdir) / "index.rst").write_text(".. autofunction:: mod_712.add_node_between_nodes")
+    monkeypatch.setitem(sys.modules, "mod_712", mod)
+    app.config.__dict__["always_document_param_types"] = True
+    app.build()
+    assert "build succeeded" in status.getvalue()
+    assert "threw an exception" not in warning.getvalue()
+    result = normalize_sphinx_text((Path(app.srcdir) / "_build/text/index.txt").read_text())
+    assert "DiGraph[int]" in result

tests/test_resolver/test_type_hints.py

@@ -66,6 +66,34 @@ def func(x: int) -> str: ...
         assert _get_type_hint([], "test", func, {}) == {}
 
 
+@pytest.fixture
+def non_subscriptable_generic_func() -> Any:  # pragma: >=3.14 cover
+    # dont_inherit keeps this file's `from __future__ import annotations` (PEP 563) out of the
+    # compiled module so its annotations stay lazily evaluated (PEP 649)
+    source = "class NotGeneric: ...\n\n\ndef func(g: NotGeneric[int]) -> None: ...\n"
+    ns: dict[str, Any] = {}
+    exec(compile(source, "<mod_712>", "exec", dont_inherit=True), ns)  # noqa: S102
+    return ns["func"]
+
+
+@pytest.mark.skipif(sys.version_info < (3, 14), reason="PEP 649 lazy annotation evaluation is Python 3.14+")
+def test_get_type_hint_unevaluatable_annotation_falls_back_to_forward_ref(
+    non_subscriptable_generic_func: Any,
+) -> None:  # pragma: >=3.14 cover
+    """Annotations whose evaluation raises TypeError degrade to ForwardRef proxies (issue #712)."""
+    result = _get_type_hint([], "test.func", non_subscriptable_generic_func, {})
+    assert result["g"].__forward_arg__ == "NotGeneric[int]"
+
+
+@pytest.mark.skipif(sys.version_info < (3, 14), reason="PEP 649 lazy annotation evaluation is Python 3.14+")
+def test_get_type_hint_forward_ref_fallback_failure_returns_empty(
+    non_subscriptable_generic_func: Any,
+) -> None:  # pragma: >=3.14 cover
+    """When even the FORWARDREF format cannot evaluate the annotations, fall back to no hints."""
+    with patch("sphinx_autodoc_typehints._resolver._type_hints.annotationlib.get_annotations", side_effect=TypeError):
+        assert _get_type_hint([], "test.func", non_subscriptable_generic_func, {}) == {}
+
+
 def test_execute_guarded_code_catches_exception() -> None:
     module = type("FakeModule", (), {"__globals__": {}, "__dict__": {}})()
     with patch("sphinx_autodoc_typehints._resolver._type_hints._run_guarded_import", side_effect=RuntimeError("boom")):

tests/test_resolver/test_util.py

@@ -3,6 +3,7 @@
 from typing import Any
 from unittest.mock import MagicMock, create_autospec, patch
 
+import pytest
 from sphinx.environment import BuildEnvironment
 
 from sphinx_autodoc_typehints._annotations import MyTypeAliasForwardRef
@@ -90,14 +91,21 @@ def test_collect_documented_type_aliases_ignores_unqualified_names() -> None:
     assert eager == {}
 
 
-def test_collect_documented_type_aliases_annotations_name_error() -> None:
-    """PEP 649 lazy annotations raising NameError must not propagate."""
+@pytest.mark.parametrize(
+    "error",
+    [
+        pytest.param(NameError("Callable"), id="name-error"),
+        pytest.param(TypeError("type 'DiGraph' is not subscriptable"), id="type-error"),
+    ],
+)
+def test_collect_documented_type_aliases_annotations_error(error: Exception) -> None:
+    """PEP 649 lazy annotation evaluation raising (NameError for TYPE_CHECKING-only names, TypeError
+    for subscripting a non-generic class) must not propagate (issue #712)."""
 
     class _AnnotationsRaiser:
         @property
         def __annotations__(self) -> dict[str, object]:  # noqa: PLW3201
-            msg = "Callable"
-            raise NameError(msg)
+            raise error
 
     env = _make_env_with_types(["mymod.MyType"])
     deferred, eager = collect_documented_type_aliases(_AnnotationsRaiser(), "mymod", env)