Specifying what to stub¶

You can give stubgen paths of the source files for which you want togenerate stubs:

$ stubgen foo.py bar.py

This generates stubsout/foo.pyi andout/bar.pyi. The defaultoutput directoryout can be overridden with-oDIR.

You can also pass directories, and stubgen will recursively searchthem 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:

-mMODULE,--moduleMODULE¶

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

Stubgenwill not recursively generate stubs for any submodules ofthe provided module.

-pPACKAGE,--packagePACKAGE¶

Generate stubs for the given package. This flag maybe repeatedmultiple times.

Stubgenwill recursively generate stubs for all submodules ofthe provided package. This flag is identical to--module apart fromthis behavior.

Stubgen applies heuristics to avoid generating stubs for submodulesthat 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 Cextension modules and to improve the quality of the generatedstubs. By default, stubgen will also use mypy to perform light-weightsemantic analysis of any Python modules. Use the following flags toalter the default behavior:

--no-import¶

Don’t try to import modules. Instead only use mypy’s normal search mechanism to findsources. This does not support C extension modules. This flag also disablesruntime introspection functionality, which mypy uses to find the value of__all__. As result the set of exported imported names in stubs may beincomplete. This flag is generally only useful when importing a module causesunwanted side effects, such as the running of tests. Stubgen tries to skip testmodules even without this option, but this does not always work.

--no-analysis¶

Don’t perform semantic analysis of source files. This may generateworse stubs – in particular, some module, class, and function aliases maybe represented as variables with theAny type. This is generally onlyuseful if semantic analysis causes a critical mypy error. Does not apply toC extension modules. Incompatible with--inspect-mode.

--inspect-mode¶

Import and inspect modules instead of parsing source code. This is the defaultbehavior for C modules and pyc-only packages. The flag is useful to forceinspection for pure Python modules that make use of dynamically generatedmembers that would otherwise be omitted when using the default behavior ofcode parsing. Implies--no-analysis as analysis requires sourcecode.

--doc-dirPATH¶

Try to infer better signatures by parsing .rst documentation inPATH.This may result in better stubs, but currently it only works for C extensionmodules.

Additional flags¶

-h,--help¶

Show help message and exit.

--ignore-errors¶

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

--include-private¶

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

--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 modulethat contains the import.

--include-docstrings¶

Include docstrings in stubs. This will add docstrings to Python function andclasses stubs and to C extension function stubs.

--search-pathPATH¶

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

-oPATH,--outputPATH¶

Change the output directory. By default the stubs are written in the./out directory. The output directory will be created if it doesn’texist. Existing stubs in the output directory will be overwritten withoutwarning.

-v,--verbose¶

Produce more verbose output.

-q,--quiet¶

Produce less verbose output.