mypy.stubgen

module documentation
(source)

Generator of dynamically typed draft stubs for arbitrary modules. The logic of this script can be split in three steps: * parsing options and finding sources: - use runtime imports be default (to find also C modules) - or use mypy's mechanisms, if importing is prohibited * (optionally) semantically analysing the sources using mypy (as a single set) * emitting the stubs text: - for Python modules: from ASTs using StubGenerator - for C modules using runtime introspection and (optionally) Sphinx docs During first and third steps some problematic files can be skipped, but any blocking error during second step will cause the whole program to stop. Basic usage: $ stubgen foo.py bar.py some_directory => Generate out/foo.pyi, out/bar.pyi, and stubs for some_directory (recursively). $ stubgen -m urllib.parse => Generate out/urllib/parse.pyi. $ stubgen -p urllib => Generate stubs for whole urlib package (recursively). For C modules, you can get more precise function signatures by parsing .rst (Sphinx) documentation for extra information. For this, use the --doc-dir option: $ stubgen --doc-dir <DIR>/Python-3.4.2/Doc/library -m curses Note: The generated stubs should be verified manually. TODO: - maybe use .rst docs also for Python modules - maybe export more imported names if there is no __all__ (this affects ssl.SSLError, for example) - a quick and dirty heuristic would be to turn this on if a module has something like 'from x import y as _y' - we don't seem to always detect properties ('closed' in 'io', for example)

Class AliasPrinter Visitor used to collect type aliases _and_ type variable definitions.
Class AnnotationPrinter Visitor used to print existing annotations in a file.
Class DefinitionFinder Find names of things defined at the top level of a module.
Class ImportTracker Record necessary imports during stub generation.
Class Options Represents stubgen options.
Class ReferenceFinder Find all name references (both local and global).
Class SelfTraverser Undocumented
Class StubGenerator Generate stub text from a mypy AST.
Class StubSource A single source for stub: can be a Python or C module.
Function collect_build_targets Collect files for which we need to generate stubs.
Function collect_docs_signatures Gather all function and class signatures in the docs.
Function find_defined_names Undocumented
Function find_method_names Undocumented
Function find_module_paths_using_imports Find path and runtime value of __all__ (if possible) for modules and packages.
Function find_module_paths_using_search Find sources for modules and packages requested.
Function find_referenced_names Undocumented
Function find_self_initializers Find attribute initializers in a method.
Function generate_asts_for_modules Use mypy to parse (and optionally analyze) source files.
Function generate_stub_from_ast Use analysed (or just parsed) AST to generate type stub for single file.
Function generate_stubs Main entry point for the program.
Function get_qualified_name Undocumented
Function get_sig_generators Undocumented
Function is_blacklisted_path Undocumented
Function is_non_library_module Does module look like a test module or a script?
Function main Undocumented
Function mypy_options Generate mypy options using the flag passed by user.
Function normalize_path_separators Undocumented
Function parse_options Undocumented
Function parse_source_file Parse a source file.
Function remove_blacklisted_modules Undocumented
Function translate_module_name Undocumented
Constant BLACKLIST Undocumented
Constant CLASS Undocumented
Constant DESCRIPTION Undocumented
Constant EMPTY Undocumented
Constant EMPTY_CLASS Undocumented
Constant ERROR_MARKER Undocumented
Constant EXTRA_EXPORTED Undocumented
Constant FUNC Undocumented
Constant HEADER Undocumented
Constant IGNORED_DUNDERS Undocumented
Constant KNOWN_MAGIC_METHODS_RETURN_TYPES Undocumented
Constant METHODS_WITH_RETURN_VALUE Undocumented
Constant NOT_IN_ALL Undocumented
Constant TYPING_MODULE_NAMES Undocumented
Constant VAR Undocumented
Constant VENDOR_PACKAGES Undocumented
def collect_build_targets(options: Options, mypy_opts: MypyOptions) -> tuple[list[StubSource], list[StubSource]]: (source)

Collect files for which we need to generate stubs. Return list of Python modules and C modules.

def collect_docs_signatures(doc_dir: str) -> tuple[dict[str, str], dict[str, str]]: (source)

Gather all function and class signatures in the docs. Return a tuple (function signatures, class signatures). Currently only used for C modules.

def find_defined_names(file: MypyFile) -> set[str]: (source)

Undocumented

def find_method_names(defs: list[Statement]) -> set[str]: (source)

Undocumented

def find_module_paths_using_imports(modules: list[str], packages: list[str], verbose: bool, quiet: bool) -> tuple[list[StubSource], list[StubSource]]: (source)

Find path and runtime value of __all__ (if possible) for modules and packages. This function uses runtime Python imports to get the information.

