bug: Stub docstrings are not used for dynamically-analyzed (C extension / SWIG) members

[tlambert03]

Hey @pawamoy ... it's me again

Following up on #116 and #296 — both about pymmcore, the SWIG-wrapped C extension I keep pestering you about. Those fixes solved the structural problems (wildcard expansion before merge, and wrong alias target paths). The stubs now merge successfully. But there's one remaining gap: _merge_stubs_docstring won't overwrite the SWIG-generated docstrings with the proper ones from the .pyi stubs.

The allow_inspection: false workaround from #296 was fine when I was rendering pymmcore.CMMCore directly, but I now need inherited_members: true on a subclass (pymmcore_plus.CMMCorePlus), which requires runtime inspection for MRO resolution — so I can't turn inspection off.

Problem

When merging .pyi stubs into a dynamically-inspected C extension module, _merge_stubs_docstring never overwrites an existing docstring:

def _merge_stubs_docstring(obj: Object, stubs: Object) -> None:
    if not obj.docstring and stubs.docstring:
        obj.docstring = stubs.docstring

This is fine for pure-Python modules where the runtime docstring is the authoritative one. But for SWIG/pybind11/cython extension modules, the runtime "docstrings" are auto-generated C-level signatures like:

getCurrentFocusScore(CMMCore self) -> double

The real docstrings live in the .pyi stubs.

Since the SWIG methods already have a (not so useful) docstring, the stub docstrings are silently discarded.

There's a second, related issue: For overload-only stub methods (methods where ALL definitions in the .pyi are @overload - standard practice for typed C extensions), _merge_stubs_overloads correctly attaches the overload annotations to the runtime member, but never applies the overload's docstring to the base function. So even though the overloads carry proper docstrings, the base function retains its SWIG signature string.

Concrete example

pymmcore ships an __init__.pyi with proper docstrings for all ~290 methods. When griffe loads it with find_stubs_package=True, none of the stub docstrings are used — every method renders with its SWIG signature instead.

Proposed fix

1. Prefer stub docstrings for dynamically-analyzed objects

   Objects loaded via runtime inspection have analysis = "dynamic". When merging stubs, their auto-generated docstrings should yield to the human-authored stub docstrings:

   def _merge_stubs_docstring(obj: Object, stubs: Object) -> None:
   -    if not obj.docstring and stubs.docstring:
   +    if stubs.docstring and (
   +        not obj.docstring or getattr(obj, "analysis", None) == "dynamic"
   +    ):
           obj.docstring = stubs.docstring

2. Apply overload docstrings to the base function during overload merging

   For overload-only stub methods, the base function (from the runtime module) has no stub counterpart in stubs.members, so _merge_stubs_members never touches it. Only _merge_stubs_overloads runs, and it only merges annotations. Adding a docstring fallback here covers the gap:

   def _merge_stubs_overloads(obj: Module | Class, stubs: Module | Class) -> None:
       for function_name, overloads in list(stubs.overloads.items()):
           if overloads:
               with suppress(KeyError):
   -                _merge_overload_annotations(obj.get_member(function_name), overloads)
   +                function = obj.get_member(function_name)
   +                _merge_overload_annotations(function, overloads)
   +                _merge_stubs_docstring(function, overloads[0])
           del stubs.overloads[function_name]

Together, these two changes ensure that stub docstrings are used for all dynamically-analyzed members — both regular and overloaded.

---

thoughts?

I can submit a PR

[tlambert03]

side-note... I'm currently "solving" this locally with a custom griffe extension (from claude):

"""Griffe extension to replace SWIG docstrings with stub docstrings for pymmcore."""

from __future__ import annotations

import ast
from pathlib import Path
from typing import TYPE_CHECKING

import griffe

if TYPE_CHECKING:
    from griffe import GriffeLoader, Module


