pydoctor.astbuilder

module documentation

(source)

Convert ASTs into pydoctor.model.Documentable instances.

Class	`ASTBuilder`	Keeps tracks of the state of the AST build, creates documentable and adds objects to the system.
Class	`AstParseError`	Parse errors are cached as instances of this class instead of bare exceptions in order to avoid cycles with the locals.
Class	`ModuleVistor`	No class docstring; 0/4 instance variable, 12/42 methods, 0/3 static method, 0/1 class method documented
Class	`SyntaxTreeParser`	Responsible to read files and cache their parsed tree.
Class	`TypeAliasVisitorExt`	This visitor implements the handling of type aliases and type variables.
Exception	`IgnoreAssignment`	A control flow exception meaning that the assignment should not be further proccessed.
Function	`extract_final_subscript`	Extract the "str" part from annotations like "Final[str]".
Function	`findModuleLevelAssign`	Find module level Assign. Yields tuples containing the assigment name and the Assign node.
Function	`is_attribute_overridden`	Detect if the optional `new_value` expression override the one already stored in the `Attribute.value` attribute.
Function	`is_constant`	Detect if the given assignment is a constant.
Function	`parseAll`	Find and attempt to parse into a list of names the `__all__` variable of a module's AST and set `Module.all` accordingly.
Function	`parseDocformat`	Find `__docformat__` variable of this module's AST and set `Module.docformat` accordingly.
Function	`parseFile`	Parse the contents of a Python source file.
Function	`setup_pydoctor_extension`	Undocumented
Constant	`MODULE_VARIABLES_META_PARSERS`	Undocumented
Type Variable	`DocumentableT`	Undocumented
Function	`_handleAliasing`	If the given expression is a name assigned to a target that is not yet in use, create an alias.
Function	`_maybeAttribute`	Check whether a name is a potential attribute of the given class. This is used to prevent an assignment that wraps a method from creating an attribute that would overwrite or shadow that method.
Function	`_parse`	Wraps `ast.parse`.
Variable	`_CONTROL_FLOW_BLOCKS`	AST types that introduces a new control flow block, potentially conditionnal.

def extract_final_subscript(annotation: ast.Subscript) -> ast.expr: (source) ¶

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

Raises
`ValueError`	If the "Final" annotation is not valid.

def findModuleLevelAssign(mod_ast: ast.Module) -> Iterator[tuple[str, ast.Assign]]: (source) ¶

Find module level Assign. Yields tuples containing the assigment name and the Assign node.

def is_attribute_overridden(obj: model.Attribute, new_value: ast.expr | None) -> bool: (source) ¶

Detect if the optional new_value expression override the one already stored in the Attribute.value attribute.

def is_constant(obj: model.Attribute, annotation: ast.expr | None, value: ast.expr | None) -> bool: (source) ¶

Detect if the given assignment is a constant.

For an assignment to be detected as constant, it should:

have all-caps variable name or using typing.Final annotation
not be overriden
not be defined in a conditionnal block or any other kind of control flow blocks

Note
Must be called after setting obj.annotation to detect variables using Final.

def parseAll(node: ast.Assign, mod: model.Module): (source) ¶

Find and attempt to parse into a list of names the __all__ variable of a module's AST and set Module.all accordingly.

def parseDocformat(node: ast.Assign, mod: model.Module): (source) ¶

Find __docformat__ variable of this module's AST and set Module.docformat accordingly.

This is all valid:

    __docformat__ = "reStructuredText en"
    __docformat__ = "epytext"
    __docformat__ = "restructuredtext"

def parseFile(path: Path) -> model.ParsedAstModule: (source) ¶

Parse the contents of a Python source file.

Returns
`model.ParsedAstModule`	The parsed ast module

Raises
`SyntaxError`	If any exception is raised by `ast.parse`

def setup_pydoctor_extension(r: extensions.ExtRegistrar): (source) ¶

Undocumented

MODULE_VARIABLES_META_PARSERS: Mapping[str, Callable[[ast.Assign, model.Module], None]] = (source) ¶

Undocumented

Value

{'__all__': parseAll, '__docformat__': parseDocformat}

DocumentableT = (source) ¶

Undocumented

Value

TypeVar('DocumentableT',
        bound=model.Documentable)

def _handleAliasing(ctx: model.CanContainImportsDocumentable, target: str, expr: ast.expr | None) -> bool: (source) ¶

If the given expression is a name assigned to a target that is not yet in use, create an alias.

Returns
`bool`	`True` iff an alias was created.

def _maybeAttribute(cls: model.Class, name: str) -> bool: (source) ¶

Check whether a name is a potential attribute of the given class. This is used to prevent an assignment that wraps a method from creating an attribute that would overwrite or shadow that method.

Returns
`bool`	`True` if the name does not exist or is an existing (possibly inherited) attribute, `False` if this name defines something else than an `Attribute`.

def _parse(source: str, *, filename: str = '<unknown>') -> ast.Module: (source) ¶

Wraps ast.parse.

Raises
`SyntaxError`	If any exception is raised by `ast.parse`

_CONTROL_FLOW_BLOCKS: tuple[type[ast.stmt], ...] = (source) ¶

AST types that introduces a new control flow block, potentially conditionnal.