🐛 fix(stubs): resolve stub type hints for C/Rust extensions (#655)

C/Rust extension functions re-exported from parent packages — like
`cbor2._cbor2.dumps` exposed as `cbor2.dumps` — had no working stub
resolution. Sphinx's built-in `_find_type_stub_spec()` only looks for
`.pyi` files adjacent to the `.so` with the same filename, so stubs at
the parent package level (e.g. `cbor2/__init__.pyi`) were never found.
This meant type aliases like `EncoderHook` were expanded to raw
`Callable[...]` signatures, annotations on C extension functions were
lost entirely, and cross-references were missing from rendered docs.
Additionally, C extension classes that define constructors via `__new__`
(with `__init__` inherited from `object`) had no constructor parameter
documentation because `process_docstring` only examined `__init__`. 🐛

The fix introduces a parent-package walk-up that follows the PEP 561
re-export pattern: when no stub is found next to the extension module,
it traverses `sys.modules` upward to find the parent whose
`__init__.pyi` documents the re-exported public API. A unified
`_get_stub_context()` call retrieves the stub's local namespace,
`TypeAlias` names (detected via AST including `typing.TypeAlias`,
`typing_extensions.TypeAlias`, and `type` statements), and the owning
module name in a single lookup — avoiding duplicate path discovery. The
owning module name is then used as `globalns` during `eval()`-based
annotation resolution, ensuring the correct namespace is used when the
function's `__module__` points at the C extension child rather than the
stub-owning parent. ✨

A `crossref` flag on `MyTypeAliasForwardRef` distinguishes stub-derived
aliases (which emit `:py:type:` roles for Sphinx cross-referencing) from
`autodoc_type_aliases` display names (which must not be wrapped to avoid
double-quoting in text output). The `collect_documented_type_aliases`
function no longer matches unqualified type names from other modules,
eliminating a cross-contamination risk in multi-module projects.
Constructor logic in `process_docstring` now falls back to `__new__`
when `__init__` is `object.__init__` and `__new__` is overridden, and
uses `inspect.signature(cls)` instead of
`inspect.signature(cls.__new__)` to get the correct parameter list for C
extensions where the latter returns `(*args, **kwargs)`.

When injecting annotation-based types, preexisting `:type:` directives
in the docstring (including multi-line continuations) are now removed
and replaced rather than duplicated. Inline `:param type name:` formats
are stripped to `:param name:` before injection, ensuring all parameter
types use consistent CSS styling via the `sphinx_autodoc_typehints-type`
class. Preexisting `:rtype:` directives are also replaced with the
annotation-derived return type, fixing a bug where stale docstring
return types would shadow the actual function signature.

Author: gaborbernat

.pre-commit-config.yaml

@@ -15,7 +15,7 @@ repos:
       - id: codespell
         additional_dependencies: ["tomli>=2.4"]
   - repo: https://github.com/tox-dev/tox-toml-fmt
-    rev: "v1.8.0"
+    rev: "v1.9.0"
     hooks:
       - id: tox-toml-fmt
   - repo: https://github.com/tox-dev/pyproject-fmt

src/sphinx_autodoc_typehints/__init__.py

@@ -23,7 +23,7 @@
 )
 from ._formats import detect_format
 from ._formats._numpydoc import _convert_numpydoc_to_sphinx_fields  # noqa: F401
