Mastering Object-oriented Python

Writing file-level docstrings, including modules and packages

A package or a module's purpose is to contain a number of elements. A package contains modules as well as classes, global variables, and functions. A module contains classes, global variables, and functions. The top-level docstrings on these containers can act as road-maps to explain the general features of the package or module. The details are delegated to the individual classes or functions.

We might have a module docstring that looks like the following code:

Blackjack Cards and Decks ========================= This module contains a definition of ``Card``, ``Deck`` and ``Shoe`` suitable for Blackjack. The ``Card`` class hierarchy ----------------------------- The ``Card`` class hierarchy ...