Repository navigation
Support for typing @overload annotation #442
Description
Problem Description
Some support for function overloads specified by @overload annotation in typestubs is missing. All functions that have it, are just shown with the general base implementation (*args, **kwds) instead of the declared and fully typed overloads.
Proposal
In the beginning, just one entry per overload would be nice.
Additional context
Trying to document a Cython extension that due to its C++ origin has typestubs with @overload annotations
Activity
mhils commentedon Sep 28, 2022
pdoc heavily relies on dynamic analysis. As far as I know, you cannot access
@overloadsignatures using that approach (the final function definition overwrites all previous ones). Implementing support using static analysis would be a major undertaking and introduce significant complexity. I think your request is by all means valid, but I'm afraid the answer here is to 1) use a different documentation generator, 2) not use@overload, or 3) live with it.jpfeuffer commentedon Sep 29, 2022
I see. That makes sense. Do you by chance know about any documentation tool that supports both typestubs and overloads 😅 It is surprisingly hard to find.
Btw: It might be possible starting from 3.11.
python/cpython#89263
mhils commentedon Sep 29, 2022
Seems like this hasn't made it into 3.11 in time and will be in 3.12 the earliest.
I don't know, but Sphinx and maybe mkdocstrings have the largest ecosystems.
jpfeuffer commentedon Sep 29, 2022
Yes, not in the
help()function but maybe via the typing stdlib (typing.getOverloads()). The PR for that was merged early enough I think.Anyway, I give up for now and will revisit the whole thing in the very distant future again. (Sphinx autosummary/doc does not support type stubs at all and overloads only via docstrings and without descriptions of each overload).
Thanks for considering!