pygenstub¶
pygenstub is a utility for generating stub files from docstrings
in source files. It takes a source file as input and creates a stub file
with the same base name and the .pyi
extension.
If the docstring of a function includes a sig field, the value of that field will be used to generate a prototype by matching the types to the parameters in the same order. For example, for the code given below:
def foo(a, b):
"""Do foo.
:sig: (int, str) -> None
"""
pygenstub will generate the following stub:
def foo(a: int, b: str) -> None: ...
pygenstub consists of a single module which itself contains signatures. You can see the source code and the autogenerated stub file as an example.
Getting started¶
pygenstub has been tested with Python 2.7, Python 3.4+, and compatible
versions of PyPy. You can install the latest version using pip
:
pip install pygenstub
Installation creates a script named pygenstub
which can be used
as follows:
pygenstub foo.py
This command will generate the file foo.pyi
in the same directory
as the input file. If the output file already exists, it will be overwritten.
If pygenstub is activated as a Sphinx extension (after autodoc), it will insert type comments for parameters and return values in the docstring. It will also remove the signature fields to exclude them from the output:
extensions = [
'sphinx.ext.autodoc',
'pygenstub'
]
As an example of the output, you can see the API documentation for pygenstub itself.
Getting help¶
The documentation is available on: https://pygenstub.tekir.org/
The source code can be obtained from: https://github.com/uyar/pygenstub
License¶
Copyright (C) 2016-2019 H. Turgut Uyar <uyar@tekir.org>
pygenstub is released under the GPL license, version 3 or later. Read
the included LICENSE.txt
for details.
Tip
pygenstub can be used with PyCharm file watchers to update stub files automatically when source files are modified.
- Features
- Command-line interface
- API
- History
- 1.4.0 (2019-03-27)
- 1.3.0 (2019-03-07)
- 1.2.4 (2019-02-01)
- 1.2.3 (2019-01-31)
- 1.2.2 (2019-01-08)
- 1.2.1 (2018-12-27)
- 1.2 (2018-10-19)
- 1.1 (2018-05-25)
- 1.0 (2018-05-25)
- 1.0b9 (2018-03-23)
- 1.0b8 (2018-03-23)
- 1.0b7 (2018-01-18)
- 1.0b6 (2017-07-26)
- 1.0b5 (2017-07-26)
- 1.0b4 (2017-06-16)
- 1.0b3 (2017-06-16)
- 1.0b2 (2017-05-26)
- 1.0b1 (2017-05-09)
- 1.0a6 (2017-03-06)
- 1.0a5 (2017-02-07)
- 1.0a4 (2017-01-06)
- 1.0a3 (2017-01-06)
- 1.0a2 (2017-01-03)
- 1.0a1 (2017-01-03)