module documentation

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.
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 _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 _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
TypeErrorIf 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]
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) -> int | None: (source)

Undocumented

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 infer_type(expr: ast.expr) -> ast.expr | None: (source)

Infer a literal expression's type.

Parameters
expr:ast.exprThe expression's AST.
Returns
ast.expr | NoneA 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: 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()
>>> 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: 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 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.exprThe 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

Undocumented

_op_data = (source)

Undocumented

_precedence_data = (source)

Undocumented

_string_lineno_is_end = (source)

True iff the 'lineno' attribute of an AST string node points to the last line in the string, rather than the first line.

_symbol_data = (source)

Undocumented