.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "STUBGEN" "1" "Apr 24, 2024" "" "Mypy"
.SH NAME
stubgen \- Generate draft type hint stubs for Python modules
.SH SYNOPSIS
.sp
\fBstubgen\fP [\-h] [\-py2] [\-m \fIMODULE\fP] [\-p \fIPACKAGE\fP] [\fIOPTIONS\fP\&...] [\fIFILES\fP\&...]
.SH DESCRIPTION
.sp
Mypy is a static type checker for Python 3 and Python 2.7. Mypy includes
the \fIstubgen\fP tool that can automatically generate stub files (\fI\&.pyi\fP
files) for Python modules and C extension modules.
.sp
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).
.sp
Stubgen generates \fIdraft\fP stubs. The auto\-generated stub files often require some manual updates, and most types will default to \fIAny\fP\&. The stubs will be much more useful if you add more precise type annotations, at least for the most commonly used functionality.
.SH OPTIONS
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The command\-line flags may change between releases.
.UNINDENT
.UNINDENT
.SS Specifying what to stub
.sp
You can give stubgen paths of the source files for which you want to
generate stubs:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ stubgen foo.py bar.py
.EE
.UNINDENT
.UNINDENT
.sp
This generates stubs \fBout/foo.pyi\fP and \fBout/bar.pyi\fP\&. The default
output directory \fBout\fP can be overridden with \fI\%\-o DIR\fP\&.
.sp
You can also pass directories, and stubgen will recursively search
them for any \fB\&.py\fP files and generate stubs for all of them:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ stubgen my_pkg_dir
.EE
.UNINDENT
.UNINDENT
.sp
Alternatively, you can give module or package names using the
\fI\%\-m\fP or \fI\%\-p\fP options:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ stubgen \-m foo \-m bar \-p my_pkg_dir
.EE
.UNINDENT
.UNINDENT
.sp
Details of the options:
.INDENT 0.0
.TP
.B \-m MODULE, \-\-module MODULE
Generate a stub file for the given module. This flag may be repeated
multiple times.
.sp
Stubgen \fIwill not\fP recursively generate stubs for any submodules of
the provided module.
.UNINDENT
.INDENT 0.0
.TP
.B \-p PACKAGE, \-\-package PACKAGE
Generate stubs for the given package. This flag maybe repeated
multiple times.
.sp
Stubgen \fIwill\fP recursively generate stubs for all submodules of
the provided package. This flag is identical to \fI\%\-\-module\fP apart from
this behavior.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
You can\(aqt mix paths and \fI\%\-m\fP/\fI\%\-p\fP options in the same stubgen
invocation.
.UNINDENT
.UNINDENT
.sp
Stubgen applies heuristics to avoid generating stubs for submodules
that include tests or vendored third\-party packages.
.SS Specifying how to generate stubs
.sp
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:
.INDENT 0.0
.TP
.B \-\-no\-import
Don\(aqt try to import modules. Instead only use mypy\(aqs 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
\fB__all__\fP\&. 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.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-analysis
Don\(aqt 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 \fBAny\fP type. This is generally only
useful if semantic analysis causes a critical mypy error.  Does not apply to
C extension modules.  Incompatible with \fI\%\-\-inspect\-mode\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-inspect\-mode
Import and inspect modules instead of parsing source code. This is the default
behavior for C modules and pyc\-only packages.  The flag is useful to force
inspection for pure Python modules that make use of dynamically generated
members that would otherwise be omitted when using the default behavior of
code parsing.  Implies \fI\%\-\-no\-analysis\fP as analysis requires source
code.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-doc\-dir PATH
Try to infer better signatures by parsing .rst documentation in \fBPATH\fP\&.
This may result in better stubs, but currently it only works for C extension
modules.
.UNINDENT
.SS Additional flags
.INDENT 0.0
.TP
.B \-h, \-\-help
Show help message and exit.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-ignore\-errors
If an exception was raised during stub generation, continue to process any
remaining modules instead of immediately failing with an error.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-include\-private
Include definitions that are considered private in stubs (with names such
as \fB_foo\fP with single leading underscore and no trailing underscores).
.UNINDENT
.INDENT 0.0
.TP
.B \-\-export\-less
Don\(aqt 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.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-include\-docstrings
Include docstrings in stubs. This will add docstrings to Python function and
classes stubs and to C extension function stubs.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-search\-path PATH
Specify module search directories, separated by colons (only used if
\fI\%\-\-no\-import\fP is given).
.UNINDENT
.INDENT 0.0
.TP
.B \-o PATH, \-\-output PATH
Change the output directory. By default the stubs are written in the
\fB\&./out\fP directory. The output directory will be created if it doesn\(aqt
exist. Existing stubs in the output directory will be overwritten without
warning.
.UNINDENT
.INDENT 0.0
.TP
.B \-v, \-\-verbose
Produce more verbose output.
.UNINDENT
.INDENT 0.0
.TP
.B \-q, \-\-quiet
Produce less verbose output.
.UNINDENT
.SH ENVIRONMENT
.INDENT 0.0
.TP
\fBMYPYPATH\fP
Additional module search path entries. The format is the same as the shell\(aqs \fI$PATH\fP: one or more directory pathnames separated by colons.
.UNINDENT
.SH SEE ALSO
.sp
\fBmypy\fP(1)
.sp
Full documentation is available online at: \fI\%https://mypy.readthedocs.io/en/latest/stubgen.html\fP
or locally at: \fI\%/usr/share/doc/mypy/html\fP (requires \fImypy\-doc\fP package).
.SH AUTHOR
Jukka Lehtosalo and contributors
.\" Generated by docutils manpage writer.
.