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.
|
|
|
| Call Graph |
|---|
|
|
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
| Call Graph |
|---|
|
|
|
|
| Call Graph |
|---|
|
|
|
|
| Call Graph |
|---|
|
bool
|
|
| Call Graph |
|---|
|
|
|
|
| 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
|
|
|
Inherited from object:
__delattr__,
__getattribute__,
__new__,
__reduce__,
__reduce_ex__
|
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.
|
|
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.
|
str
|
docs_extracted_by = _Sentinel('UNKNOWN')
Information about where the information contained by this
APIDoc came from.
|
|
Inherited from object:
__class__
|
|
|
| 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__
|
|
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.)
|
|
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(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__
|
|
|
| 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)
|
|
|
| Call Graph |
|---|
hash(x)
- Overrides:
object.__hash__
- (inherited documentation)
|
|
|
| Call Graph |
|---|
Does this object deserve a box with extra details?
- Returns:
bool
- True if the object needs extra details, else False.
|
|
|
| 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.
|
|
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.
|
__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:
-
|
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:
-
|
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:
-
|
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:
-
|