pydoctor.model.Documentable

class documentation

class Documentable: (source)

Known subclasses: pydoctor.model.CanContainImportsDocumentable, pydoctor.model.Inheritable

Constructor: Documentable(system, name, parent, source_path)

An object that can be documented.

The interface is a bit ridiculously wide.

Method	`__init__`	Undocumented
Method	`__repr__`	Undocumented
Method	`docsources`	Objects that can be considered as a source of documentation.
Method	`expandName`	Return a fully qualified name for the possibly-dotted `name`.
Method	`fullName`	Undocumented
Method	`isNameDefined`	Is the given name defined in the globals/locals of self-context? Only the first name of a dotted name is checked.
Method	`reparent`	Undocumented
Method	`report`	Log an error or warning about this documentable object.
Method	`resolveName`	Return the object named by "name" (using Python's lookup rules) in this context, if any is known to pydoctor.
Method	`setDocstring`	Undocumented
Method	`setLineNumber`	Save the linenumber of this object.
Method	`setup`	Undocumented
Class Variable	`kind`	Page location where we are documented.
Class Variable	`parsed_docstring`	Undocumented
Class Variable	`parsed_summary`	Undocumented
Class Variable	`parsed_type`	Undocumented
Instance Variable	`contents`	Undocumented
Instance Variable	`docstring`	The object's docstring. But also see docsources.
Instance Variable	`docstring_lineno`	Undocumented
Instance Variable	`extra_info`	A list to store extra informations about this documentable, as `ParsedDocstring`.
Instance Variable	`linenumber`	Undocumented
Instance Variable	`name`	Undocumented
Instance Variable	`parent`	Undocumented
Instance Variable	`parentMod`	Undocumented
Instance Variable	`source_path`	Undocumented
Instance Variable	`sourceHref`	Undocumented
Instance Variable	`system`	The system the object is part of.
Property	`description`	A string describing our source location to the user.
Property	`docstring_linker`	Returns an instance of `DocstringLinker` suitable for resolving names in the context of the object.
Property	`doctarget`	Undocumented
Property	`isPrivate`	Is this object considered private API?
Property	`isVisible`	Is this object so private as to be not shown at all?
Property	`module`	This object's `Module`.
Property	`page_object`	The documentable to which the page we're documented on belongs. For example methods are documented on the page of their class, functions are documented in their module's page etc.
Property	`privacyClass`	How visible this object should be.
Property	`url`	Relative URL at which the documentation for this Documentable can be found.
Method	`_handle_reparenting_post`	Undocumented
Method	`_handle_reparenting_pre`	Undocumented
Method	`_localNameToFullName`	Undocumented
Instance Variable	`_linker`	Undocumented

def __init__(self, system: System, name: str, parent: Optional[Documentable] = None, source_path: Optional[Path] = None): (source) ¶

Undocumented

def __repr__(self) -> str: (source) ¶

Undocumented

def docsources(self) -> Iterator[Documentable]: (source) ¶

overridden in pydoctor.model.Inheritable

Objects that can be considered as a source of documentation.

The motivating example for having multiple sources is looking at a superclass' implementation of a method for documentation for a subclass'.

def expandName(self, name: str) -> str: (source) ¶

Return a fully qualified name for the possibly-dotted `name`.

To explain what this means, consider the following modules:

mod1.py:

    from external_location import External
    class Local:
        pass

mod2.py:

    from mod1 import External as RenamedExternal
    import mod1 as renamed_mod
    class E:
        pass

In the context of mod2.E, expandName("RenamedExternal") should be "external_location.External" and expandName("renamed_mod.Local") should be "mod1.Local".

def fullName(self) -> str: (source) ¶

Undocumented

def isNameDefined(self, name: str) -> bool: (source) ¶

overridden in pydoctor.model.CanContainImportsDocumentable, pydoctor.model.Inheritable

Is the given name defined in the globals/locals of self-context? Only the first name of a dotted name is checked.

Returns True iff the given name can be loaded without raising `NameError`.

def reparent(self, new_parent: Module, new_name: str): (source) ¶

Undocumented

def report(self, descr: str, section: str = 'parsing', lineno_offset: int = 0, thresh: int = -1): (source) ¶

Log an error or warning about this documentable object.

Parameters
descr:`str`	The error/warning string
section:`str`	What the warning is about.
lineno_offset:`int`	Offset
thresh:`int`	Thresh to pass to `System.msg`, it will use `-1` by default, meaning it will count as a violation and will fail the build if option `-W` is passed. But this behaviour is not applicable if `thresh` is greater or equal to zero.

def resolveName(self, name: str) -> Optional[Documentable]: (source) ¶

Return the object named by "name" (using Python's lookup rules) in this context, if any is known to pydoctor.

def setDocstring(self, node: astutils.Str): (source) ¶

Undocumented

def setLineNumber(self, lineno: LineFromDocstringField|LineFromAst|int): (source) ¶

Save the linenumber of this object.

If the linenumber is already set from a ast analysis, this is an no-op. If the linenumber is already set from docstring fields and the new linenumber if not from docstring fields as well, the old docstring based linumber will be replaced with the one from ast analysis since this takes precedence.

Parameters
lineno:`LineFromDocstringField\|LineFromAst\|int`	The linenumber. If the given linenumber is simply an `int` we'll assume it's coming from the ast builder and it will be converted to an `LineFromAst` instance.

def setup(self): (source) ¶

overridden in pydoctor.model.CanContainImportsDocumentable, pydoctor.model.Function

Undocumented

kind: Optional[DocumentableKind] = (source) ¶

overridden in pydoctor.model.Function

Page location where we are documented.

parsed_docstring: Optional[ParsedDocstring] = (source) ¶

Undocumented

parsed_summary: Optional[ParsedDocstring] = (source) ¶

Undocumented

parsed_type: Optional[ParsedDocstring] = (source) ¶

Undocumented

contents: Dict[str, Documentable] = (source) ¶

Undocumented

docstring: Optional[str] = (source) ¶

The object's docstring. But also see docsources.

docstring_lineno = (source) ¶

Undocumented

extra_info: List[ParsedDocstring] = (source) ¶

A list to store extra informations about this documentable, as ParsedDocstring.

linenumber: LineFromAst|LineFromDocstringField|Literal[0] = (source) ¶

Undocumented

name = (source) ¶

Undocumented

parent = (source) ¶

overridden in pydoctor.model.Class, pydoctor.model.Inheritable

Undocumented

parentMod: Optional[Module] = (source) ¶

Undocumented

source_path: Optional[Path] = (source) ¶

Undocumented

sourceHref: Optional[str] = (source) ¶

Undocumented

system = (source) ¶

The system the object is part of.

@property
description: str = (source) ¶

A string describing our source location to the user.

If this module's code was read from a file, this returns its file path. In other cases, such as during unit testing, the full module name is returned.

@property
docstring_linker: linker.DocstringLinker = (source) ¶

Returns an instance of DocstringLinker suitable for resolving names in the context of the object.

@property
doctarget: Documentable = (source) ¶

Undocumented

@property
isPrivate: bool = (source) ¶

Is this object considered private API?

This is just a simple helper which defers to self.privacyClass.

@property
isVisible: bool = (source) ¶

Is this object so private as to be not shown at all?

This is just a simple helper which defers to self.privacyClass.

@property
module: Module = (source) ¶

overridden in pydoctor.model.Module

This object's Module.

For modules, this returns the object itself, otherwise the module containing the object is returned.

@property
page_object: Documentable = (source) ¶

The documentable to which the page we're documented on belongs. For example methods are documented on the page of their class, functions are documented in their module's page etc.

@property
privacyClass: PrivacyClass = (source) ¶

overridden in pydoctor.model.Module

How visible this object should be.

@property
url: str = (source) ¶

Relative URL at which the documentation for this Documentable can be found.

For page objects this method MUST return an .html filename without a URI fragment (because pydoctor.templatewriter.writer.TemplateWriter uses it directly to determine the output filename).

def _handle_reparenting_post(self): (source) ¶

Undocumented

def _handle_reparenting_pre(self): (source) ¶

Undocumented

def _localNameToFullName(self, name: str) -> str: (source) ¶

overridden in pydoctor.model.Class, pydoctor.model.Inheritable, pydoctor.model.Module

Undocumented

_linker: Optional[linker.DocstringLinker] = (source) ¶

Undocumented