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.0b6 (2017-07-26)
------------------
* Fixed handling of * separator for keyword-only arguments.
* Added support for keyword-only arguments with default values.
* Added --version option to command line arguments.
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.0b6 (2017-07-26)
------------------
* Fixed handling of * separator for keyword-only arguments.
* Added support for keyword-only arguments with default values.
* Added --version option to command line arguments.
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.0b6.tar.gz
(28.7 kB
view hashes)
Built Distribution
Close
Hashes for pygenstub-1.0b6-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 883ffe68cb12457dcdc858783f316444396f037c1ab76982ec90e6f8077e2270 |
|
MD5 | 9976e9805f33fb4fb5302f1f1b4b7cab |
|
BLAKE2b-256 | 092441b72b481e61219a5478828db0b8457df6214c0baf363e5dc6674e042593 |