Guide to Reading the API Reference¶
The API documentation is auto-generated using sphinx and the napolean sphinx extension. Some of the layout and terminology may need some more explanation.
API Documentation Structure¶
The API listings are grouped by sub-package, then module, then class.
The class layout can appear a little confusing because of some limitations of the autodocumentation (or more likely some limitations of my knowledge of how to use it).
In particular, the documented public attributes of classes (actually, attributes of class instances) are included without a header section.
Class documentation is layed out in the following structure:
- Class summary: the
- Documented public attributes (other than explicit properties). The Attributes section has no title so everything you see until the instance creation documentation is an attribute.
- Class instantiation:
__init__signature and documentation, i.e. the syntax to create a new instance of this class.
- Class methods and Class properties.
- Class summary: the
The package uses type annotations with types imported from the
typing library. For a full explanation of how these are used
and how to interpret some of the odder-looking types please
see PEP 484.
typing uses abstract classes to help deal with duck typing - e.g.
MyFancyList may implement all required
list interfaces but not
actually be derived from
Most of the types used are easily interpretable (e.g.
Tuple ~= tuple)
with the advantage that you can supply type annotations to Tuple’s
members - e.g.
Tuple[str, int, float].
Some members of
typing are a little more esoteric:
An object supporting keyed access to its members (like a
Mapping[str, MyClass]: when this appears in a parameter type
annotation, it means that any dict-like object (that takes a type str
as a key and returns an object of type MyClass) T2 is acceptable.
This is more rarely used in return type annotations but means that
the returned object will support keyed access to members but not necessarily
implement everything that
An object that supports iterator interface.
The specified type maybe present or None.
Optional[str]: means that either str or None is
accepted or returned.
More general form of
Optional where multiple types are
Union[str, float]: means that either a str or a float is acceptable
Any type is acceptable.