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_assign_docstring_node`	Get the docstring for a `ast.Assign` or `ast.AnnAssign` node.
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_node_block`	Tell in wich block the given node lives in.
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	`has_comment_line`	Returns True if the is a comment line in between node1 and node2.
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_old_school_namespace_package`	Returns True if the module is a pre PEP 420 namespace package:
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	`unstring_annotation`	Replace all strings in the given expression by parsed versions.
Function	`upgrade_annotation`	Transform the annotation to use python 3.10+ syntax.
Constant	`DEPRECATED_TYPING_ALIAS_BUILTINS`	Undocumented
Constant	`SUBSCRIPTABLE_CLASSES_PEP585`	Undocumented
Constant	`TYPING_ALIAS`	Undocumented
Class	`_AnnotationStringParser`	Implementation of `unstring_annotation()`.
Class	`_OldSchoolNamespacePackageVis`	Undocumented
Class	`_StrMeta`	Undocumented
Class	`_UpgradeDeprecatedAnnotations`	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	`_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_assign_docstring_node(assign: ast.Assign | ast.AnnAssign) -> Str | None: (source) ¶

Get the docstring for a ast.Assign or ast.AnnAssign node.

This helper function relies on the non-standard .parent attribute on AST nodes to navigate upward in the tree and determine this node direct siblings.

Note
This does not validate whether there is a comment in between the assigment and the docstring node since the function operates on AST solely. Use `has_comment_line` for that.

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) -> int | None: (source) ¶

Undocumented

def get_node_block(node: ast.AST) -> tuple[ast.AST, str]: (source) ¶

Tell in wich block the given node lives in.

A block is defined by a tuple: (parent node, fieldname)

Raises
`ValueError`	If the assignment parent is missing or boggus.

def get_num_value(expr: ast.expr) -> Number | None: (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) -> str | None: (source) ¶

Undocumented

def has_comment_line(node1: ast.expr | ast.stmt, node2: ast.expr | ast.stmt, lines: Sequence[str]) -> bool: (source) ¶

Returns True if the is a comment line in between node1 and node2.

>>> from pydoctor.model import ParsedAstModule
>>> from pydoctor.astbuilder import SyntaxTreeParser
>>> src = 'var = 1\n# this is a comment\nfoo = 2\n\n\nplum = 3'
>>> parsed = SyntaxTreeParser().parseString(src, None)
>>> has_comment_line(parsed.root.body[0], parsed.root.body[1], parsed.lines)
True
>>> has_comment_line(parsed.root.body[1], parsed.root.body[2], parsed.lines)
False

Raises
`IndexError`	If the line numbers coming from `node1` or `node2` are not present in the given `lines`.

def infer_type(expr: ast.expr) -> ast.expr | None: (source) ¶

Infer a literal expression's type.

Parameters
expr:`ast.expr`	The expression's AST.

Returns
`ast.expr \| None`	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_old_school_namespace_package(tree: ast.Module) -> bool: (source) ¶

Returns True if the module is a pre PEP 420 namespace package:

    from pkgutil import extend_path
    __path__ = extend_path(__path__, __name__)
    # OR
    import pkg_resources
    pkg_resources.declare_namespace(__name__)
    # OR
    __import__('pkg_resources').declare_namespace(__name__)
    # OR
    import pkg_resources
    pkg_resources.declare_namespace(name=__name__)

The following code will return False, tho:

    from pkgutil import extend_path
    __path__ = extend_path(__path__, __name__ + '.impl')

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: ast.AST | None, 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: ast.AST | None, ctx: model.Documentable) -> bool: (source) ¶

Undocumented

def is_using_typing_final(expr: ast.AST | None, ctx: model.Documentable) -> bool: (source) ¶

Undocumented

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

Undocumented

def iterassign(node: _AssingT) -> Iterator[list[str] | None]: (source) ¶

Utility function to iterate assignments targets.

Useful for all the following AST assignments:

    var:int=2
    self.var = target = node.astext()
    ol = ['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))
[['self', 'var'], ['target'], None]

def node2dottedname(node: ast.AST | None) -> list[str] | None: (source) ¶

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

def node2fullname(expr: ast.AST | None, ctx: model.Documentable | None = None, *, expandName: Callable[[str], str] | None = None) -> str | None: (source) ¶

Undocumented

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.

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

Transform the annotation to use python 3.10+ syntax.

DEPRECATED_TYPING_ALIAS_BUILTINS: dict[str, str] = (source) ¶

Undocumented

Value

{'typing.Text': 'str',
 'typing.Dict': 'dict',
 'typing.Tuple': 'tuple',
 'typing.Type': 'type',
 'typing.List': 'list',
 'typing.Set': 'set',
 'typing.FrozenSet': 'frozenset'}

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

Undocumented

Value

('tuple',
 'list',
 'dict',
 'set',
 'frozenset',
 'type',
 'builtins.tuple',
...

TYPING_ALIAS = (source) ¶

Undocumented

Value

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

def _annotation_for_elements(sequence: Iterable[object]) -> ast.expr | None: (source) ¶

Undocumented

def _annotation_for_value(value: object) -> ast.expr | None: (source) ¶

Undocumented

def _is_str_constant(expr: ast.expr, s: str) -> bool: (source) ¶

Undocumented

_AssingT = (source) ¶

Undocumented

Value

ast.Assign | ast.AnnAssign

_deprecated: Collection[str] = (source) ¶

Undocumented

_op_data = (source) ¶

Undocumented

_precedence_data = (source) ¶

Undocumented

_symbol_data = (source) ¶

Undocumented