✨ feat(resolver): type C data descriptors from stub files (#716)

A stub-backed C extension gets full signatures on its functions and
methods, yet its properties render as bare attributes. The cause sits at
the top of `process_docstring`: getset and member descriptors are not
`property` instances and are not callable, so the handler returns before
any stub lookup runs, even though the type is sitting right there in the
`.pyi` as a `@property` return annotation or a class-level annotated
assignment. I hit this documenting `turbohtml`'s C `Token` type, where
`attr()` rendered with full types while the eleven properties next to it
showed nothing.

The fix routes these descriptors through the same stub machinery that
signatures already use. A new `get_descriptor_type_hint` finds the
owning class in the stub via `__objclass__`, takes the `@property`
return annotation or the matching `AnnAssign`, and evaluates it in the
stub's namespace so type aliases keep their cross-referenced form. The
result lands in the docstring as a `:type:` field, which the attribute
directive renders the same way `:vartype:` injections do; an explicit
`:type:` already present in the docstring wins, and objects without a
stub stay untouched.

The `c_ext_mod` fixture grows three getset descriptors covering the
`@property` return, the alias-typed union, and the class-annotation
forms. Behavior for pure-Python properties is unchanged, since those
keep flowing through `fget`.

Author: gaborbernat

src/sphinx_autodoc_typehints/__init__.py

@@ -32,6 +32,7 @@
     backfill_type_hints,
     collect_documented_type_aliases,
     get_all_type_hints,
+    get_descriptor_type_hint,
     get_instance_var_annotations,
     get_obj_location,
 )
