🐛 fix(resolver): resolve forward refs in nested attrs classes (#646)

Nested attrs classes that reference sibling types via their parent (e.g.
`Outer.Foo` inside `Outer.Bar`) fail with `NameError: name 'Outer' is
not defined` during Sphinx doc generation. 🐛 This happens because
attrs-generated `__init__` methods have `__globals__` pointing to attrs
internals rather than the defining module's namespace, so the parent
class can't be found for forward reference resolution.

The fix walks the full `__qualname__` chain using `inspect.getmodule` to
obtain the correct module namespace, resolving each ancestor class and
adding it to `localns`. This falls back to `obj.__globals__` for dynamic
modules where `inspect.getmodule` returns `None`, preserving
compatibility with PEP 695 type parameter resolution.

Fixes #643

Author: gaborbernat

src/sphinx_autodoc_typehints/_resolver/_type_hints.py

@@ -60,7 +60,7 @@ def _get_type_hint(
     autodoc_mock_imports: list[str], name: str, obj: Any, localns: dict[Any, MyTypeAliasForwardRef]
 ) -> dict[str, Any]:
     _resolve_type_guarded_imports(autodoc_mock_imports, obj)
-    localns = _add_type_params_to_localns(obj, localns)
+    localns = _build_localns(obj, localns)
     try:
         result = get_type_hints(obj, None, localns, include_extras=True)
     except (AttributeError, TypeError, RecursionError) as exc:
@@ -146,21 +146,26 @@ def _run_guarded_import(autodoc_mock_imports: list[str], obj: Any, guarded_code:
             pass
 
 
-def _add_type_params_to_localns(
-    obj: Any, localns: dict[Any, MyTypeAliasForwardRef]
-) -> dict[Any, MyTypeAliasForwardRef]:
+def _build_localns(obj: Any, localns: dict[Any, MyTypeAliasForwardRef]) -> dict[Any, MyTypeAliasForwardRef]:
     if type_params := getattr(obj, "__type_params__", None):
         localns = {**localns, **{p.__name__: p for p in type_params}}
-    qualname = getattr(obj, "__qualname__", "") or ""
-    parts = qualname.rsplit(".", 1)
-    if len(parts) > 1:
-        parent_name = parts[0]
-        ns = getattr(obj, "__globals__", None)
-        if ns is None:
-            module = inspect.getmodule(obj)
-            ns = vars(module) if module else None
-        if ns and (parent := ns.get(parent_name)) and (parent_params := getattr(parent, "__type_params__", None)):
-            localns = {**localns, **{p.__name__: p for p in parent_params}}
+    parts = (getattr(obj, "__qualname__", "") or "").split(".")
+    if len(parts) <= 1:
+        return localns
+    if ns := (vars(module) if (module := inspect.getmodule(obj)) else getattr(obj, "__globals__", None)):
+        current: Any = None
+        for part in parts[:-1]:
+            current = (
+                (ns if current is None else vars(current)).get(part)
+                if current is None or hasattr(current, "__dict__")
+                else None
+            )
+            if current is None:
+                break
+            if inspect.isclass(current):
+                localns = {**localns, part: current}
+            if ancestor_params := getattr(current, "__type_params__", None):
+                localns = {**localns, **{p.__name__: p for p in ancestor_params}}
     return localns
 
 

tests/roots/test-attrs/attrs_mod.py

@@ -27,3 +27,16 @@ class ModernAttrs:
 
     name: str
     age: int
+
+
+class Outer:
+    """A class with nested attrs classes to test forward reference resolution."""
+
+    class Foo:
+        """A nested class referenced by Bar."""
+
+    @attrs.define
+    class Bar:
+        """An attrs class referencing a sibling nested class."""
+
+        foo: Outer.Foo

tests/roots/test_nested_attrs_localns.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+
+class Outer:
+    class Inner:
+        def __init__(self) -> None: ...

tests/test_resolver/test_attrs.py

@@ -89,6 +89,24 @@ class NoAnnotations:
     assert NoAnnotations.__annotations__["x"] is int
 
 
+@pytest.mark.sphinx("text", testroot="attrs")
+def test_sphinx_build_nested_attrs_forward_ref(app: SphinxTestApp, status: StringIO, warning: StringIO) -> None:
+    template = """\
+.. autoclass:: attrs_mod.Outer
+   :members:
+   :undoc-members:
+
+.. autoclass:: attrs_mod.Outer.Bar
+   :members:
+   :undoc-members:
+"""
+    (Path(app.srcdir) / "index.rst").write_text(template)
+    app.build()
+    assert "build succeeded" in status.getvalue()
+    assert "Foo" in normalize_sphinx_text((Path(app.srcdir) / "_build/text/index.txt").read_text())
+    assert "forward reference" not in warning.getvalue()
+
+
 @pytest.mark.sphinx("text", testroot="attrs")
 def test_sphinx_build_attrs_types(app: SphinxTestApp, status: StringIO, warning: StringIO) -> None:
     template = """\

tests/test_resolver/test_type_hints.py

@@ -6,6 +6,7 @@
 from unittest.mock import MagicMock, patch
 
 from sphinx_autodoc_typehints._resolver._type_hints import (
+    _build_localns,
     _execute_guarded_code,
     _future_annotations_imported,
     _get_type_hint,
@@ -87,3 +88,25 @@ def test_guarded_import_warning_includes_module() -> None:
     mock_logger.warning.assert_called_once()
     args = mock_logger.warning.call_args
     assert "fake_mod" in str(args)
+
+
+def test_build_localns_adds_ancestor_classes() -> None:
+    import tests.roots.test_nested_attrs_localns as mod  # noqa: PLC0415
+
+    assert _build_localns(mod.Outer.Inner.__init__, {})["Outer"] is mod.Outer
+
+
+def test_build_localns_no_qualname() -> None:
+    def func() -> None: ...
+
+    func.__qualname__ = "func"
+    localns: dict[Any, Any] = {"existing": 1}
+    assert _build_localns(func, localns) == {"existing": 1}
+
+
+def test_build_localns_preserves_existing_localns() -> None:
+    import tests.roots.test_nested_attrs_localns as mod  # noqa: PLC0415
+
+    localns: dict[Any, Any] = {"key": "value"}
+    assert (result := _build_localns(mod.Outer.Inner.__init__, localns))["key"] == "value"
+    assert result["Outer"] is mod.Outer