pydoctor.model.System

class documentation

class System: (source)

Constructor: System(options)

View In Hierarchy

A collection of related documentable objects.

PyDoctor documents collections of objects, often the contents of a package.

Method __init__ Undocumented
Method addModuleFromPath Undocumented
Method addObject Add object to the system.
Method addPackage Undocumented
Method analyzeModule Undocumented
Method fetchIntersphinxInventories Download and parse intersphinx inventories based on configuration.
Method find_object Look up an object using a potentially outdated full name.
Method getProcessedModule Undocumented
Method handleDuplicate This is called when we see two objects with the same .fullName(), for example:
Method introspectModule Undocumented
Method membersOrder Returns a callable suitable to be used with sorted function. Used to sort the given object's members for presentation.
Method msg Log a message. pydoctor's logging system is bit messy.
Method objectsOfType Iterate over all instances of cls present in the system.
Method objForFullName Undocumented
Method postProcess Called when there are no more unprocessed modules.
Method privacyClass Undocumented
Method process Undocumented
Method processModule Undocumented
Method progress Undocumented
Method setSourceHref Undocumented
Class Variable custom_extensions Additional list of extensions to load alongside default extensions.
Class Variable defaultBuilder Undocumented
Class Variable show_attr_value What kind of attributes we should display the value for?
Class Variable systemBuilder Undocumented
Instance Variable allobjects Undocumented
Instance Variable buildtime Undocumented
Instance Variable extensions List of extensions.
Instance Variable intersphinx Undocumented
Instance Variable module_count Undocumented
Instance Variable needsnl Undocumented
Instance Variable once_msgs Undocumented
Instance Variable options Undocumented
Instance Variable parse_errors Dict from the name of the thing we're rendering (section) to the FullNames of objects for which the rendereable elements failed to parse. Typically the renderable element is the docstring, but it can be the decorators, parameter default values or any other colorized AST.
Instance Variable processing_modules Undocumented
Instance Variable projectname Undocumented
Instance Variable rootobjects Undocumented
Instance Variable unprocessed_modules Undocumented
Instance Variable verboselevel Undocumented
Instance Variable violations The number of docstring problems found. This is used to determine whether to fail the build when using the --warnings-as-errors option, so it should only be increased for problems that the user can fix.
Property Attribute Undocumented
Property Class Undocumented
Property Function Undocumented
Property Module Undocumented
Property Package Undocumented
Property root_names The top-level package/module names in this system.
Property sourcebase Undocumented
Method _addUnprocessedModule First add the new module into the unprocessed_modules list. Handle eventual duplication of module names, and finally add the module to the system.
Method _handleDuplicateModule This is called when two modules have the same name.
Method _introspectThing Undocumented
Method _remove Undocumented
Instance Variable _astbuilder_visitors Undocumented
Instance Variable _factory Undocumented
Instance Variable _post_processor Undocumented
Instance Variable _privacyClassCache Undocumented
def __init__(self, options: Options | None = None): (source)

Undocumented

def addModuleFromPath(self, path: Path, package: _PackageT | None): (source)

Undocumented

def addObject(self, obj: Documentable): (source)

Add object to the system.

def addPackage(self, package_path: Path, parentPackage: _PackageT | None = None): (source)

Undocumented

@overload
def analyzeModule(self, modpath: Path, modname: str, parentPackage: _PackageT | None, is_package: Literal[False] = False) -> _ModuleT:
@overload
def analyzeModule(self, modpath: Path, modname: str, parentPackage: _PackageT | None, is_package: Literal[True]) -> _PackageT:
(source)

Undocumented

def fetchIntersphinxInventories(self, cache: CacheT): (source)

Download and parse intersphinx inventories based on configuration.

def find_object(self, full_name: str) -> Documentable | None: (source)

Look up an object using a potentially outdated full name.

A name can become outdated if the object is reparented: objForFullName() will only be able to find it under its new name, but we might still have references to the old name.

Parameters
full_name:strThe fully qualified name of the object.
Returns
Documentable | NoneThe object, or None if the name is external (it does not match any of the roots of this system).
Raises
LookupErrorIf the object is not found, while its name does match one of the roots of this system.
def getProcessedModule(self, modname: str) -> _ModuleT | None: (source)

Undocumented

def handleDuplicate(self, obj: Documentable): (source)

This is called when we see two objects with the same .fullName(), for example:

    class C:
        if something:
            def meth(self):
                implementation 1
        else:
            def meth(self):
                implementation 2

The default is that the second definition "wins".

def introspectModule(self, path: Path, module_name: str, package: _PackageT | None) -> _ModuleT: (source)

Undocumented

