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.