Docstring Conventions

Style Guide For Python Code

      Another category of attributes are those that are part of the "subclass

      API" (often called "protected" in other languages).  Some classes are

      designed to be inherited from, either to extend or modify aspects of the

      class's behavior.  When designing such a class, take care to make

      explicit decisions about which attributes are public, which are part of

      the subclass API, and which are truly only to be used by your base

      class.

      With this in mind, here are the Pythonic guidelines:

      - Public attributes should have no leading underscores.

      - If your public attribute name collides with a reserved keyword, append

        a single trailing underscore to your attribute name.  This is

        preferable to an abbreviation or corrupted spelling.  (However,

        notwithstanding this rule, 'cls' is the preferred spelling for any

        variable or argument which is known to be a class, especially the

        first argument to a class method.)

        Note 1: See the argument name recommendation above for class methods.

      - For simple public data attributes, it is best to expose just the

        attribute name, without complicated accessor/mutator methods.  Keep in

        mind that Python provides an easy path to future enhancement, should

        you find that a simple data attribute needs to grow functional

        behavior.  In that case, use properties to hide functional

        implementation behind simple data attribute access syntax.

        Note 1: Properties only work on new-style classes.

        Note 2: Try to keep the functional behavior side-effect free, although

        side-effects such as caching are generally fine.

        Note 3: Avoid using properties for computationally expensive

        operations; the attribute notation makes the caller believe

        that access is (relatively) cheap.

      - If your class is intended to be subclassed, and you have attributes

        that you do not want subclasses to use, consider naming them with

        double leading underscores and no trailing underscores.  This invokes

        Python's name mangling algorithm, where the name of the class is

        mangled into the attribute name.  This helps avoid attribute name

        collisions should subclasses inadvertently contain attributes with the

        same name.

        Note 1: Note that only the simple class name is used in the mangled

        name, so if a subclass chooses both the same class name and attribute