scientific-python / docstub

Generate Python stub files from docstrings

docstub

Note

In early development!

A command line tool to generate Python stub files (PYI) from type descriptions in NumPyDoc style docstrings.

Installation

To try out docstub, for now, we recommend installing docstub directly from this repo:

pip install 'docstub [optional] @ git+https://github.com/scientific-python/docstub'

Usage & configuration

docstub example/example_pkg/

will create stub files for example_pkg/ in example/example_pkg-stubs/. For now, refer to docstub --help for more.

Declare imports and synonyms

Types in docstrings can and are used without having to import them. However, when docstub creates stub files from these docstrings it actually needs to know how to import those unknown types.

Tip

docstub already knows about types in Python's typing or collections.abc modules. That means you can just use types like Literal or Sequence.

For now docstub's relies on users to declare unknown types¹ in a docstub.toml or pyproject.toml like this:

[tool.docstub.docnames]
np = { import = "numpy", as = "np" }

With this declaration, you can safely use things that are available in the numpy namespace. E.g. docstub will recognize that np.uint8 requires import numpy as np and will include it in stub files if necessary.

docstub uses the keys of the docnames map to match unknown names used in docstrings. So

[tool.docstub.docnames]
func = { use = "Callable", from = "typing" }

will allow using func as a synonym for Callable.

Contributing

TBD

Acknowledgements

Thanks to docs2stubs by which this project was heavily inspired and influenced.

Footnotes

1. Static and possibly runtime analysis to automatically find unknown types is on the roadmap. ↩