API

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

It takes a source file as input and creates a stub file with the same base name and the .pyi extension.

For more information, please refer to the documentation: https://pygenstub.tekir.org/

class pygenstub.ClassNode(name, bases, signature=None)

Bases: pygenstub.StubNode

A node representing a class in a stub tree.

Parameters:
  • name (str) – Name of class.
  • bases (Sequence[str]) – Base classes of class.
  • signature (Optional[str]) – Signature of class, to be used in __init__ method.
get_code()

Get the stub code for this class.

Return type:List[str]
Returns:Lines of stub code for this class.
class pygenstub.FunctionNode(name, parameters, rtype, decorators=None)

Bases: pygenstub.StubNode

A node representing a function in a stub tree.

Parameters:
  • name (str) – Name of function.
  • parameters (Sequence[Tuple[str, str, bool]]) – List of parameter triples (name, type, has_default).
  • rtype (str) – Type of return value.
  • decorators (Optional[Sequence[str]]) – Decorators of function.
get_code()

Get the stub code for this function.

Return type:List[str]
Returns:Lines of stub code for this function.
class pygenstub.StubGenerator(source, generic=False)

Bases: ast.NodeVisitor

A transformer that generates stub declarations from a source code.

Parameters:
  • source (str) – Source code to generate the stub for.
  • generic (bool) – Whether to produce generic stubs.
collect_aliases()

Collect the type aliases in the source.

static generate_import_from(module_, names)

Generate an import line.

Parameters:
  • module (str) – Name of module to import the names from.
  • names (Set[str]) – Names to import.
Return type:

str

Returns:

Import line in stub code.

generate_stub()

Generate the stub code for this source.

Return type:str
Returns:Generated stub code.
get_function_node(node)

Process a function node.

Parameters:node – Node to process.
Return type:FunctionNode
Returns:Generated function node in stub tree.
visit_Assign(node)

Visit an assignment node.

visit_AsyncFunctionDef(node)

Visit an async function node.

visit_ClassDef(node)

Visit a class node.

visit_FunctionDef(node)

Visit a function node.

visit_Import(node)

Visit an import node.

visit_ImportFrom(node)

Visit an from-import node.

class pygenstub.StubNode

Bases: object

A node in a stub tree.

add_child(node)

Add a function/method or class node to this node.

Parameters:node – Function or class node to add.
add_variable(node)

Add a variable node to this node.

Parameters:node – Variable node to add.
get_code()

Get the stub code for this node.

The stub code for a node consists of the type annotations of its variables, followed by the prototypes of its functions/methods and classes.

Return type:List[str]
Returns:Lines of stub code for this node.
class pygenstub.VariableNode(name, type_)

Bases: pygenstub.StubNode

A node representing an assignment in a stub tree.

Parameters:
  • name (str) – Name of variable that is being assigned to.
  • type (str) – Type of variable.
get_code()

Get the type annotation for this variable.

Return type:List[str]
Returns:Lines of stub code for this variable.
pygenstub.extract_signature(docstring)

Extract the signature from a docstring.

Parameters:docstring (str) – Docstring to extract the signature from.
Return type:Optional[str]
Returns:Extracted signature, or None if there’s no signature.
pygenstub.get_aliases(lines)

Get the type aliases in the source.

Parameters:lines (Sequence[str]) – Lines of the source code.
Return type:Dict[str, str]
Returns:Aliases and their their definitions.
pygenstub.get_fields(node, fields_tag='field_list')

Get the field names and their values from a node.

Parameters:
  • node (Document docutils.nodes.document) – Node to get the fields from.
  • fields_tag (str) – Tag of child node that contains the fields.
Return type:

Dict[str, str]

Returns:

Names and values of fields.

pygenstub.get_mod_paths(mod_name, out_dir)

Get source and stub paths for a module.

pygenstub.get_pkg_paths(pkg_name, out_dir)

Recursively get all source and stub paths for a package.

pygenstub.get_signature(node)

Get the signature of a function or a class.

Parameters:node (Union[ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef]) – Node to get the signature from.
Return type:Optional[str]
Returns:Value of signature field in node docstring, or None if there’s no signature.
pygenstub.get_stub(source, generic=False)

Get the stub code for a source code.

Parameters:
  • source (str) – Source code to generate the stub for.
  • generic (bool) – Whether to produce generic stubs.
Return type:

str

Returns:

Generated stub code.

pygenstub.main(argv=None)

Start the command line interface.

pygenstub.parse_signature(signature)

Parse a signature into its input and return parameter types.

This will also collect the types that are required by any of the input and return types.

Parameters:signature (str) – Signature to parse.
Return type:Tuple[List[str], str, Set[str]]
Returns:Input parameter types, return type, and all required types.
pygenstub.process_docstring(app, what, name, obj, options, lines)

Modify the docstring before generating documentation.

This will insert type declarations for parameters and return type into the docstring, and remove the signature field so that it will be excluded from the generated document.

pygenstub.setup(app)

Register to Sphinx.

pygenstub.split_parameter_types(parameters)

Split a parameter types declaration into individual types.

The input is the left hand side of a signature (the part before the arrow), excluding the parentheses.

Parameters:parameters (str) – Comma separated parameter types.
Return type:List[str]
Returns:Parameter types.