pydocspec.ApiObject

class documentation

class ApiObject(_model.ApiObject): (source)

Known subclasses: pydocspec.Class, pydocspec.Function, pydocspec.Indirection, pydocspec.Module, pydocspec.Variable

View In Hierarchy

An augmented docspec.ApiObject, with functionalities to resolve names for the python language.

Method	`expand_name`	Return a fully qualified name for the possibly-dotted `name`.
Method	`resolve_name`	Return the object named by "name" (using Python's lookup rules) in this context.
Class Variable	`docstring`	The documentation string of the API object.
Class Variable	`location`	The location of the API object, i.e. where it is sourced from/defined in the code.
Class Variable	`module`	Undocumented
Class Variable	`parent`	The parent of the API object.
Class Variable	`root`	`TreeRoot` instance holding references to all objects in the tree.
Instance Variable	`aliases`	Aliases to this object.
Instance Variable	`doc_sources`	Objects that can be considered as a source of documentation.
Method	`_init_attribs`	A method to define extra attributes that will be set after initialization.
Method	`_local_to_full_name`	Undocumented
Method	`_resolve_indirection`	Follow an indirection and return the supposed full name of the origin object.

Inherited from ApiObject:

Method	`__repr__`	Undocumented
Method	`__str__`	Undocumented
Method	`add_siblings`	A new nodes to the tree, siblings to this node.
Method	`get_member`	Retrieve a member from the API object. This will always return `None` for objects that don't support members (eg. `Function` and `Variable`).
Method	`get_members`	Like `get_member` but can return several items with the same name.
Method	`remove`	Undocumented
Method	`replace`	Replace this object by one or more objects.
Method	`walk`	Traverse a tree of objects, calling the `genericvisitor.Visitor.visit` method of `visitor` when entering each node.
Method	`walkabout`	Perform a tree traversal similarly to `walk()`, except also call the `genericvisitor.Visitor.depart` method before exiting each node.
Property	`dotted_name`	The fully qualified dotted name of this object, as `DottedName` instance.
Property	`full_name`	The fully qualified dotted name of this object, as string. This value is used as the key in the `ApiObject.root.all_objects` dictionnary.
Property	`scope`	Undocumented
Method	`_members`	Undocumented
Method	`_remove_self`	Undocumented
Method	`_repr`	Undocumented
Class Variable	`_spec_fields`	Undocumented

Inherited from ApiObject (via ApiObject):

Method	`__init__`	Undocumented
Method	`sync_hierarchy`	Synchronize the hierarchy of this API object and all of it's children. This should be called when the #HasMembers.members are updated to ensure that all child objects reference the right #parent. Loaders are expected to return #ApiObject#s in a fully synchronized state such that the user does not have to call this method unless they are doing modifications to the tree.
Instance Variable	`name`	The name of the entity. This is usually relative to the respective parent of the entity, as opposed to it's fully qualified name/absolute name. However, that is more of a recommendation than rule. For example the #docspec_python loader by default returns #Module objects with their full module name (and does not create a module hierarchy).
Property	`path`	Returns a list of all of this API object's parents, from top to bottom. The list includes self as the last item.

Inherited from CanTriggerWarnings (via ApiObject):

Method warn Undocumented

Inherited from GetMembersMixin (via ApiObject):

Method __getitem__ Undocumented

def expand_name(self, name, follow_aliases=True, _indirections=None): (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, expand_name("RenamedExternal") should be "external_location.External" and expand_name("renamed_mod.Local") should be "mod1.Local".

This method is in charge to follow the aliases when possible! It will reccursively follow any alias entries found up to certain level of complexity. Example: mod1.py:

import external
class Processor:
    spec = external.Processor.more_spec
P = Processor

mod2.py:

from mod1 import P
class Runner:
    processor = P

In the context of mod2, expand_name("Runner.processor.spec") should be "external.Processor.more_spec".

Parameters
name:`str`	The name to expand.
follow_aliases:`bool`	Whether or not to follow aliases. Indirections will still be followed anyway.
_indirections:`Any`	Undocumented
Returns
`str`	Undocumented
Notes
The implementation replies on iterating through the each part of the dotted name, calling `_local_to_full_name` for each name in their associated context and incrementally building the full_name from that. Lookup members in superclasses when possible and follows aliases and indirections. This mean that `expand_name` will never return the name of an alias, it will always follow it's indirection to the origin. Except if `follow_aliases=False`.
Supports relative dotted name like `.foo.bar`.

def resolve_name(self, name, follow_aliases=True): (source)

Return the object named by "name" (using Python's lookup rules) in this context.

Parameters
name:`str`	Undocumented
follow_aliases:`bool`	Undocumented
Returns
`Optional[ApiObject]`	Undocumented
Note
This method will never return an `Indirection` or an alias since it's supposed to follow indirections and aliases. Except if `follow_aliases=False`.

docstring: Optional[Docstring] = (source)

overrides pydocspec._docspec.ApiObject.docstring

The documentation string of the API object.

location: Location = (source)

overrides pydocspec._docspec.ApiObject.location

The location of the API object, i.e. where it is sourced from/defined in the code.

module: Module = (source)

overrides pydocspec._model.ApiObject.module

Undocumented

parent: Optional[Union[Class, Module]] = (source)

overrides pydocspec._model.ApiObject.parent

overridden in pydocspec.Class, pydocspec.Function, pydocspec.Indirection, pydocspec.Module, pydocspec.Variable

The parent of the API object.

root: TreeRoot = (source)

overrides pydocspec._model.ApiObject.root

TreeRoot instance holding references to all objects in the tree.

aliases: List[Variable] = (source)

Aliases to this object.

doc_sources: List[ApiObject] = (source)

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 _init_attribs(self): (source)

overrides pydocspec._model.ApiObject._init_attribs

overridden in pydocspec.Class, pydocspec.Function, pydocspec.Module, pydocspec.Variable

A method to define extra attributes that will be set after initialization.

Note
Most attributes don't need a special value at initialization (if they use None as default for instance), in those cases, avoid overriding this method by declaring them as class variable. Override this method only if you have to initialize an attribute value to a mutable object.

def _local_to_full_name(self, name, follow_aliases, _indirections=None): (source)

Undocumented

Parameters
name:`str`	Undocumented
follow_aliases:`bool`	Undocumented
_indirections:`Any`	Undocumented
Returns
`str`	Undocumented

def _resolve_indirection(self, indirection, _indirections=None): (source)

Follow an indirection and return the supposed full name of the origin object.

Resolve the alias value to it's target full name. Or fall back to original alias target if we know we've exhausted the max recursions.

Parameters
indirection:`Indirection`	an `Indirection` object.
_indirections:`Optional[List[Indirection]]`	Undocumented
indirections	Chain of alias objects followed. This variable is used to prevent infinite loops when doing the lookup.
Returns
`Optional[str]`	Undocumented
Note
It can return None in exceptionnal cases if an indirection cannot be resolved. Then we use the indirection's full_name.