Use type information from parseable docstrings?

[cgevans]

For some styles of docstrings, particularly numpydoc, it may be possible to use the docstring to add type information to the signature, and a return type. For modules with appropriately-formatted docstrings, this could allow an almost-complete typed stub file with minimal manual editing.

The numpydoc package supports parsing of numpydoc docstrings; there may be other packages for other styles. It may be that further parsing would be required:

• numpydoc uses "or", which would need to be replaced with, eg, "|".
• numpydoc uses {a, b, c} for fixed values, which would need to be replaced with Literal.
• numpydoc may have multiple return types as separate entries, which would need to be combined into a tuple.

[MusicalNinjaDad]

That's a really good idea @cgevans.

I can think of a few (more) places where similar functionality is available:

• mkdocstrings uses (IIRC) griffe to parse docstring details into logical segments, so it can render arguments in table form etc.
• ruff has lints in place to identify when arguments are not fully documented e.g. D417 (logic for that is in rust and ruff don't officially expose anything as an API)
• ruff bases the lints on pydocstyle, which will have similar logic in python

In my experience each of those need very specific and exact formatting to work.

I'd suggest for now just handling the case which you need and we can work on extending to other situations over time(?)

[pawamoy]

If you decide to use Griffe, let me know, I can help :)