-from ._formats._sphinx import _has_yields_section, _is_generator_type
+from ._formats._sphinx import _has_yields_section, _is_generator_type, _strip_inline_param_type
 from ._intersphinx import build_type_mapping
 from ._parser import parse
 from ._resolver import (
@@ -151,14 +151,22 @@ def process_docstring(  # noqa: PLR0913, PLR0917
         return
     if inspect.isclass(obj):
         backfill_attrs_annotations(obj)
-    obj = obj.__init__ if inspect.isclass(obj) else obj
+    use_class_for_signature = False
+    if inspect.isclass(obj):
+        if obj.__init__ is object.__init__ and obj.__new__ is not object.__new__:
+            use_class_for_signature = True
+            obj = obj.__new__
+        else:
+            obj = obj.__init__
     try:
         obj = inspect.unwrap(obj)
     except ValueError:
         return
 
     try:
-        signature = sphinx_signature(obj, type_aliases=app.config["autodoc_type_aliases"])
+        signature = sphinx_signature(
+            original_obj if use_class_for_signature else obj, type_aliases=app.config["autodoc_type_aliases"]
+        )
     except (ValueError, TypeError):
         signature = None
 
@@ -305,6 +313,13 @@ def _inject_arg_signature(  # noqa: PLR0913, PLR0917
 
     insert_index = fmt.find_param(lines, arg_name)
 
+    if (
+        insert_index is not None
+        and annotation is not None
+        and (stripped := _strip_inline_param_type(lines[insert_index], arg_name))
+    ):
+        lines[insert_index] = stripped
+
     if insert_index is not None and hasattr(fmt, "get_arg_name_from_line"):
         arg_name = fmt.get_arg_name_from_line(lines[insert_index]) or arg_name
 
@@ -314,27 +329,44 @@ def _inject_arg_signature(  # noqa: PLR0913, PLR0917
     elif annotation is not None and insert_index is None and app.config.always_document_param_types:
         insert_index = fmt.add_undocumented_param(lines, arg_name)
 
-    if insert_index is not None:
-        has_preexisting_annotation = False
+    if insert_index is None:
+        return
+
+    has_preexisting = False
+    if annotation is None:
+        type_annotation, has_preexisting = fmt.find_preexisting_type(lines, arg_name)
+    else:
+        preexisting_line, has_preexisting = fmt.find_preexisting_type(lines, arg_name)
+        if has_preexisting:
+            insert_index = _remove_preexisting_type(lines, preexisting_line)
+        type_annotation = ":type {}: {}".format(
+            arg_name,
+            add_type_css_class(
+                format_annotation(annotation, app.config, short_literals=app.config.python_display_short_literal_types)
+            ),
+        )
+
+    if app.config.typehints_defaults and (
+        formatted_default := format_default(app, default, annotation is not None or has_preexisting)
+    ):
+        type_annotation = fmt.append_default(
+            lines,
+            insert_index,
+            type_annotation,
+            formatted_default,
+            after=app.config.typehints_defaults.endswith("after"),
+        )
+
+    lines.insert(insert_index, type_annotation)
 
-        if annotation is None:
-            type_annotation, has_preexisting_annotation = fmt.find_preexisting_type(lines, arg_name)
-        else:
-            short_literals = app.config.python_display_short_literal_types
-            formatted_annotation = add_type_css_class(
-                format_annotation(annotation, app.config, short_literals=short_literals)
-            )
-            type_annotation = f":type {arg_name}: {formatted_annotation}"
-
-        if app.config.typehints_defaults:
-            formatted_default = format_default(app, default, annotation is not None or has_preexisting_annotation)
-            if formatted_default:
-                after = app.config.typehints_defaults.endswith("after")
-                type_annotation = fmt.append_default(
-                    lines, insert_index, type_annotation, formatted_default, after=after
-                )
 
-        lines.insert(insert_index, type_annotation)
+def _remove_preexisting_type(lines: list[str], preexisting_line: str) -> int:
+    idx = lines.index(preexisting_line)
+    end = idx + 1
+    while end < len(lines) and (not lines[end] or lines[end][0].isspace()):
+        end += 1
+    del lines[idx:end]
+    return idx
 
 
 def _inject_rtype(  # noqa: PLR0913, PLR0917

src/sphinx_autodoc_typehints/_annotations.py

@@ -65,6 +65,8 @@
 
 
 class MyTypeAliasForwardRef(TypeAliasForwardRef):
+    crossref: bool = False
+
     def __or__(self, value: Any) -> Any:  # ty: ignore[invalid-method-override]
         return Union[self, value]  # noqa: UP007
 
@@ -88,14 +90,16 @@ def format_annotation(annotation: Any, config: Config, *, short_literals: bool =
         return _format_internal_tuple(annotation, config)
 
     if isinstance(annotation, TypeAliasForwardRef):
+        fully_qualified: bool = getattr(config, "typehints_fully_qualified", False)
+        prefix = "" if fully_qualified else "~"
         if (env := getattr(config, "_typehints_env", None)) is not None:
             py_domain = env.get_domain("py")
             module_prefix = getattr(config, "_typehints_module_prefix", "")
             for candidate in (f"{module_prefix}.{annotation.name}", annotation.name):
                 if candidate in py_domain.objects and py_domain.objects[candidate].objtype == "type":
-                    fully_qualified: bool = getattr(config, "typehints_fully_qualified", False)
-                    prefix = "" if fully_qualified else "~"
                     return f":py:type:`{prefix}{candidate}`"
+        if isinstance(annotation, MyTypeAliasForwardRef) and annotation.crossref:
+            return f":py:type:`{prefix}{annotation.name}`"
         return annotation.name
 
     try:

src/sphinx_autodoc_typehints/_formats/_sphinx.py

@@ -67,7 +67,23 @@ def _line_is_param_line_for_arg(line: str, arg_name: str) -> bool:
     if keyword not in {"param", "parameter", "arg", "argument"}:
         return False
 
-    return any(doc_name == prefix + arg_name for prefix in ("", "\\*", "\\**", "\\*\\*"))
+    if any(doc_name == prefix + arg_name for prefix in ("", "\\*", "\\**", "\\*\\*")):
+        return True
+    # Match `:param type name:` format where inline type precedes the argument name.
+    return any(doc_name.endswith(f" {prefix}{arg_name}") for prefix in ("", "\\*", "\\**", "\\*\\*"))
+
+
+def _strip_inline_param_type(line: str, arg_name: str) -> str | None:
+    parts = line.split(":", maxsplit=2)
+    if len(parts) != 3:  # noqa: PLR2004
+        return None
+    directive_and_name = parts[1]
+    for prefix in ("", "\\*", "\\**", "\\*\\*"):
+        suffix = f" {prefix}{arg_name}"
+        if directive_and_name.endswith(suffix):
+            keyword = directive_and_name.split(maxsplit=1)[0]
+            return f":{keyword} {prefix}{arg_name}:{parts[2]}"
+    return None
 
 
 def _is_generator_type(annotation: Any) -> bool:
@@ -150,8 +166,9 @@ def find_preexisting_type(self, lines: list[str], arg_name: str) -> tuple[str, b
         return type_annotation, False
 
     def get_rtype_insert_info(self, app: Sphinx, lines: list[str]) -> InsertIndexInfo | None:  # noqa: PLR6301
-        if any(line.startswith(":rtype:") for line in lines):
-            return None
+        if (at := next((i for i, line in enumerate(lines) if line.startswith(":rtype:")), None)) is not None:
+            del lines[at]
+            return InsertIndexInfo(insert_index=at, found_return=True)
 
         for at, line in enumerate(lines):
             if line.startswith((":return:", ":returns:")):

src/sphinx_autodoc_typehints/_resolver/_stubs.py

@@ -6,11 +6,15 @@
 import contextlib
 import importlib
 import inspect
+import sys
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from ._type_comments import _load_args
 
+if TYPE_CHECKING:
+    import types
+
 _STUB_AST_CACHE: dict[Path, ast.Module | None] = {}
 
 
@@ -20,10 +24,22 @@ def _backfill_from_stub(obj: Any) -> dict[str, str]:
     return {}
 
 
-def _get_stub_localns(obj: Any) -> dict[str, Any]:
-    if (stub_path := _find_stub_path(obj)) and (tree := _parse_stub_ast(stub_path)):
-        return _resolve_stub_imports(tree)
-    return {}
+def _get_stub_context(obj: Any) -> tuple[dict[str, Any], set[str], str]:
+    """
+    Return (localns, alias_names, owner_module_name) from the stub owning *obj*.
+
+    Single lookup avoids duplicate ``_find_stub_owner`` / ``_parse_stub_ast`` calls. The owner module name lets callers
+    use ``vars(sys.modules[name])`` as the correct globalns — important when a C extension function lives in a child
+    module but its stub belongs to a parent package (e.g. ``cbor2._cbor2.dumps`` → ``cbor2/__init__.pyi``).
+    """
+    if (info := _find_stub_owner(obj)) is None:
+        return {}, set(), ""
+    stub_path, owner_module = info
+    if (tree := _parse_stub_ast(stub_path)) is None:
+        return {}, set(), ""
+    ns: dict[str, Any] = dict(vars(owner_module))
+    ns.update(_resolve_stub_imports(tree))
+    return ns, _extract_type_alias_names(tree), owner_module.__name__
 
 
 def _resolve_stub_imports(tree: ast.Module) -> dict[str, Any]:
@@ -51,9 +67,43 @@ def _resolve_stub_imports(tree: ast.Module) -> dict[str, Any]:
     return ns
 
 
+def _get_module(obj: Any) -> types.ModuleType | None:
+    if module := inspect.getmodule(obj):
+        return module
+    # inspect.getmodule returns None for some C/Rust extension descriptors even when __module__ is valid.
+    if (mod_name := getattr(obj, "__module__", None)) and (module := sys.modules.get(mod_name)):
+        return module
+    # Method descriptors on C extension types expose the owning class via __objclass__.
+    if (owner_cls := getattr(obj, "__objclass__", None)) and (module := inspect.getmodule(owner_cls)):
+        return module
+    # Bound methods like __new__ on C extension classes have __self__ pointing to the class.
+    if (owner_cls := getattr(obj, "__self__", None)) and inspect.isclass(owner_cls):
+        return inspect.getmodule(owner_cls)
+    return None
+
+
 def _find_stub_path(obj: Any) -> Path | None:
-    if (module := inspect.getmodule(obj)) is None:
+    if info := _find_stub_owner(obj):
+        return info[0]
+    return None
+
+
+def _find_stub_owner(obj: Any) -> tuple[Path, types.ModuleType] | None:
+    if (module := _get_module(obj)) is None:
         return None
+    if result := _find_stub_for_module(module):
+        return result, module
+    # PEP 561 re-export pattern: cbor2.__init__.pyi documents functions living in cbor2._cbor2 (C/Rust). Walk up to
+    # find the parent package whose stub describes the re-exported public API.
+    module_name = module.__name__
+    while "." in module_name:
+        module_name = module_name.rsplit(".", 1)[0]
+        if (parent := sys.modules.get(module_name)) and (result := _find_stub_for_module(parent)):
+            return result, parent
+    return None
+
+
+def _find_stub_for_module(module: types.ModuleType) -> Path | None:
     try:
         source_file = inspect.getfile(module)
     except TypeError:
@@ -77,6 +127,24 @@ def _parse_stub_ast(stub_path: Path) -> ast.Module | None:
     return _STUB_AST_CACHE[stub_path]
 
 
+_TYPE_ALIAS_ANNOTATIONS = {"TypeAlias", "typing.TypeAlias", "typing_extensions.TypeAlias"}
+
+
+def _extract_type_alias_names(tree: ast.Module) -> set[str]:
+    names: set[str] = set()
+    for node in tree.body:
+        if (
+            isinstance(node, ast.AnnAssign)
+            and isinstance(node.target, ast.Name)
+            and isinstance(node.annotation, ast.Name | ast.Attribute)
+            and ast.unparse(node.annotation) in _TYPE_ALIAS_ANNOTATIONS
+        ):
+            names.add(node.target.id)
+        elif isinstance(node, ast.TypeAlias) and isinstance(node.name, ast.Name):
+            names.add(node.name.id)
+    return names
+
+
 def _extract_annotations_from_stub(tree: ast.Module, obj: Any) -> dict[str, str]:
     qualname = getattr(obj, "__qualname__", None)
     if not qualname:

src/sphinx_autodoc_typehints/_resolver/_type_hints.py

@@ -8,18 +8,17 @@
 import sys
 import textwrap
 import types
-from typing import TYPE_CHECKING, Any, get_type_hints
+from typing import Any, get_type_hints
 
 from sphinx.ext.autodoc.mock import mock
 from sphinx.util import logging
 
-from ._stubs import _backfill_from_stub, _get_stub_localns
+from sphinx_autodoc_typehints._annotations import MyTypeAliasForwardRef
+
+from ._stubs import _backfill_from_stub, _get_stub_context
 from ._type_comments import backfill_type_hints
 from ._util import get_obj_location
 
-if TYPE_CHECKING:
-    from sphinx_autodoc_typehints._annotations import MyTypeAliasForwardRef
-
 if sys.version_info >= (3, 14):  # pragma: >=3.14 cover
     import annotationlib
 
@@ -46,19 +45,51 @@ def get_all_type_hints(
     if not result:
         result = backfill_type_hints(obj, name)
         stub_localns: dict[str, Any] = {}
+        stub_alias_names: set[str] = set()
+        stub_owner_module: str = ""
         if not result:
             result = _backfill_from_stub(obj)
             if result:
-                stub_localns = _get_stub_localns(obj)
+                stub_localns, stub_alias_names, stub_owner_module = _get_stub_context(obj)
+        combined_localns = {**stub_localns, **localns}
+        for alias_name in stub_alias_names:
+            ref = MyTypeAliasForwardRef(alias_name)
+            ref.crossref = True
+            combined_localns[alias_name] = ref
         try:
             obj.__annotations__ = result
         except (AttributeError, TypeError):
-            pass
+            result = _resolve_string_annotations(obj, result, combined_localns, stub_owner_module)
         else:
-            result = _get_type_hint(autodoc_mock_imports, name, obj, {**localns, **stub_localns})
+            result = _get_type_hint(autodoc_mock_imports, name, obj, combined_localns)
     return result
 
 
+def _resolve_string_annotations(
+    obj: Any, annotations: dict[str, str], localns: dict[str, Any], owner_module: str = ""
+) -> dict[str, Any]:
+    # Use the stub owner module's namespace when available — the obj's __module__ may point at a C extension child
+    # (e.g. cbor2._cbor2) while the stub lives in the parent (cbor2/__init__.pyi).
+    module_name = owner_module or getattr(obj, "__module__", None)
+    globalns = vars(sys.modules[module_name]) if module_name and module_name in sys.modules else {}
+    resolved: dict[str, Any] = {}
+    for key, value in annotations.items():
+        if isinstance(value, str):
+            try:
+                resolved[key] = eval(value, globalns, localns)  # noqa: S307
+            except Exception:  # noqa: BLE001
+                _LOGGER.debug(
+                    "Failed to resolve annotation %r=%r for %s",
+                    key,
+                    value,
+                    getattr(obj, "__qualname__", "?"),
+                )
+                resolved[key] = value
+        else:
+            resolved[key] = value
+    return resolved
+
+
 def _get_type_hint(
     autodoc_mock_imports: list[str], name: str, obj: Any, localns: dict[Any, MyTypeAliasForwardRef]
 ) -> dict[str, Any]: