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

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 `ValueDoc`s that can be reached, directly or indirectly from the given root list of `ValueDoc`s. | source code call graph

Call Graph

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

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

Call Graph

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

Parameters:
  - `filters` - A set of filters that can be used to prevent `reachable_valdocs` from following specific link types when looking for `ValueDoc`s 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')