def find_module_paths_using_search(modules: list[str], packages: list[str], search_path: list[str], pyversion: tuple[int, int]) -> list[StubSource]: (source)

Find sources for modules and packages requested. This function just looks for source files at the file system level. This is used if user passes --no-import, and will not find C modules. Exit if some of the modules or packages can't be found.

def find_referenced_names(file: MypyFile) -> set[str]: (source)

Undocumented

def find_self_initializers(fdef: FuncBase) -> list[tuple[str, Expression]]: (source)

Find attribute initializers in a method. Return a list of pairs (attribute name, r.h.s. expression).

def generate_asts_for_modules(py_modules: list[StubSource], parse_only: bool, mypy_options: MypyOptions, verbose: bool): (source)

Use mypy to parse (and optionally analyze) source files.

def generate_stub_from_ast(mod: StubSource, target: str, parse_only: bool = False, include_private: bool = False, export_less: bool = False): (source)

Use analysed (or just parsed) AST to generate type stub for single file. If directory for target doesn't exist it will created. Existing stub will be overwritten.

def generate_stubs(options: Options): (source)

Main entry point for the program.

def get_qualified_name(o: Expression) -> str: (source)

Undocumented

def get_sig_generators(options: Options) -> List[SignatureGenerator]: (source)

Undocumented

def is_blacklisted_path(path: str) -> bool: (source)

Undocumented

def is_non_library_module(module: str) -> bool: (source)

Does module look like a test module or a script?

def main(args: list[str]|None = None): (source)

Undocumented

def mypy_options(stubgen_options: Options) -> MypyOptions: (source)

Generate mypy options using the flag passed by user.

def normalize_path_separators(path: str) -> str: (source)

Undocumented

def parse_options(args: list[str]) -> Options: (source)

Undocumented

def parse_source_file(mod: StubSource, mypy_options: MypyOptions): (source)

Parse a source file. On success, store AST in the corresponding attribute of the stub source. If there are syntax errors, print them and exit.

def remove_blacklisted_modules(modules: list[StubSource]) -> list[StubSource]: (source)

Undocumented

def translate_module_name(module: str, relative: int) -> tuple[str, int]: (source)

Undocumented

BLACKLIST: list[str] = (source)

Undocumented

Value
['/six.py\n', '/vendored/', '/vendor/', '/_vendor/', '/_vendored_packages/']
CLASS: str = (source)

Undocumented

Value
'CLASS'
DESCRIPTION: str = (source)

Undocumented

Value
'''
Generate draft stubs for modules.

Stubs are generated in directory ./out, to avoid overriding files with
manual changes.  This directory is assumed to exist.
'''
EMPTY: str = (source)

Undocumented

Value
'EMPTY'
EMPTY_CLASS: str = (source)

Undocumented

Value
'EMPTY_CLASS'
ERROR_MARKER: str = (source)

Undocumented

Value
'<ERROR>'
EXTRA_EXPORTED: set[str] = (source)

Undocumented

Value
set(['pyasn1_modules.rfc2437.univ',
     'pyasn1_modules.rfc2459.char',
     'pyasn1_modules.rfc2459.univ'])
FUNC: str = (source)

Undocumented

Value
'FUNC'
HEADER: str = (source)

Undocumented

Value
'''%(prog)s [-h] [more options, see -h]
                     [-m MODULE] [-p PACKAGE] [files ...]'''
IGNORED_DUNDERS: set[str] = (source)

Undocumented

Value
set(['__all__',
     '__author__',
     '__version__',
     '__about__',
     '__copyright__',
     '__email__',
     '__license__',
...
KNOWN_MAGIC_METHODS_RETURN_TYPES: dict[str, str] = (source)

Undocumented

Value
{'__len__': 'int',
 '__length_hint__': 'int',
 '__init__': 'None',
 '__del__': 'None',
 '__bool__': 'bool',
 '__bytes__': 'bytes',
 '__format__': 'str',
...
METHODS_WITH_RETURN_VALUE: set[str] = (source)

Undocumented

Value
set(['__ne__',
     '__eq__',
     '__lt__',
     '__le__',
     '__gt__',
     '__ge__',
     '__hash__',
...
NOT_IN_ALL: str = (source)

Undocumented

Value
'NOT_IN_ALL'
TYPING_MODULE_NAMES: tuple[str, ...] = (source)

Undocumented

Value
('typing', 'typing_extensions')
VAR: str = (source)

Undocumented

Value
'VAR'
VENDOR_PACKAGES: list[str] = (source)

Undocumented

Value
['packages', 'vendor', 'vendored', '_vendor', '_vendored_packages']