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 __init__ signature header
    • Attributes:
      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:
      the __init__ signature and documentation, i.e. the syntax to create a new instance of this class.
    • Class methods and Class properties.

Type Annotations

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 list.

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:

Mapping

An object supporting keyed access to its members (like a dict). E.g. 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 dict supports.

Iterable

An object that supports iterator interface. e.g. Iterable[int]

Optional

The specified type maybe present or None. e.g. Optional[str]: means that either str or None is accepted or returned.

Union

More general form of Optional where multiple types are acceptable. e.g. Union[str, float]: means that either a str or a float is acceptable

Any

Any type is acceptable.