def _extract_stub_docstrings(pyi_path: Path) -> dict[str, str]:
    """Parse a .pyi file and extract method docstrings from a class.

    Handles @overload methods (takes docstring from first overload) and
    regular methods alike.
    """
    source = pyi_path.read_text()
    tree = ast.parse(source)

    docstrings: dict[str, str] = {}
    for node in ast.walk(tree):
        if not (isinstance(node, ast.ClassDef) and node.name == "CMMCore"):
            continue
        for item in node.body:
            if not isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
                continue
            name = item.name
            if name in docstrings:
                continue  # keep first occurrence (first @overload)
            doc = ast.get_docstring(item)
            if doc:
                docstrings[name] = doc
    return docstrings


class SWIGStubDocstrings(griffe.Extension):
    """Replace SWIG-generated docstrings with proper ones from .pyi stubs."""

    def on_package(
        self, *, pkg: Module, loader: GriffeLoader, **kwargs: object
    ) -> None:
        if pkg.name != "pymmcore":
            return

        # Find the .pyi stub file
        pkg_dir = Path(pkg.filepath).parent  # type: ignore[arg-type]
        pyi_path = pkg_dir / "__init__.pyi"
        if not pyi_path.exists():
            return

        # Extract all docstrings from the stub (including @overload methods)
        stub_docs = _extract_stub_docstrings(pyi_path)
        if not stub_docs:
            return

        # Find the runtime CMMCore class (in the SWIG submodule)
        for subpath in ("pymmcore_swig.CMMCore", "_pymmcore_swig.CMMCore"):
            try:
                swig_cls = pkg[subpath]
                break
            except KeyError:
                continue
        else:
            return

        # Replace SWIG docstrings with stub docstrings
        for name, doc in stub_docs.items():
            if name in swig_cls.members:
                member = swig_cls.members[name]
                member.docstring = griffe.Docstring(doc, parent=member)

[pawamoy]

Hey @tlambert03! Thanks for the detailed report 🙂

I've been conservative about overriding data from sources with data obtained from stubs. But more and more I think Griffe should give precedence to stubs data. Let me re-read again the authoritative docs regarding stubs.

[pawamoy]

There's a tiny paragraph at the end of https://typing.python.org/en/latest/guides/writing_stubs.html about docstrings 😅:

There are several tradeoffs around including docstrings in type stubs. Consider the intended purpose of your stubs when deciding whether to include docstrings in your project’s stubs.

• They do not affect type checking results and will be ignored by type checkers.
• Docstrings can improve certain IDE functionality, such as hover info.
• Duplicating docstrings between source code and stubs requires extra work to keep them in sync.

The second sentence is interesting:

Consider the intended purpose of your stubs when deciding whether to include docstrings in your project’s stubs.

It tells me (although a bit too implicitly) that stubs can indeed be used for something else than type-checking.

In any case, there's nothing about who gets precedence: source docstrings or stubs docstrings. So I suppose we can do whatever we want in Griffe 🤷

The thing is, switching the behavior from "preserving source docstring" to "overriding it with stub one" could be a breaking change. So I'm inclined to implement this second behavior under a configuration option (named something like prefer_stub_docstrings).

Also, the SWIG thing definitely should let you configure it so that it doesn't add these useless (to you) docstrings on objects. Have you thought about requesting that?

I've asked about official recommendations here: https://discuss.python.org/t/stubs-and-docstrings-official-recommendations/106281 🙂

[tlambert03]

Thanks!

In my opinion there's no right answer to the question

In docs-oriented static analysis tools, should stub docstrings override source docstrings?

A simple "yes" or "no" is guaranteed to come up short. It feels like a natural candidate for a user preference to me.

I'm inclined to implement this second behavior under a configuration option

Absolutely, I think that's the right choice. And I would be plenty happy with it defaulting to whatever behavior you want (ie don't override, for non breaking behavior).

Yes, one could ask for more from SWIG and other tools that wrap native code with any degree of auto generation, and I will look into that as well, but as an abstract and practical question: there are too many ways in which things happen for this to ever be completely solved by working on the native wrapping tools. It's a natural for a configurable