pydoctor.astutils

module documentation

(source)

Various bits of reusable code related to ast.AST node processing.

Class	`NodeVisitor`	Generic AST node visitor. This class does not work like `ast.NodeVisitor`, it only visits statements directly within a `body`. Also, visitor methods can't return anything.
Class	`NodeVisitorExt`	Undocumented
Class	`op_util`	This class provides data and functions for mapping AST nodes to symbols and precedences.
Class	`Parentage`	Add `parent` attribute to ast nodes instances.
Class	`Str`	Wraps ast.Constant/ast.Str for `isinstance` checks and annotations. Ensures that the value is actually a string. Do not try to instanciate this class.
Function	`bind_args`	Binds the arguments of a function call to that function's signature.
Function	`extract_docstring`	Extract docstring information from an ast node that represents the docstring.
Function	`extract_docstring_linenum`	In older CPython versions, the AST only tells us the end line number and we must approximate the start line number. This approximation is correct if the docstring does not contain explicit newlines ('\n') or joined lines ('\' at end of line).
Function	`get_docstring_node`	Return the docstring node for the given class, function or module or None if no docstring can be found.
Function	`get_int_value`	Undocumented
Function	`get_num_value`	Undocumented
Function	`get_parents`	Once nodes have the `.parent` attribute with {Parentage}, use this function to get a iterator on all parents of the given node up to the root module.
Function	`get_str_value`	Undocumented
Function	`infer_type`	Infer a literal expression's type.
Function	`is__name__equals__main__`	Returns whether or not the given `ast.Compare` is equal to `__name__ == '__main__'`.
Function	`is_none_literal`	Does this AST node represent the literal constant None?
Function	`is_typing_annotation`	Whether this annotation node refers to a typing alias.
Function	`is_using_annotations`	Detect if this expr is firstly composed by one of the specified annotation(s)' full name.
Function	`is_using_typing_classvar`	Undocumented
Function	`is_using_typing_final`	Undocumented
Function	`iter_values`	Undocumented
Function	`iterassign`	Utility function to iterate assignments targets.
Function	`node2dottedname`	Resove expression composed by `ast.Attribute` and `ast.Name` nodes to a list of names.
Function	`node2fullname`	Undocumented
Function	`unparse`	This function convert a node tree back into python sourcecode.
Function	`unstring_annotation`	Replace all strings in the given expression by parsed versions.
Constant	`SUBSCRIPTABLE_CLASSES_PEP585`	Undocumented
Constant	`TYPING_ALIAS`	Undocumented
Class	`_AnnotationStringParser`	Implementation of `unstring_annotation()`.
Class	`_StrMeta`	Undocumented
Function	`_annotation_for_elements`	Undocumented
Function	`_annotation_for_value`	Undocumented
Function	`_is_str_constant`	Undocumented
Type Alias	`_AssingT`	Undocumented
Variable	`_deprecated`	Undocumented
Variable	`_op_data`	Undocumented
Variable	`_precedence_data`	Undocumented
Variable	`_string_lineno_is_end`	True iff the 'lineno' attribute of an AST string node points to the last line in the string, rather than the first line.
Variable	`_symbol_data`	Undocumented

def bind_args(sig: Signature, call: ast.Call) -> BoundArguments: (source) ¶

Binds the arguments of a function call to that function's signature.

Raises
`TypeError`	If the arguments do not match the signature.

def extract_docstring(node: Str) -> Tuple[int, str]: (source) ¶

Extract docstring information from an ast node that represents the docstring.

Returns
`Tuple[int, str]`	The line number of the first non-blank line of the docsring. See `extract_docstring_linenum`. The docstring to be parsed, cleaned by `inspect.cleandoc`.

def extract_docstring_linenum(node: Str) -> int: (source) ¶

In older CPython versions, the AST only tells us the end line number and we must approximate the start line number. This approximation is correct if the docstring does not contain explicit newlines ('\n') or joined lines ('\' at end of line).

Leading blank lines are stripped by cleandoc(), so we must return the line number of the first non-blank line.

def get_docstring_node(node: ast.AST) -> Str|None: (source) ¶

Return the docstring node for the given class, function or module or None if no docstring can be found.

def get_int_value(expr: ast.expr) -> Optional[int]: (source) ¶

Undocumented

def get_num_value(expr: ast.expr) -> Optional[Number]: (source) ¶

Undocumented

def get_parents(node: ast.AST) -> Iterator[ast.AST]: (source) ¶

Once nodes have the .parent attribute with {Parentage}, use this function to get a iterator on all parents of the given node up to the root module.

def get_str_value(expr: ast.expr) -> Optional[str]: (source) ¶

Undocumented

def infer_type(expr: ast.expr) -> Optional[ast.expr]: (source) ¶

Infer a literal expression's type.

Parameters
expr:`ast.expr`	The expression's AST.
Returns
`Optional[ast.expr]`	A type annotation, or None if the expression has no obvious type.

def is__name__equals__main__(cmp: ast.Compare) -> bool: (source) ¶

Returns whether or not the given ast.Compare is equal to __name__ == '__main__'.

def is_none_literal(node: ast.expr) -> bool: (source) ¶

Does this AST node represent the literal constant None?

def is_typing_annotation(node: ast.AST, ctx: model.Documentable) -> bool: (source) ¶

Whether this annotation node refers to a typing alias.

def is_using_annotations(expr: Optional[ast.AST], annotations: Sequence[str], ctx: model.Documentable) -> bool: (source) ¶

Detect if this expr is firstly composed by one of the specified annotation(s)' full name.

def is_using_typing_classvar(expr: Optional[ast.AST], ctx: model.Documentable) -> bool: (source) ¶

Undocumented

def is_using_typing_final(expr: Optional[ast.AST], ctx: model.Documentable) -> bool: (source) ¶

Undocumented

def iter_values(node: ast.AST) -> Iterator[ast.AST]: (source) ¶

Undocumented

def iterassign(node: _AssingT) -> Iterator[Optional[List[str]]]: (source) ¶

Utility function to iterate assignments targets.

Useful for all the following AST assignments:

>>> var:int=2
>>> self.var = target = node.astext()
>>> lol = ['extensions']

NOT Useful for the following AST assignments:

>>> x, y = [1,2]

Example:

>>> from pydoctor.astutils import iterassign
>>> from ast import parse
>>> node = parse('self.var = target = thing[0] = node.astext()').body[0]
>>> list(iterassign(node))

def node2dottedname(node: Optional[ast.AST]) -> Optional[List[str]]: (source) ¶

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

def node2fullname(expr: Optional[ast.AST], ctx: model.Documentable) -> Optional[str]: (source) ¶

Undocumented

def unparse(node: ast.AST) -> str: (source) ¶

This function convert a node tree back into python sourcecode.

Uses ast.unparse or astor.to_source for python versions before 3.9.

def unstring_annotation(node: ast.expr, ctx: model.Documentable, section: str = 'annotation') -> ast.expr: (source) ¶

Replace all strings in the given expression by parsed versions.

Returns
`ast.expr`	The unstringed node. If parsing fails, an error is logged and the original node is returned.

SUBSCRIPTABLE_CLASSES_PEP585: tuple[str, ...] = (source) ¶

Undocumented

Value

('tuple',
 'list',
 'dict',
 'set',
 'frozenset',
 'type',
 'collections.deque',
...

TYPING_ALIAS: tuple[str, ...] = (source) ¶

Undocumented

Value

('typing.Hashable',
 'typing.Awaitable',
 'typing.Coroutine',
 'typing.AsyncIterable',
 'typing.AsyncIterator',
 'typing.Iterable',
 'typing.Iterator',
...