Metadata-Version: 2.1
Name: pygenstub
Version: 1.4.0
Summary: Python stub file generator.
Home-page: https://pygenstub.tekir.org/
License: GPL-3.0+
Keywords: type hints,stub files
Author: H. Turgut Uyar
Author-email: uyar@tekir.org
Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Software Development :: Documentation
Requires-Dist: docutils (>=0.14,<0.15)
Requires-Dist: pathlib2 (>=2.3,<3.0); python_version >= "2.7" and python_version < "3.0"
Project-URL: Documentation, https://pygenstub.tekir.org/
Project-URL: Repository, https://github.com/uyar/pygenstub
Description-Content-Type: text/x-rst

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:

.. 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: ...

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:

.. code-block:: python

   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.

.. _source code: https://github.com/uyar/pygenstub/blob/master/pygenstub.py
.. _stub file: https://github.com/uyar/pygenstub/blob/master/pygenstub.pyi
.. _API documentation: https://pygenstub.tekir.org/api.html

