Ubuntu Manpage: stubgen - Generate draft type hint stubs for Python modules

NAME

       stubgen - Generate draft type hint stubs for Python modules

SYNOPSIS

       stubgen [-h] [-py2] [-m MODULE] [-p PACKAGE] [OPTIONS...] [FILES...]

DESCRIPTION

       Mypy  is a static type checker for Python 3 and Python 2.7. Mypy includes the stubgen tool
       that can automatically generate stub files (.pyi files) for Python modules and C extension
       modules.

       A  stub  file (see PEP 484) contains only type hints for the public interface of a module,
       with empty function bodies. Mypy can use a stub file instead of the real implementation to
       provide  type  information  for  the module. They are useful for third-party modules whose
       authors have not yet added type hints (and when no stubs are available in typeshed) and  C
       extension modules (which mypy can’t directly process).

       Stubgen  generates  draft  stubs.  The auto-generated stub files often require some manual
       updates, and most types will default to Any. The stubs will be much more useful if you add
       more precise type annotations, at least for the most commonly used functionality.

OPTIONS

NOTE:
The command-line flags may change between releases.

Specifying what to stub
You can give stubgen paths of the source files for which you want to generate stubs:

$ stubgen foo.py bar.py

This generates stubs out/foo.pyi and out/bar.pyi. The default output directory out can be
overridden with
:option:`-o DIR <-o>`
.

System Message: ERROR/3 (debian/stubgen_options.rst:, line 14)
Unknown interpreted text role "option".

You can also pass directories, and stubgen will recursively search them for any .py
files and generate stubs for all of them:

$ stubgen my_pkg_dir

Alternatively, you can give module or package names using the -m or -p options:

$ stubgen -m foo -m bar -p my_pkg_dir

Details of the options:

System Message: ERROR/3 (debian/stubgen_options.rst:, line 29)
Unknown directive type "option".

.. option:: -m MODULE, --module MODULE

Generate a stub file for the given module. This flag may be repeated
multiple times.

Stubgen *will not* recursively generate stubs for any submodules of
the provided module.

System Message: ERROR/3 (debian/stubgen_options.rst:, line 37)
Unknown directive type "option".

.. option:: -p PACKAGE, --package PACKAGE

Generate stubs for the given package. This flag maybe repeated
multiple times.

Stubgen *will* recursively generate stubs for all submodules of
the provided package. This flag is identical to :option:`--module` apart from
this behavior.

NOTE:
You can't mix paths and
:option:`-m`
/
:option:`-p`
options in the same stubgen invocation.

System Message: ERROR/3 (debian/stubgen_options.rst:, line 48)
Unknown interpreted text role "option".

Stubgen applies heuristics to avoid generating stubs for submodules that include tests or
vendored third-party packages.

Specifying how to generate stubs
By default stubgen will try to import the target modules and packages. This allows
stubgen to use runtime introspection to generate stubs for C extension modules and to
improve the quality of the generated stubs. By default, stubgen will also use mypy to
perform light-weight semantic analysis of any Python modules. Use the following flags to
alter the default behavior:

System Message: ERROR/3 (debian/stubgen_options.rst:, line 64)
Unknown directive type "option".

.. option:: --no-import

Don't try to import modules. Instead only use mypy's normal search mechanism to find
sources. This does not support C extension modules. This flag also disables
runtime introspection functionality, which mypy uses to find the value of
``__all__``. As result the set of exported imported names in stubs may be
incomplete. This flag is generally only useful when importing a module causes
unwanted side effects, such as the running of tests. Stubgen tries to skip test
modules even without this option, but this does not always work.

System Message: ERROR/3 (debian/stubgen_options.rst:, line 74)
Unknown directive type "option".

.. option:: --parse-only

Don't perform semantic analysis of source files. This may generate
worse stubs -- in particular, some module, class, and function aliases may
be represented as variables with the ``Any`` type. This is generally only
useful if semantic analysis causes a critical mypy error.

System Message: ERROR/3 (debian/stubgen_options.rst:, line 81)
Unknown directive type "option".

.. option:: --doc-dir PATH

Try to infer better signatures by parsing .rst documentation in ``PATH``.
This may result in better stubs, but currently it only works for C extension
modules.

Additional flags
System Message: ERROR/3 (debian/stubgen_options.rst:, line 90)
Unknown directive type "option".

.. option:: --py2

Run stubgen in Python 2 mode (the default is Python 3 mode).

System Message: ERROR/3 (debian/stubgen_options.rst:, line 94)
Unknown directive type "option".

.. option:: --ignore-errors

If an exception was raised during stub generation, continue to process any
remaining modules instead of immediately failing with an error.

System Message: ERROR/3 (debian/stubgen_options.rst:, line 99)
Unknown directive type "option".

.. option:: --include-private

Include definitions that are considered private in stubs (with names such
as ``_foo`` with single leading underscore and no trailing underscores).

System Message: ERROR/3 (debian/stubgen_options.rst:, line 104)
Unknown directive type "option".

.. option:: --export-less

Don't export all names imported from other modules within the same package.
Instead, only export imported names that are not referenced in the module
that contains the import.

System Message: ERROR/3 (debian/stubgen_options.rst:, line 110)
Unknown directive type "option".

.. option:: --search-path PATH

Specify module search directories, separated by colons (only used if
:option:`--no-import` is given).

System Message: ERROR/3 (debian/stubgen_options.rst:, line 115)
Unknown directive type "option".

.. option:: --python-executable PATH

Use Python interpreter at ``PATH`` for importing modules and runtime
introspection. This has no effect with :option:`--no-import`, and this only works
in Python 2 mode. In Python 3 mode the Python interpreter used to run stubgen
will always be used.

System Message: ERROR/3 (debian/stubgen_options.rst:, line 122)
Unknown directive type "option".

.. option:: -o PATH, --output PATH

Change the output directory. By default the stubs are written in the
``./out`` directory. The output directory will be created if it doesn't
exist. Existing stubs in the output directory will be overwritten without
warning.

System Message: ERROR/3 (debian/stubgen_options.rst:, line 129)
Unknown directive type "option".

.. option:: -v, --verbose

Produce more verbose output.

System Message: ERROR/3 (debian/stubgen_options.rst:, line 133)
Unknown directive type "option".

.. option:: -q, --quiet

Produce less verbose output.

ENVIRONMENT

       MYPYPATH
              Additional module search path entries. The format is the same as the shell's $PATH:
              one or more directory pathnames separated by colons.

AUTHOR