module documentation

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 ModuleVistor No class docstring; 0/3 instance variable, 5/33 methods, 0/3 static method, 0/1 class method documented
Class TypeAliasVisitorExt This visitor implements the handling of type aliases and type variables.
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
Class _AnnotationValueFormatter Special _ValueFormatter for function annotations.
Class _ValueFormatter Class to encapsulate a python value and translate it to HTML when calling repr() on the _ValueFormatter. Used for presenting default values of parameters.
Function _extract_annotation_subscript Extract the "str, bytes" part from annotations like "Union[str, bytes]".
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.
Variable _CONTROL_FLOW_BLOCKS AST types that introduces a new control flow block, potentially conditionnal.
Variable _parse Undocumented
def extract_final_subscript(annotation: ast.Subscript) -> ast.expr: (source)

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

Raises
ValueErrorIf 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) -> ast.Module: (source)

Parse the contents of a Python source file.

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 _extract_annotation_subscript(annotation: ast.Subscript) -> ast.AST: (source)

Extract the "str, bytes" part from annotations like "Union[str, bytes]".

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
boolTrue 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
boolTrue if the name does not exist or is an existing (possibly inherited) attribute, False if this name defines something else than an Attribute.
_CONTROL_FLOW_BLOCKS: tuple[type[ast.stmt], ...] = (source)

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

Undocumented