Skip to main content

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.


Project details


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)

Uploaded Source

Built Distribution

pygenstub-1.0b6-py2.py3-none-any.whl (12.5 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page