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 collect_assigns Returns a list of ast.Assign or ast.AnnAssign declared in the given scope. It does not include assignments in nested scopes.
Function dottedname2node Reverse operation of node2dottedname.
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_literal_arg Retreive the literal value of an argument from the BoundArguments. Only works with purely literal values (no Name or Attribute).
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 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_decorators Utility function to iterate decorators.
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 safe_bind_args Binds the arguments of a function call to that function's signature.
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
Class _V Undocumented
Function _annotation_for_elements Undocumented
Function _annotation_for_value Undocumented
Function _collect_nodes Undocumented
Function _get_literal_arg Helper function for get_literal_arg.
Function _is_str_constant Undocumented
Constant _SCOPE_TYPES Undocumented
Type Variable _T Undocumented
Type Alias _AssingT Undocumented
Type Alias _ClassInfo 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
TypeErrorIf the arguments do not match the signature.
def collect_assigns(node: ast.AST) -> Sequence[ast.Assign | ast.AnnAssign]: (source)

Returns a list of ast.Assign or ast.AnnAssign declared in the given scope. It does not include assignments in nested scopes.

def dottedname2node(parts: list[str]) -> ast.Name | ast.Attribute: (source)

Reverse operation of node2dottedname.

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_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.

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_literal_arg(args: BoundArguments, name: str, default: _T, typecheck: type[_T] | tuple[type[_T], ...], lineno: int, ctx: model.Documentable) -> _T: (source)

Retreive the literal value of an argument from the BoundArguments. Only works with purely literal values (no Name or Attribute).

Parameters
args:BoundArgumentsThe BoundArguments instance.
name:strThe name of the argument
default:_TThe default value of the argument, this value is returned if the argument is not found.
typecheck:type[_T] | tuple[type[_T], ...]The type of the literal value this argument is expected to have.
lineno:intThe lineumber of the callsite, used for error reporting.
ctx:model.DocumentableUndocumented
moduleModule that contains the call, used for error reporting.
Returns
_TThe value of the argument if we can infer it, otherwise returns the default value.
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)

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_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_decorators(decorator_list: list[ast.expr], ctx: model.Documentable) -> Iterator[tuple[str | None, ast.expr]]: (source)

Utility function to iterate decorators.

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 safe_bind_args(sig: Signature, call: ast.AST, ctx: model.Documentable) -> inspect.BoundArguments | None: (source)

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

When bind_args raises a TypeError, it reports a warning and returns None.

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 _collect_nodes(node: ast.AST, typecheck: _ClassInfo, stop_typecheck: _ClassInfo = _SCOPE_TYPES) -> Sequence[ast.AST]: (source)

Undocumented

def _get_literal_arg(args: BoundArguments, name: str, typecheck: type[_T] | tuple[type[_T], ...]) -> Literal[_V.NoValue] | _T: (source)

Helper function for get_literal_arg.

If the value is not present in the arguments, returns _V.NoValue.

Raises
ValueErrorIf the passed value is not a literal or if it's not the right type.
def _is_str_constant(expr: ast.expr, s: str) -> bool: (source)

Undocumented

_SCOPE_TYPES = (source)

Undocumented

Value
(ast.SetComp,
 ast.DictComp,
 ast.ListComp,
 ast.GeneratorExp,
 ast.Lambda,
 ast.FunctionDef,
 ast.AsyncFunctionDef,
...
_T = (source)

Undocumented

Value
TypeVar('_T',
        bound=object)
_AssingT = (source)

Undocumented

Value
ast.Assign | ast.AnnAssign
_ClassInfo = (source)

Undocumented

Value
type[Any] | tuple[type[Any], ...]
_deprecated: Collection[str] = (source)

Undocumented

_op_data = (source)

Undocumented

_precedence_data = (source)

Undocumented

_symbol_data = (source)

Undocumented