pydocspec.astroidutils

module documentation

(source)

Various bits of reusable code related to astroid.nodes.NodeNG node processing.

Class	`NodeTransformer`	A `NodeVisitor` subclass that walks the abstract syntax tree and allows modification of nodes. The `NodeTransformer` will walk the AST and use the return value of the visitor methods to replace or remove the old node...
Class	`NodeVisitor`	A node visitor base class that walks the abstract syntax tree and calls a visitor function for every node found. This function may return a value which is forwarded by the `visit` method. This class is meant to be subclassed, with the subclass adding visitor methods...
Class	`SignatureBuilder`	Builds a signature, parameter by parameter, with customizable value formatter and signature classes.
Class	`ValueFormatter`	Formats values stored in AST expressions back to source code. Used for presenting default values of parameters and annotations.
Function	`bind_args`	Binds the arguments of a function call to that function's signature. :raise TypeError: If the arguments do not match the signature.
Function	`build_signature`	Builds `inspect.Signature` representing this function's parameters and return value.
Function	`copy_location`	Copy source location (`lineno`, `col_offset`, `end_lineno`, and `end_col_offset` attributes) from old_node to new_node if possible, and return new_node.
Function	`extract_expr`	Convert a python expression to ast.
Function	`extract_final_subscript`	Extract the "str" part from annotations like "Final[str]".
Function	`fix_missing_locations`	When you compile a node tree with compile(), the compiler expects lineno and col_offset attributes for every node that supports them. This is rather tedious to fill in for generated nodes, so this helper adds these attributes recursively where not already set, by setting them to the values of the parent node...
Function	`get_full_import_name`	Get the full path of a name from a `from x import y` statement.
Function	`infer_type_annotation`	Infer an expression's type. :param expr: The expression's AST. :return: A type annotation, or None if the expression has no obvious type.
Function	`is_name`	A name is an expression composed by `astroid.nodes.Attribute` and `astroid.nodes.Name` nodes :returns: `True` if value is a valid name.
Function	`is_type_guard`	Return True if the If statement is a typing guard.
Function	`is_type_guarded`	Return True if one of the parent(s) of a node is a typing guard.
Function	`iter_fields`	Given a node, get the fields names and their values. We need the fields names in NodeTransformer.
Function	`iter_values`	Undocumented
Function	`literal_eval`	Safely evaluate an expression node or a string containing a Python expression. The string or node provided may only consist of the following Python literal structures: strings, bytes, numbers, tuples, lists, dicts, sets, booleans, and None.
Function	`merge_annotations`	Undocumented
Function	`node2dottedname`	Resove expression composed by `astroid.nodes.Attribute` and `astroid.nodes.Name` nodes to a list of names.
Function	`node2fullname`	Return `ctx.expand_name(name)` if `expr` is a valid name, or `None`.
Function	`resolve_import_alias`	Resolve a name from an aliased import to its original name.
Function	`resolve_qualname`	Resolve a basename to get its fully qualified name.
Function	`to_source`	This function convert a node tree back into python sourcecode.
Function	`unstring_annotation`	Replace all strings in the given expression by parsed versions. :return: The unstringed node. If parsing fails, an error is logged
Variable	`nodefactory`	Acts like every node arguments can be passed to the constructor method.
Class	`_AnnotationStringParser`	Implementation of `unstring_annotation`.
Class	`_NodeConstructorMethod`	Undocumented
Class	`_NodeFactory`	Easy create NodeNG instances.
Function	`_annotation_for_elements`	Undocumented
Function	`_annotation_for_value`	Undocumented
Function	`_is_ellipsis`	Undocumented
Function	`_iter_args`	Undocumented

def bind_args(sig, call): (source)

Binds the arguments of a function call to that function's signature. :raise TypeError: If the arguments do not match the signature.

Parameters
sig:`inspect.Signature`	Undocumented
call:`astroid.nodes.Call`	Undocumented
Returns
`inspect.BoundArguments`	Undocumented

def build_signature(func): (source)

Builds inspect.Signature representing this function's parameters and return value.

Parameters
func:`Union[astroid.nodes.AsyncFunctionDef, astroid.nodes.FunctionDef]`	Undocumented
Returns
`inspect.Signature`	Undocumented
Raises
`ValueError`	If the function has invalid parameters.

def copy_location(new_node, old_node): (source)

Copy source location (lineno, col_offset, end_lineno, and end_col_offset attributes) from old_node to new_node if possible, and return new_node.

Parameters
new_node:`astroid.nodes.NodeNG`	Undocumented
old_node:`astroid.nodes.NodeNG`	Undocumented
Returns
`astroid.nodes.NodeNG`	Undocumented

def extract_expr(expr, filename=None, allow_stmt=False): (source)

Convert a python expression to ast.

Can raise SyntaxError if invalid python sytax or if got statements instead of expression.

Parameters
expr:`str`	Undocumented
filename:`Optional[str]`	Undocumented
allow_stmt:`bool`	Undocumented
Returns
`astroid.nodes.NodeNG`	Undocumented

def extract_final_subscript(annotation): (source)

Extract the "str" part from annotations like "Final[str]".

@raises ValueError: If the "Final" annotation is not valid.

Parameters
annotation:`astroid.nodes.Subscript`	Undocumented
Returns
`astroid.nodes.NodeNG`	Undocumented

def fix_missing_locations(node): (source)

When you compile a node tree with compile(), the compiler expects lineno and col_offset attributes for every node that supports them. This is rather tedious to fill in for generated nodes, so this helper adds these attributes recursively where not already set, by setting them to the values of the parent node. It works recursively starting at node.

