Package epydoc :: Module apidoc
[hide private]
[frames] | no frames]

Module apidoc

source code

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
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')