Python stub file generator.
Project description
Copyright (C) 2016-2017 H. Turgut Uyar <uyar@tekir.org>
pygenstub is a utility for generating stub files from Python source files.
It takes a source file as input and creates a stub file with the same base name
and the ``.pyi`` extension.
:PyPI: https://pypi.python.org/pypi/pygenstub/
:Repository: https://bitbucket.org/uyar/pygenstub
:Documentation: https://pygenstub.readthedocs.io/
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:
.. code-block:: python
def foo(a, b):
"""Do foo.
:sig: (int, str) -> None
"""
pygenstub will generate the following stub:
.. code-block:: python
def foo(a: int, b: str) -> None: ...
Usage
-----
pygenstub can be installed 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.
.. tip::
pygenstub can be used with PyCharm file watchers to update stub files
automatically when source files are modified.
pygenstub consists of a single module which itself contains signature fields
and commands as described in the documentation. You can see the `source code`_
and the autogenerated `stub file`_ as an example.
Sphinx autodoc support
----------------------
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:
.. code-block:: python
extensions = [
'sphinx.ext.autodoc',
'pygenstub'
]
As an example of the output, you can see the `API documentation`_
for pygenstub itself.
.. _source code: https://bitbucket.org/uyar/pygenstub/src/tip/pygenstub.py
.. _stub file: https://bitbucket.org/uyar/pygenstub/src/tip/pygenstub.pyi
.. _API documentation: https://pygenstub.readthedocs.io/en/latest/api.html
History
=======
1.0b5 (2017-07-26)
------------------
* Added support for property, staticmethod, and classmethod decorators.
* Added support for keyword-only arguments.
1.0b4 (2017-06-16)
------------------
* Collect builtin types from the builtins module.
1.0b3 (2017-06-16)
------------------
* Fixes for *args and **kwargs on Python 2 code.
1.0b2 (2017-05-26)
------------------
* Added support for Python 2 again.
1.0b1 (2017-05-09)
------------------
* Added support for using type hints in Sphinx autodoc.
1.0a6 (2017-03-06)
------------------
* Improvements on imported names.
1.0a5 (2017-02-07)
------------------
* Support for methods.
* Support for instance variables.
* Support for base classes.
* Shortened the field name from "signature" to "sig".
* Use three dots instead of actual value for parameter defaults.
* Dropped support for Python 2.
1.0a4 (2017-01-06)
------------------
* Long stubs are now spread over multiple lines.
* Better handling of parameter defaults that are tuples.
* Bugfix: handling of parameter defaults that have the value None.
1.0a3 (2017-01-06)
------------------
* Proper support for names from the typing module in input parameters.
* Added parameter default values to stubs.
1.0a2 (2017-01-03)
------------------
* Support for Python 2.7.
1.0a1 (2017-01-03)
------------------
* First release on PyPI.
pygenstub is a utility for generating stub files from Python source files.
It takes a source file as input and creates a stub file with the same base name
and the ``.pyi`` extension.
:PyPI: https://pypi.python.org/pypi/pygenstub/
:Repository: https://bitbucket.org/uyar/pygenstub
:Documentation: https://pygenstub.readthedocs.io/
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:
.. code-block:: python
def foo(a, b):
"""Do foo.
:sig: (int, str) -> None
"""
pygenstub will generate the following stub:
.. code-block:: python
def foo(a: int, b: str) -> None: ...
Usage
-----
pygenstub can be installed 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.
.. tip::
pygenstub can be used with PyCharm file watchers to update stub files
automatically when source files are modified.
pygenstub consists of a single module which itself contains signature fields
and commands as described in the documentation. You can see the `source code`_
and the autogenerated `stub file`_ as an example.
Sphinx autodoc support
----------------------
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:
.. code-block:: python
extensions = [
'sphinx.ext.autodoc',
'pygenstub'
]
As an example of the output, you can see the `API documentation`_
for pygenstub itself.
.. _source code: https://bitbucket.org/uyar/pygenstub/src/tip/pygenstub.py
.. _stub file: https://bitbucket.org/uyar/pygenstub/src/tip/pygenstub.pyi
.. _API documentation: https://pygenstub.readthedocs.io/en/latest/api.html
History
=======
1.0b5 (2017-07-26)
------------------
* Added support for property, staticmethod, and classmethod decorators.
* Added support for keyword-only arguments.
1.0b4 (2017-06-16)
------------------
* Collect builtin types from the builtins module.
1.0b3 (2017-06-16)
------------------
* Fixes for *args and **kwargs on Python 2 code.
1.0b2 (2017-05-26)
------------------
* Added support for Python 2 again.
1.0b1 (2017-05-09)
------------------
* Added support for using type hints in Sphinx autodoc.
1.0a6 (2017-03-06)
------------------
* Improvements on imported names.
1.0a5 (2017-02-07)
------------------
* Support for methods.
* Support for instance variables.
* Support for base classes.
* Shortened the field name from "signature" to "sig".
* Use three dots instead of actual value for parameter defaults.
* Dropped support for Python 2.
1.0a4 (2017-01-06)
------------------
* Long stubs are now spread over multiple lines.
* Better handling of parameter defaults that are tuples.
* Bugfix: handling of parameter defaults that have the value None.
1.0a3 (2017-01-06)
------------------
* Proper support for names from the typing module in input parameters.
* Added parameter default values to stubs.
1.0a2 (2017-01-03)
------------------
* Support for Python 2.7.
1.0a1 (2017-01-03)
------------------
* First release on PyPI.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
pygenstub-1.0b5.tar.gz
(28.4 kB
view hashes)
Built Distribution
Close
Hashes for pygenstub-1.0b5-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e2591a04e3139f86072f4ea2b1f62fa4f83eba8b731cf3e207cf88cfe9c9d806 |
|
MD5 | 2be7d2a6941c030007c0d681ed162d36 |
|
BLAKE2b-256 | fdc0918f0f18a18a144772fbfb68c1d48999461f2fd66d9795192568d5390955 |