Metadata-Version: 2.1
Name: pygenstub
Version: 2.0.0
Summary: Python stub file generator.
Home-page: https://tekir.org/pygenstub/
License: GPL-3.0+
Keywords: type hints,stub files,docstring
Author: H. Turgut Uyar
Author-email: uyar@tekir.org
Requires-Python: >=3.6,<4.0
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
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Software Development :: Documentation
Requires-Dist: docutils (>=0.16,<0.17)
Project-URL: Documentation, https://pygenstub.readthedocs.io/
Project-URL: Repository, https://github.com/uyar/pygenstub
Description-Content-Type: text/x-rst

pygenstub
=========

pygenstub is a utility for generating stub files from docstrings
in source files.

If the docstring of a function includes a **sig** field,
the value of that field will be used to generate a stub
by matching the types to the parameters in the same order.

For example, for the function 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 `source file`_ which contains such signatures.
You can check the `stub file`_ generated by running pygenstub on itself
as an example.

Getting started
---------------

pygenstub runs on Python 3.6 and later versions.
You can install the latest version from `PyPI`_::

  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 you download the `source file`_, you can also run it directly
without installing::

  python pygenstub.py foo.py

If pygenstub is activated as a Sphinx extension (after *sphinx.ext.autodoc*),
it will insert type comments into the docstring:

.. code-block:: python

   extensions = [
       "sphinx.ext.autodoc",
       "pygenstub"
   ]

As an example of the output, you can check the `API documentation`_
for pygenstub itself.

Getting help
------------

The documentation is available on: https://pygenstub.readthedocs.io/

The source code can be obtained from: https://github.com/uyar/pygenstub

License
-------

Copyright (C) 2016-2021 H. Turgut Uyar <uyar@tekir.org>

pygenstub is released under the GPL license, version 3 or later.
Read the included `LICENSE.txt`_ for details.

.. _PyPI: https://pypi.org/project/pygenstub/
.. _source file: https://github.com/uyar/pygenstub/blob/master/pygenstub.py
.. _stub file: https://github.com/uyar/pygenstub/blob/master/pygenstub.pyi
.. _API documentation: https://pygenstub.readthedocs.io/en/latest/api.html
.. _LICENSE.txt: https://github.com/uyar/pygenstub/blob/master/LICENSE.txt

