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

type APIDoc

source code

Known Subclasses:

API documentation information for a single element of a Python program. APIDoc itself is an abstract base class; subclasses are used to specify what information should be recorded about each type of program element. In particular, APIDoc has two direct subclasses, VariableDoc for documenting variables and ValueDoc for documenting values; and the ValueDoc class is subclassed further for different value types.

Each APIDoc subclass specifies the set of attributes that should be used to record information about the corresponding program element type. The default value for each attribute is stored in the class; these default values can then be overridden with instance variables. Most attributes use the special value UNKNOWN as their default value, to indicate that the correct value for that attribute has not yet been determined. This makes it easier to merge two APIDoc objects that are documenting the same element (in particular, to merge information about an element that was derived from parsing with information that was derived from introspection).

For all attributes with boolean values, use only the constants True and False to designate true and false. In particular, do not use other values that evaluate as true or false, such as 2 or (). This restriction makes it easier to handle UNKNOWN values. For example, to test if a boolean attribute is True or UNKNOWN, use 'attrib in (True, UNKNOWN)' or 'attrib is not False'.

Two APIDoc objects describing the same object can be merged, using the method merge_and_overwrite(other). After two APIDocs are merged, any changes to one will be reflected in the other. This is accomplished by setting the two APIDoc objects to use a shared instance dictionary. See the documentation for merge_and_overwrite for more information, and some important caveats about hashing.

Instance Methods [hide private]
 
__init__(self, **kwargs)
Construct a new APIDoc object.
source code
call graph 
 
_debug_setattr(self, attr, val)
Modify an APIDoc's attribute.
source code
 
__setattr__(self, attr, val)
Modify an APIDoc's attribute.
source code
 
__repr__(self) source code
 
pp(self, doublespace=0, depth=5, exclude=(), include=())
Return a pretty-printed string representation for the information contained in this APIDoc.
source code
 
__str__(self, doublespace=0, depth=5, exclude=(), include=())
Return a pretty-printed string representation for the information contained in this APIDoc.
source code
 
specialize_to(self, cls)
Change self's class to cls.
source code
call graph 
 
__hash__(self) source code
call graph 
 
__cmp__(self, other) source code
call graph 
bool
is_detailed(self)
Does this object deserve a box with extra details?
source code
call graph 
 
merge_and_overwrite(self, other, ignore_hash_conflict=False)
Combine self and other into a merged object, such that any changes made to one will affect the other.
source code
call graph 
 