Parameters
node:`astroid.nodes.NodeNG`	Undocumented
Returns
`astroid.nodes.NodeNG`	Undocumented

def get_full_import_name(import_from, name): (source)

Get the full path of a name from a from x import y statement.

Parameters
import_from:`astroid.nodes.ImportFrom`	The astroid node to resolve the name of.
name:`str`
Returns
`str`	The full import path of the name.

def infer_type_annotation(expr): (source)

Infer an expression's type. :param expr: The expression's AST. :return: A type annotation, or None if the expression has no obvious type.

Parameters
expr:`Optional[astroid.nodes.NodeNG]`	Undocumented
Returns
`Optional[astroid.nodes.NodeNG]`	Undocumented

def is_name(value): (source)

A name is an expression composed by astroid.nodes.Attribute and astroid.nodes.Name nodes :returns: True if value is a valid name.

Parameters
value:`Optional[astroid.nodes.NodeNG]`	Undocumented
Returns
`bool`	Undocumented

def is_type_guard(node): (source)

Return True if the If statement is a typing guard.

Parameters
node:`astroid.nodes.If`	Undocumented
Returns
`bool`	Undocumented

def is_type_guarded(node, ctx): (source)

Return True if one of the parent(s) of a node is a typing guard.

Parameters
node:`Optional[astroid.nodes.NodeNG]`	Undocumented
ctx:`_model.ApiObject`	Undocumented
Returns
`bool`	Undocumented

def iter_fields(node): (source)

Given a node, get the fields names and their values. We need the fields names in NodeTransformer.

Parameters
node:`astroid.nodes.NodeNG`	Undocumented
Returns
`Iterator[Tuple[str, Any]]`	Undocumented

def iter_values(node): (source)

Undocumented

Parameters
node:`astroid.nodes.NodeNG`	Undocumented
Returns
`Iterator[astroid.nodes.NodeNG]`	Undocumented

def literal_eval(node_or_string): (source)

Safely evaluate an expression node or a string containing a Python expression. The string or node provided may only consist of the following Python literal structures: strings, bytes, numbers, tuples, lists, dicts, sets, booleans, and None.

Parameters
node_or_string:`Union[str, astroid.nodes.NodeNG]`	Undocumented
Returns
`Any`	Undocumented

def merge_annotations(annotations, comment_annotations): (source)

Undocumented

Parameters
annotations:`Iterable[Optional[astroid.nodes.NodeNG]]`	Undocumented
comment_annotations:`Iterable[Optional[astroid.nodes.NodeNG]]`	Undocumented
Returns
`Iterator[Optional[astroid.nodes.NodeNG]]`	Undocumented

def node2dottedname(node, strict=False): (source)

Resove expression composed by astroid.nodes.Attribute and astroid.nodes.Name nodes to a list of names.

Parameters
node:`Optional[astroid.nodes.NodeNG]`	Undocumented
strict:`bool`	Undocumented
Returns
`Optional[List[str]]`	Undocumented
Notes
Supports variants `AssignAttr` and `AssignName`.
Strips the subscript slice, i.e. `Generic[T]` -> `Generic`, except if scrict=True.

def node2fullname(expr, ctx): (source)

Return ctx.expand_name(name) if expr is a valid name, or None.

Parameters
expr:`Optional[astroid.nodes.NodeNG]`	Undocumented
ctx:`ApiObject`	Undocumented
Returns
`Optional[str]`	Undocumented

def resolve_import_alias(name, import_names): (source)

Resolve a name from an aliased import to its original name.

Parameters
name:`str`	The potentially aliased name to resolve.
import_names:`Iterable[Tuple[str, Union[str, None]]]`	The pairs of original names and aliases from the import.
Returns
`str`	The original name.

def resolve_qualname(ctx, basename): (source)

Resolve a basename to get its fully qualified name.

Parameters
ctx:`astroid.nodes.NodeNG`	The node representing the base name.
basename:`str`	The partial base name to resolve.
Returns
`str`	The fully resolved base name.

def to_source(expr): (source)

This function convert a node tree back into python sourcecode.

Parameters
expr:`astroid.nodes.NodeNG`	Undocumented
Returns
`str`	Undocumented

def unstring_annotation(node): (source)

Replace all strings in the given expression by parsed versions. :return: The unstringed node. If parsing fails, an error is logged

and the original node is returned.

Parameters
node:`astroid.nodes.NodeNG`	Undocumented
Returns
`astroid.nodes.NodeNG`	Undocumented
Raises
`SyntaxError`	if the annotation is invalid.

nodefactory = (source)

Acts like every node arguments can be passed to the constructor method.

def _annotation_for_elements(sequence): (source)

Undocumented

Parameters
sequence:`Iterable[object]`	Undocumented
Returns
`Optional[astroid.nodes.NodeNG]`	Undocumented

def _annotation_for_value(value): (source)

Undocumented

Parameters
value:`object`	Undocumented
Returns
`Optional[astroid.nodes.NodeNG]`	Undocumented

def _is_ellipsis(node): (source)

Undocumented

Parameters
node:`astroid.nodes.NodeNG`	Undocumented
Returns
`bool`	Undocumented

def _iter_args(args, annotations, defaults): (source)

Undocumented

Parameters
args:`List[astroid.nodes.AssignName]`	Undocumented
annotations:`List[astroid.nodes.AssignName]`	Undocumented
defaults:`List[astroid.nodes.AssignName]`	Undocumented
Returns
`Iterator[Tuple[str, Optional[astroid.nodes.NodeNG], Optional[astroid.nodes.NodeNG]]]`	Undocumented