def membersOrder(self, ob: Documentable) -> Callable[[Documentable], tuple[Any, ...]]: (source)

Returns a callable suitable to be used with sorted function. Used to sort the given object's members for presentation.

Users can customize class and module members order independently, or can override this method with a custom system class for further tweaks.

def msg(self, section: str, msg: str, thresh: int = 0, topthresh: int = 100, nonl: bool = False, wantsnl: bool = True, once: bool = False): (source)

Log a message. pydoctor's logging system is bit messy.

Parameters
section:strAPI doc generation step this message belongs to.
msg:strThe message.
thresh:intThe minimum verbosity level of the system for this message to actually be printed. Meaning passing thresh=-1 will make message still display if -q is passed but not if -qq. Similarly, passing thresh=1 will make the message only apprear if the verbosity level is at least increased once with -v. Using negative thresh will count this message as a violation and will fail the build if option -W is passed.
topthresh:intThe maximum verbosity level of the system for this message to actually be printed.
nonl:boolUndocumented
wantsnl:boolUndocumented
once:boolUndocumented
def objectsOfType(self, cls: type[DocumentableT] | str) -> Iterator[DocumentableT]: (source)

Iterate over all instances of cls present in the system.

def objForFullName(self, fullName: str) -> Documentable | None: (source)

Undocumented

def postProcess(self): (source)

Called when there are no more unprocessed modules.

Analysis of relations between documentables can be done here, without the risk of drawing incorrect conclusions because modules were not fully processed yet.

See Also
extensions.PriorityProcessor.
def privacyClass(self, ob: Documentable) -> PrivacyClass: (source)

Undocumented

def process(self): (source)

Undocumented

def processModule(self, mod: _ModuleT): (source)

Undocumented

def progress(self, section: str, i: int, n: int | None, msg: str): (source)

Undocumented

def setSourceHref(self, mod: _ModuleT, source_path: Path): (source)

Undocumented

custom_extensions: list[str] = (source)

Additional list of extensions to load alongside default extensions.

defaultBuilder: type[ASTBuilder] = (source)

Undocumented

show_attr_value = (source)

What kind of attributes we should display the value for?

systemBuilder: type[ISystemBuilder] = (source)

Undocumented

allobjects: dict[str, Documentable] = (source)

Undocumented

buildtime = (source)

Undocumented

extensions: list[str] = (source)

List of extensions.

By default, all built-in pydoctor extensions will be loaded. Override this value to cherry-pick extensions.

intersphinx = (source)

Undocumented

module_count: int = (source)

Undocumented

needsnl: bool = (source)

Undocumented

once_msgs: set[tuple[str, str]] = (source)

Undocumented

options: Options = (source)

Undocumented

parse_errors: dict[str, set[str]] = (source)

Dict from the name of the thing we're rendering (section) to the FullNames of objects for which the rendereable elements failed to parse. Typically the renderable element is the docstring, but it can be the decorators, parameter default values or any other colorized AST.

processing_modules: list[str] = (source)

Undocumented

projectname: str = (source)

Undocumented

rootobjects: list[_ModuleT] = (source)

Undocumented

unprocessed_modules: list[_ModuleT] = (source)

Undocumented

verboselevel: int = (source)

Undocumented

violations: int = (source)

The number of docstring problems found. This is used to determine whether to fail the build when using the --warnings-as-errors option, so it should only be increased for problems that the user can fix.

@property
Attribute: type[Attribute] = (source)

Undocumented

@property
Class: type[Class] = (source)

Undocumented

@property
Function: type[Function] = (source)

Undocumented

@property
Module: type[Module] = (source)

Undocumented

@property
Package: type[Package] = (source)

Undocumented

@property
root_names: Collection[str] = (source)

The top-level package/module names in this system.

@property
sourcebase: str | None = (source)

Undocumented

def _addUnprocessedModule(self, mod: _ModuleT): (source)

First add the new module into the unprocessed_modules list. Handle eventual duplication of module names, and finally add the module to the system.

def _handleDuplicateModule(self, first: _ModuleT, dup: _ModuleT): (source)

This is called when two modules have the same name.

Current rules are the following:

  • C-modules wins over regular python modules
  • Packages wins over modules
  • Else, the last added module wins
def _introspectThing(self, thing: object, parent: CanContainImportsDocumentable, parentMod: _ModuleT): (source)

Undocumented

def _remove(self, o: Documentable): (source)

Undocumented

_astbuilder_visitors: list[type[astutils.NodeVisitorExt]] = (source)

Undocumented

_factory = (source)

Undocumented

_post_processor = (source)

Undocumented

_privacyClassCache: dict[str, PrivacyClass] = (source)

Undocumented