apidoc_links(self, **filters)
Return a list of all APIDocs that are directly linked from this APIDoc (i.e., are contained or pointed to by one or more of this APIDoc's attributes.)
source code
Class Variables [hide private]
  __has_been_hashed = False
True iff self.__hash__() has ever been called.
  __mergeset = None
The set of all APIDoc objects that have been merged with this APIDoc (using merge_and_overwrite()).
Instance Variables [hide private]
    Docstrings
string or None docstring = _Sentinel('UNKNOWN')
The documented item's docstring.
int docstring_lineno = _Sentinel('UNKNOWN')
The line number on which the documented item's docstring begins.
    Information Extracted from Docstrings
ParsedDocstring descr = _Sentinel('UNKNOWN')
A description of the documented item, extracted from its docstring.
ParsedDocstring summary = _Sentinel('UNKNOWN')
A summary description of the documented item, extracted from its docstring.
bool other_docs = _Sentinel('UNKNOWN')
A flag indicating if the entire docstring body (except tags if any) is entirely included in the summary.
(str, str, ParsedDocstring) metadata = _Sentinel('UNKNOWN')
Metadata about the documented item, extracted from fields in its docstring.
DocstringField extra_docstring_fields = _Sentinel('UNKNOWN')
A list of new docstring fields tags that are defined by the documented item's docstring.
    Source Information
str docs_extracted_by = _Sentinel('UNKNOWN')
Information about where the information contained by this APIDoc came from.
Method Details [hide private]

__init__(self, **kwargs)
(Constructor)

source code 
call graph 

Construct a new APIDoc object. Keyword arguments may be used to initialize the new APIDoc's attributes.

Raises:
  • TypeError - If a keyword argument is specified that does not correspond to a valid attribute for this (sub)class of APIDoc.
Overrides: object.__init__

_debug_setattr(self, attr, val)

source code 

Modify an APIDoc's attribute. This is used when epydoc.DEBUG is true, to make sure we don't accidentally set any inappropriate attributes on APIDoc objects.

Raises:
  • AttributeError - If attr is not a valid attribute for this (sub)class of APIDoc. (attr is considered a valid attribute iff self.__class__ defines an attribute with that name.)

__setattr__(self, attr, val)

source code 

Modify an APIDoc's attribute. This is used when epydoc.DEBUG is true, to make sure we don't accidentally set any inappropriate attributes on APIDoc objects.

Raises:
  • AttributeError - If attr is not a valid attribute for this (sub)class of APIDoc. (attr is considered a valid attribute iff self.__class__ defines an attribute with that name.)
Overrides: object.__setattr__

__repr__(self)
(Representation operator)

source code 
Overrides: object.__repr__
(inherited documentation)

__str__(self, doublespace=0, depth=5, exclude=(), include=())
(Informal representation operator)

source code 

Return a pretty-printed string representation for the information contained in this APIDoc.

Overrides: object.__str__

specialize_to(self, cls)

source code 
call graph 

Change self's class to cls. cls must be a subclass of self's current class. For example, if a generic ValueDoc was created for a value, and it is determined that the value is a routine, you can update its class with:

>>> valdoc.specialize_to(RoutineDoc)

__hash__(self)
(Hashing function)

source code 
call graph 
Overrides: object.__hash__
(inherited documentation)

is_detailed(self)

source code 
call graph 

Does this object deserve a box with extra details?

Returns: bool
True if the object needs extra details, else False.

merge_and_overwrite(self, other, ignore_hash_conflict=False)

source code 
call graph 

Combine self and other into a merged object, such that any changes made to one will affect the other. Any attributes that other had before merging will be discarded. This is accomplished by copying self.__dict__ over other.__dict__ and self.__class__ over other.__class__.

Care must be taken with this method, since it modifies the hash value of other. To help avoid the problems that this can cause, merge_and_overwrite will raise an exception if other has ever been hashed, unless ignore_hash_conflict is True. Note that adding other to a dictionary, set, or similar data structure will implicitly cause it to be hashed. If you do set ignore_hash_conflict to True, then any existing data structures that rely on other's hash staying constant may become corrupted.

Returns:
self
Raises:
  • ValueError - If other has ever been hashed.

apidoc_links(self, **filters)

source code 

Return a list of all APIDocs that are directly linked from this APIDoc (i.e., are contained or pointed to by one or more of this APIDoc's attributes.)

Keyword argument filters can be used to selectively exclude certain categories of attribute value. For example, using includes=False will exclude variables that were imported from other modules; and subclasses=False will exclude subclasses. The filter categories currently supported by epydoc are:

  • imports: Imported variables.
  • packages: Containing packages for modules.
  • submodules: Contained submodules for packages.
  • bases: Bases for classes.
  • subclasses: Subclasses for classes.
  • variables: All variables.
  • private: Private variables.
  • overrides: Points from class variables to the variables they override. This filter is False by default.

Class Variable Details [hide private]

__mergeset

The set of all APIDoc objects that have been merged with this APIDoc (using merge_and_overwrite()). Each APIDoc in this set shares a common instance dictionary (__dict__).

Value:
None

Instance Variable Details [hide private]

metadata

Metadata about the documented item, extracted from fields in its docstring. Currently this is encoded as a list of tuples (field, arg, descr). But that may change.
Type:
(str, str, ParsedDocstring)
Value:
_Sentinel('UNKNOWN')

extra_docstring_fields

A list of new docstring fields tags that are defined by the documented item's docstring. These new field tags can be used by this item or by any item it contains.
Type:
DocstringField
Value:
_Sentinel('UNKNOWN')

docs_extracted_by

Information about where the information contained by this APIDoc came from. Can be one of 'parser', 'introspector', or 'both'.
Type:
str
Value:
_Sentinel('UNKNOWN')