Home       Trees       Index       Help   

epydoc 3.0alpha2

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

Class APIDoc
source code

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.
  _debug_setattr(self, attr, val)
Modify an APIDoc's attribute.
  __setattr__(self, attr, val)
Modify an APIDoc's attribute.
  __repr__(self)
repr(x)...
  pp(self, doublespace=0, depth=5, exclude=(), include=())
Return a pretty-printed string representation for the information contained in this APIDoc.
  __str__(self, doublespace=0, depth=5, exclude=(), include=())
Return a pretty-printed string representation for the information contained in this APIDoc.
  specialize_to(self, cls)
Change self's class to cls.
  __hash__(self)
hash(x)...
  __cmp__(self, other)
  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.
  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.)

Inherited from object: __delattr__, __getattribute__, __new__, __reduce__, __reduce_ex__


Class Variables [hide private]
__has_been_hashed True iff self.__hash__() has ever been called.
__mergeset The set of all APIDoc objects that have been merged with this APIDoc (using merge_and_overwrite()).

Inherited from object: __class__


Instance Variables [hide private]
    Docstrings
docstring The documented item's docstring.
docstring_lineno The line number on which the documented item's docstring begins.
    Information Extracted from Docstrings
descr A description of the documented item, extracted from its docstring.
summary A summary description of the documented item, extracted from its docstring.
metadata Metadata about the documented item, extracted from fields in its docstring.
extra_docstring_fields A list of new docstring fields tags that are defined by the documented item's docstring.
    Source Information
docs_extracted_by 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 
call graph 
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 
call graph 
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  
repr(x)
Overrides: object.__repr__
(inherited documentation)

pp(self, doublespace=0, depth=5, exclude=(), include=())

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

__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 		 
hash(x)
Overrides: object.__hash__
(inherited documentation)

__cmp__(self, other)
(Comparison operator)

source code 
call graph 

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.

Class Variable Details [hide private]

__has_been_hashed

True iff self.__hash__() has ever been called.
Value:
False

__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]

docstring

The documented item's docstring.
Type:
string or None
Value:
epydoc.apidoc.UNKNOWN

docstring_lineno

The line number on which the documented item's docstring begins.
Type:
int
Value:
epydoc.apidoc.UNKNOWN

descr

A description of the documented item, extracted from its docstring.
Type:
ParsedDocstring
Value:
epydoc.apidoc.UNKNOWN

summary

A summary description of the documented item, extracted from its docstring.
Type:
ParsedDocstring
Value:
epydoc.apidoc.UNKNOWN

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:
epydoc.apidoc.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:
epydoc.apidoc.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:
epydoc.apidoc.UNKNOWN

   Home       Trees       Index       Help   

epydoc 3.0alpha2

Generated by Epydoc 3.0alpha2 on Tue Apr 11 17:32:10 2006 http://epydoc.sf.net