pydocspec.astbuilder.Builder

class documentation

class Builder: (source)

Coordinate the process of parsing and analysing the ast trees.

Note
The approach is to proceed incrementally, and outside-in. First, you add the top-level directory structure, this computes the whole package/module structure. Then, each modules are parse, it creates all object instances, then it does some analysis on what we’ve found in post-processing.

Method	`add_module`	Add a module or package from a system path. If the path is pointing to a directory, reccursively add all submodules.
Method	`add_module_string`	Add a module to the builder from a simple string.
Method	`build_modules`	Drives the building, builds modules until there is no unprocessed modules anymore.
Method	`get_processed_module`	Returns the processed or processing (in case of cylces) module or None if the name cannot be found.
Instance Variable	`astroid_transforms`	Astroid inference system tweaks.
Instance Variable	`options`	Options
Instance Variable	`pprocessor`	Post processor.
Instance Variable	`processing_map`	Mapping from module's full_name to the processing state
Instance Variable	`root`	Tree root.
Instance Variable	`visitor_extensions`	AST build visitor extensions.
Property	`introspect_c_modules`	Optionally instrospect C modules enabled?
Property	`unprocessed_modules`	Undocumented
Method	`_add_module`	Create a new empty module and add it to the tree. Initiate it's state in the AST processing map.
Method	`_add_package`	Handles '__init__.py' files and reccursively calls itself when traversing subdirectories.
Method	`_discard_duplicate_mod`	Runs before adding a new module to the root. Check if a module already has the same name.
Method	`_maybe_add_module`	Ignores the files that are not recognized as python files.
Method	`_post_build`	Undocumented
Method	`_process_module`	Parse the module file to an AST and create it's members. At the time this method is called, not all objects are created. But all module instances already exist and are added to `root.all_objects`, including nested modules.
Method	`_process_module_ast`	Undocumented
Instance Variable	`_added_paths`	Undocumented
Instance Variable	`_processing_mod_stack`	Undocumented

def add_module(self, path): (source)

Add a module or package from a system path. If the path is pointing to a directory, reccursively add all submodules.

Parameters
path:`Path`	Undocumented

def add_module_string(self, text, modname, parent_name=None, path='<fromtext>', is_package=False): (source)

Add a module to the builder from a simple string.

Parameters
text:`str`	The module string
modname:`str`	The module short name
parent_name:`Optional[str]`	The fully qualified name of the parent package of this module. The package should be added to the builder first.
path:`str`	Undocumented
is_package:`bool`	Whether this module is a package.

def build_modules(self): (source)

Drives the building, builds modules until there is no unprocessed modules anymore.

Runs post-build operations after.

Note
This method should only be run once per Builder instance.

def get_processed_module(self, modname, raise_on_cycles=False): (source)

Returns the processed or processing (in case of cylces) module or None if the name cannot be found.

Parameters
modname:`str`	Undocumented
raise_on_cycles:`bool`	Undocumented
Returns
`Optional[_model.Module]`	Undocumented

astroid_transforms: List[ext._AstroidTransform] = (source)

Astroid inference system tweaks.

options: pydocspec.Options = (source)

Options

pprocessor: processor.Processor = (source)

Post processor.

processing_map: Dict[str, ProcessingState] = (source)

Mapping from module's full_name to the processing state

root: pydocspec.TreeRoot = (source)

Tree root.

visitor_extensions: Set[Union[ext.AstVisitorExt, Type[ext.AstVisitorExt]]] = (source)

AST build visitor extensions.

@property
introspect_c_modules: bool = (source)

Optionally instrospect C modules enabled?

@property
unprocessed_modules: Iterator[_model.Module] = (source)

Undocumented

def _add_module(self, path, modname, parent, is_package=False, is_c_module=False, py_mod=None, py_string=None): (source)

Create a new empty module and add it to the tree. Initiate it's state in the AST processing map.

Parameters
path:`Union[Path, str]`	path where we can find the module file(s).
modname:`str`	the name of the new module (local name, not qname).
parent:`Optional[_model.Module]`	the parent package, if any.
is_package:`bool`	whether this module is a package.
is_c_module:`bool`	whether this module is c extension.
py_mod:`Optional[types.ModuleType]`	the live module, usually `None` because it parses the source code file instead.
py_string:`Optional[str]`	the module's string, usually `None` because it directly gets the AST from the file path. This is used when calling add_module_string().
Returns
`_model.Module`	Undocumented

def _add_package(self, path, parent=None): (source)

Handles '__init__.py' files and reccursively calls itself when traversing subdirectories.

Parameters
path:`Path`	Undocumented
parent:`Optional[_model.Module]`	Undocumented

def _discard_duplicate_mod(self, mod, mod_full_name): (source)

Runs before adding a new module to the root. Check if a module already has the same name.

Parameters
mod:`_model.Module`	Undocumented
mod_full_name:`str`	Undocumented
Returns
`Optional[_model.Module]`	The older module (already present) if the new module has been discarded. This should stop the new module from beeing added, it's a duplicate module.
Note
The rule is that the package/directory wins over the regular module, also, c-modules wins over regular modules.

def _maybe_add_module(self, path, parent=None): (source)

Ignores the files that are not recognized as python files.

Parameters
path:`Path`	Undocumented
parent:`Optional[_model.Module]`	Undocumented

def _post_build(self): (source)

Undocumented

def _process_module(self, mod): (source)

Parse the module file to an AST and create it's members. At the time this method is called, not all objects are created. But all module instances already exist and are added to root.all_objects, including nested modules.

Parameters
mod:`_model.Module`	Undocumented

def _process_module_ast(self, mod_ast, mod): (source)

Undocumented

Parameters
mod_ast:`astroid.nodes.Module`	Undocumented
mod:`_model.Module`	Undocumented

_added_paths: Set[Path] = (source)

Undocumented

_processing_mod_stack: List[_model.Module] = (source)

Undocumented