epydoc.apidoc.APIDoc

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 `APIDoc`s 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
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) repr(x) | 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
Call Graph
__hash__(self) hash(x) | source code call graph
Call Graph
__cmp__(self, other) | source code call graph
Call Graph
`bool` |
is_detailed(self) Does this object deserve a box with extra details? | source code call graph
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
Call Graph
apidoc_links(self, **filters) Return a list of all `APIDoc`s 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
Inherited from `object`: `__delattr__`, `__getattribute__`, `__new__`, `__reduce__`, `__reduce_ex__`

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.

Properties | [hide private]
Inherited from `object`: `__class__`

Method Details | [hide private]

### __init__(self, **kwargs) (Constructor) | source code call graph
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
    repr(x)
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
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
Call Graph
    hash(x)
Overrides: object.__hash__ (inherited documentation)

### is_detailed(self) | source code call graph
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
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 `APIDoc`s 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')