Package epydoc :: Module apidoc

Module apidoc

Classes for encoding API documentation about Python programs. These classes are used as a common representation for combining information derived from introspection and from parsing.

The API documentation for a Python program is encoded using a graph of APIDoc objects, each of which encodes information about a single Python variable or value. APIDoc has two direct subclasses: VariableDoc, for documenting variables; and ValueDoc, for documenting values. The ValueDoc class is subclassed further, to define the different pieces of information that should be recorded about each value type:

Class Hierarchy for APIDoc

The distinction between variables and values is intentionally made explicit. This allows us to distinguish information about a variable itself (such as whether it should be considered 'public' in its containing namespace) from information about the value it contains (such as what type the value has). This distinction is also important because several variables can contain the same value: each variable should be described by a separate VariableDoc; but we only need one ValueDoc, since they share a single value.

To Do: Add a cache to canonical name lookup?

Classes

[hide private]

DottedName
A sequence of identifiers, separated by periods, used to name a Python variable, value, or argument.

_Sentinel
A unique value that won't compare equal to any other value.

APIDoc
API documentation information for a single element of a Python program.

VariableDoc
API documentation information about a single Python variable.

ValueDoc
API documentation information about a single Python value.

GenericValueDoc
API documentation about a 'generic' value, i.e., one that does not have its own docstring or any information other than its value and parse representation.

NamespaceDoc
API documentation information about a singe Python namespace value.

ModuleDoc
API documentation information about a single module.

ClassDoc
API documentation information about a single class.

RoutineDoc
API documentation information about a single routine.

ClassMethodDoc

StaticMethodDoc

PropertyDoc
API documentation information about a single property.

DocIndex
[xx] out of date.

Functions

[hide private]

reachable_valdocs(root, **filters)
Return a list of all ValueDocs that can be reached, directly or indirectly from the given root list of ValueDocs. source code
call graph

_flatten(lst, out=None)
Return a flattened version of lst. source code
call graph

pp_apidoc(api_doc, doublespace=0, depth=5, exclude=(), include=(), backpointers=None)
Returns: A multiline pretty-printed string representation for the given APIDoc. source code

_pp_list(api_doc, items, doublespace, depth, exclude, include, backpointers, is_last)

source code

_pp_dict(api_doc, dict, doublespace, depth, exclude, include, backpointers, is_last)

source code

_pp_apidoc(api_doc, val, doublespace, depth, exclude, include, backpointers, is_last)

source code

_pp_val(api_doc, val, doublespace, depth, exclude, include, backpointers)

source code

Variables

[hide private]

UNKNOWN = _Sentinel('UNKNOWN')
A special value used to indicate that a given piece of information about an object is unknown.

Function Details

[hide private]

reachable_valdocs(root, **filters)

source code
call graph

Return a list of all ValueDocs that can be reached, directly or indirectly from the given root list of ValueDocs.

Parameters:

filters - A set of filters that can be used to prevent reachable_valdocs from following specific link types when looking for ValueDocs that can be reached from the root set. See APIDoc.apidoc_links for a more complete description.

pp_apidoc(api_doc, doublespace=0, depth=5, exclude=`()`, include=`()`, backpointers=None)

source code

Parameters:

doublespace - If true, then extra lines will be inserted to make the output more readable.
depth - The maximum depth that pp_apidoc will descend into descendent VarDocs. To put no limit on depth, use depth=-1.
exclude - A list of names of attributes whose values should not be shown.
backpointers - For internal use.

Returns:

A multiline pretty-printed string representation for the given APIDoc.

Variables Details

[hide private]

UNKNOWN

A special value used to indicate that a given piece of information about an object is unknown. This is used as the default value for all instance variables.

Value:

_Sentinel('UNKNOWN')

Module apidoc

reachable_valdocs(root, **filters)

pp_apidoc(api_doc, doublespace=0, depth=5, exclude=(), include=(), backpointers=None)

UNKNOWN

pp_apidoc(api_doc, doublespace=0, depth=5, exclude=`()`, include=`()`, backpointers=None)