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