🐛 fix(resolver): resolve NamedTuple hints from class (#657)

Fixes #656

NamedTuples with non-builtin type annotations (e.g. `Path`) combined
with `from __future__ import annotations` produce spurious "Cannot
resolve forward reference" warnings since 3.9.6. 🐛 This happens because
the `__new__` method generated for NamedTuples has its `__module__` set
to a synthetic name like `namedtuple_Program` that doesn't exist in
`sys.modules`, so `typing.get_type_hints()` can't resolve the
stringified annotations.

The fix passes the original class to `get_all_type_hints()` instead of
`__new__` when dealing with NamedTuple-style classes (custom `__new__`,
inherited `__init__`). The class has the correct `__module__` pointing
to the real module where the imports live, while `__new__` continues to
be used for signature extraction as intended by the 3.9.6 C extension
support change.

Author: gaborbernat

src/sphinx_autodoc_typehints/__init__.py

@@ -152,9 +152,11 @@ def process_docstring(  # noqa: PLR0913, PLR0917
     if inspect.isclass(obj):
         backfill_attrs_annotations(obj)
     use_class_for_signature = False
+    cls_for_hints = None
     if inspect.isclass(obj):
         if obj.__init__ is object.__init__ and obj.__new__ is not object.__new__:
             use_class_for_signature = True
+            cls_for_hints = obj
             obj = obj.__new__
         else:
             obj = obj.__init__
@@ -176,7 +178,7 @@ def process_docstring(  # noqa: PLR0913, PLR0917
     if (env := getattr(app, "env", None)) is not None:
         deferred, eager_aliases = collect_documented_type_aliases(obj, module_prefix, env)
         localns.update(deferred)
-    type_hints = get_all_type_hints(app.config.autodoc_mock_imports, obj, name, localns)
+    type_hints = get_all_type_hints(app.config.autodoc_mock_imports, cls_for_hints or obj, name, localns)
     for param, hint in type_hints.items():
         if id(hint) in eager_aliases:
             type_hints[param] = eager_aliases[id(hint)]

tests/roots/test-dummy/dummy_module.py

@@ -1,7 +1,10 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import NamedTuple
+from typing import TYPE_CHECKING, NamedTuple
+
+if TYPE_CHECKING:
+    from pathlib import Path
 
 
 def undocumented_function(x: int) -> str:
@@ -23,6 +26,13 @@ class MyNamedTuple(NamedTuple):
     y: str = "hello"
 
 
+class MyNamedTupleWithPath(NamedTuple):
+    """A named tuple with non-builtin types."""
+
+    path: Path
+    version: str
+
+
 @dataclass
 class DataClass:
     """Class docstring."""

tests/test_sphinx_autodoc_typehints.py

@@ -166,6 +166,25 @@ def test_namedtuple_new_no_warning(
     assert "NoneType" not in warning.getvalue()
 
 
+@pytest.mark.sphinx("text", testroot="dummy")
+def test_namedtuple_no_forward_ref_warning(
+    app: SphinxTestApp,
+    status: StringIO,
+    warning: StringIO,
+    write_rst: Callable[[str], None],
+) -> None:
+    """Regression test for #656: NamedTuple forward reference resolution fails."""
+    write_rst("""\
+        .. autoclass:: dummy_module.MyNamedTupleWithPath
+            :undoc-members:
+    """)
+
+    app.build()
+
+    assert "build succeeded" in status.getvalue()
+    assert "Cannot resolve forward reference" not in warning.getvalue()
+
+
 @pytest.mark.sphinx("text", testroot="dummy")
 def test_sphinx_output_future_annotations(app: SphinxTestApp, status: StringIO) -> None:
     app.config.master_doc = "future_annotations"  # create flag