@@ -157,6 +158,7 @@ def process_docstring(  # noqa: PLR0913, PLR0917
     original_obj = obj
     obj = obj.fget if isinstance(obj, property) else obj
     if not callable(obj):
+        _maybe_inject_descriptor_type(app, what, obj, lines)
         return
     if inspect.isclass(obj):
         backfill_attrs_annotations(obj)
@@ -207,6 +209,20 @@ def process_docstring(  # noqa: PLR0913, PLR0917
         del app.config._typehints_module_prefix  # noqa: SLF001
 
 
+def _maybe_inject_descriptor_type(app: Sphinx, what: str, obj: Any, lines: list[str]) -> None:
+    """C data descriptors document as plain attributes; lift their type from the stub."""
+    if what != "attribute" or not (inspect.isgetsetdescriptor(obj) or inspect.ismemberdescriptor(obj)):
+        return
+    if any(line.startswith(":type:") for line in lines):
+        return
+    if (hint := get_descriptor_type_hint(obj)) is None:
+        return
+    formatted = add_type_css_class(
+        format_annotation(hint, app.config, short_literals=app.config.python_display_short_literal_types)
+    )
+    lines.extend(["", f":type: {formatted}"])
+
+
 def _inject_overload_signatures(
     app: Sphinx,
     what: str,

src/sphinx_autodoc_typehints/_resolver/__init__.py

@@ -5,14 +5,15 @@
 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
+from ._type_hints import get_all_type_hints, get_descriptor_type_hint
 from ._util import collect_documented_type_aliases, get_obj_location
 
 __all__ = [
     "backfill_attrs_annotations",
     "backfill_type_hints",
     "collect_documented_type_aliases",
     "get_all_type_hints",
+    "get_descriptor_type_hint",
     "get_instance_var_annotations",
     "get_obj_location",
 ]

src/sphinx_autodoc_typehints/_resolver/_stubs.py

@@ -258,6 +258,40 @@ def _extract_func_annotations(node: ast.FunctionDef | ast.AsyncFunctionDef) -> d
     return result
 
 
+def _backfill_descriptor_annotation(obj: Any) -> str | None:
+    """
+    Return the stub annotation string for a C data descriptor, or ``None``.
+
+    getset and member descriptors carry no runtime annotations, so their type
+    can only come from the owning class's stub: either a ``@property`` return
+    annotation or a class-level annotated assignment with the same name.
+    """
+    objclass = getattr(obj, "__objclass__", None)
+    name = getattr(obj, "__name__", None)
+    if objclass is None or not name:
+        return None
+    if (stub_path := _find_stub_path(obj)) is None or (tree := _parse_stub_ast(stub_path)) is None:
+        return None
+    node = _find_ast_node(tree.body, objclass.__qualname__.split("."))
+    if not isinstance(node, ast.ClassDef):
+        return None
+    members: list[ast.stmt] = list(node.body)
+    while members:
+        member = members.pop()
+        if isinstance(member, ast.If):
+            # stubs guard members behind `if sys.version_info >= ...` blocks (numpy's ndarray does)
+            members.extend(member.body)
+            members.extend(member.orelse)
+            continue
+        if isinstance(member, ast.AnnAssign) and isinstance(member.target, ast.Name) and member.target.id == name:
+            return ast.unparse(member.annotation)
+        if not isinstance(member, ast.FunctionDef) or member.name != name or member.returns is None:
+            continue
+        if any(isinstance(decorator, ast.Name) and decorator.id == "property" for decorator in member.decorator_list):
+            return ast.unparse(member.returns)
+    return None
+
+
 def _extract_class_annotations(node: ast.ClassDef) -> dict[str, str]:
     result: dict[str, str] = {}
     for child in node.body:

src/sphinx_autodoc_typehints/_resolver/_type_hints.py

@@ -16,7 +16,7 @@
 
 from sphinx_autodoc_typehints._annotations import MyTypeAliasForwardRef
 
-from ._stubs import _backfill_from_stub, _get_stub_context
+from ._stubs import _backfill_descriptor_annotation, _backfill_from_stub, _get_stub_context
 from ._type_comments import backfill_type_hints
 from ._util import get_obj_location
 
@@ -78,6 +78,25 @@ def _stub_target(cls: type) -> Any:
     return cls
 
 
+def get_descriptor_type_hint(obj: Any) -> Any | None:
+    """
+    Resolve the documented type of a C data descriptor from its stub, or ``None``.
+
+    The signature-driven backfill never sees these objects because they are not
+    callable; the annotation string from the stub is evaluated in the stub's
+    namespace so aliases and forward references resolve the same way they do
+    for function signatures.
+    """
+    if (annotation := _backfill_descriptor_annotation(obj)) is None:
+        return None
+    localns, alias_names, owner_module = _get_stub_context(obj)
+    for alias_name in alias_names:
+        ref = MyTypeAliasForwardRef(alias_name)
+        ref.crossref = True
+        localns[alias_name] = ref
+    return _resolve_string_annotations(obj, {"return": annotation}, localns, owner_module)["return"]
+
+
 def _resolve_string_annotations(
     obj: Any, annotations: dict[str, str], localns: dict[str, Any], owner_module: str = ""
 ) -> dict[str, Any]:

tests/roots/test-pyi-stubs/c_ext_mod.c

@@ -19,6 +19,26 @@ static PyObject *encoder_new(PyTypeObject *type, PyObject *args, PyObject *kwarg
     return type->tp_alloc(type, 0);
 }
 
+static PyObject *encoder_get_depth(PyObject *self, void *closure) {
+    (void)self;
+    (void)closure;
+    return PyLong_FromLong(0);
+}
+
+static PyObject *encoder_get_hook(PyObject *self, void *closure) {
+    (void)self;
+    (void)closure;
+    Py_RETURN_NONE;
+}
+
+static PyGetSetDef encoder_getset[] = {
+    {"depth", encoder_get_depth, NULL, "current nesting depth", NULL},
+    {"hook", encoder_get_hook, NULL, "the active encoder hook", NULL},
+    {"flags", encoder_get_depth, NULL, "encoder behavior flags", NULL},
+    {"guarded", encoder_get_depth, NULL, "a member guarded by sys.version_info in the stub", NULL},
+    {NULL, NULL, NULL, NULL, NULL}
+};
+
 static PyTypeObject EncoderType = {
     PyVarObject_HEAD_INIT(NULL, 0)
     .tp_name = "c_ext_mod.Encoder",
@@ -27,6 +47,7 @@ static PyTypeObject EncoderType = {
     .tp_itemsize = 0,
     .tp_flags = Py_TPFLAGS_DEFAULT,
     .tp_new = encoder_new,
+    .tp_getset = encoder_getset,
 };
 
 static int module_exec(PyObject *m) {

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

@@ -8,4 +8,11 @@ def greet(name: str, greeting: Sequence[str]) -> str: ...
 def with_hook(callback: GreetHook) -> None: ...
 
 class Encoder:
+    flags: int
     def __new__(cls, default: EncoderHook | None = None) -> Self: ...
+    @property
+    def depth(self) -> int: ...
+    @property
+    def hook(self) -> EncoderHook | None: ...
+    @property
+    def guarded(self) -> bool: ...

tests/test_init.py

@@ -85,6 +85,26 @@ def func(x: int) -> str: ...
     assert ":param x: the x" in lines
 
 
+def test_process_docstring_descriptor_without_stub_is_untouched() -> None:
+    """A C data descriptor with no stub keeps its docstring as-is."""
+    import array  # noqa: PLC0415
+
+    app = make_docstring_app()
+    lines = ["the typecode character used to create the array"]
+    process_docstring(app, "attribute", "array.array.typecode", array.array.typecode, None, lines)
+    assert lines == ["the typecode character used to create the array"]
+
+
+def test_process_docstring_descriptor_with_existing_type_field() -> None:
+    """An explicit :type: field wins over the stub annotation."""
+    import array  # noqa: PLC0415
+
+    app = make_docstring_app()
+    lines = [":type: str"]
+    process_docstring(app, "attribute", "array.array.typecode", array.array.typecode, None, lines)
+    assert lines == [":type: str"]
+
+
 def test_inject_overload_no_qualname() -> None:
     """Line 198: obj without __qualname__ returns False."""
     obj = MagicMock(spec=[])

tests/test_resolver/test_type_hints.py

@@ -16,7 +16,9 @@
     import annotationlib
 
 import pytest
+from conftest import make_docstring_app
 
+from sphinx_autodoc_typehints import process_docstring
 from sphinx_autodoc_typehints._annotations import MyTypeAliasForwardRef
 from sphinx_autodoc_typehints._resolver._type_hints import (
     _TYPE_GUARD_IMPORTS_RESOLVED,
@@ -29,6 +31,7 @@
     _run_guarded_import,
     _should_skip_guarded_import_resolution,
     get_all_type_hints,
+    get_descriptor_type_hint,
 )
 
 STUB_ROOT = Path(__file__).parent.parent / "roots" / "test-pyi-stubs"
@@ -216,6 +219,56 @@ def test_get_all_type_hints_preserves_stub_type_aliases(c_ext_mod: Any) -> None:
     assert result["callback"].name == "GreetHook"
 
 
+def test_descriptor_type_hint_resolves_from_stub(c_ext_mod: Any) -> None:
+    assert get_descriptor_type_hint(c_ext_mod.Encoder.depth) is int
+
+
+def test_descriptor_type_hint_preserves_stub_type_aliases(c_ext_mod: Any) -> None:
+    hint = get_descriptor_type_hint(c_ext_mod.Encoder.hook)
+    args = get_args(hint)
+    assert len(args) == 2
+    encoder_hook = args[0] if isinstance(args[0], MyTypeAliasForwardRef) else args[1]
+    assert encoder_hook.name == "EncoderHook"
+
+
+def test_descriptor_type_hint_resolves_class_annotation(c_ext_mod: Any) -> None:
+    assert get_descriptor_type_hint(c_ext_mod.Encoder.flags) is int
+
+
+def test_descriptor_type_hint_inside_version_guard(c_ext_mod: Any) -> None:
+    assert get_descriptor_type_hint(c_ext_mod.Encoder.guarded) is bool
+
+
+def test_descriptor_type_hint_for_non_class_stub_node(c_ext_mod: Any) -> None:
+    fake_class = type("greet", (), {"__module__": c_ext_mod.__name__, "__qualname__": "greet"})
+    descriptor = types.SimpleNamespace(__objclass__=fake_class, __name__="depth")
+    assert get_descriptor_type_hint(descriptor) is None
+
+
+def test_descriptor_type_hint_for_name_missing_from_stub(c_ext_mod: Any) -> None:
+    descriptor = types.SimpleNamespace(__objclass__=c_ext_mod.Encoder, __name__="missing")
+    assert get_descriptor_type_hint(descriptor) is None
+
+
+def test_process_docstring_injects_descriptor_type(c_ext_mod: Any) -> None:
+    app = make_docstring_app()
+    lines = ["current nesting depth"]
+    process_docstring(app, "attribute", "c_ext_mod.Encoder.depth", c_ext_mod.Encoder.depth, None, lines)
+    assert lines[0] == "current nesting depth"
+    assert lines[-1].startswith(":type: ")
+    assert "int" in lines[-1]
+
+
+def test_descriptor_type_hint_without_stub_is_none() -> None:
+    import array  # noqa: PLC0415
+
+    assert get_descriptor_type_hint(array.array.typecode) is None
+
+
+def test_descriptor_type_hint_ignores_non_descriptors() -> None:
+    assert get_descriptor_type_hint(object()) is None
+
+
 def test_get_all_type_hints_resolves_c_extension_class_new(c_ext_mod: Any) -> None:
     result = get_all_type_hints([], c_ext_mod.Encoder.__new__, "c_ext_mod.Encoder.__new__", {})
     default_type = result["default"]