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:

:code:

   .. code-block:: python

      def foo(a, b):
          """Do foo.

          :sig: (int, str) -> None
          """

: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 this document. You can see the `source code`_
and the autogenerated `stub file`_ as an example.

.. note::

   Generating stub files this way might not be a good idea in some cases.
   However, if you're not manually writing your ``.pyi`` files,
   pygenstub should be harmless.

Sphinx autodoc support
----------------------

If pygenstub is activated as a Sphinx extension (after 'sphinx.ext.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.

.. _source code: https://bitbucket.org/uyar/pygenstub/src/tip/pygenstub.py
.. _stub file: https://bitbucket.org/uyar/pygenstub/src/tip/pygenstub.pyi
