Python module docstrings tutorial

In this tutorial we will discuss how to create docstrings as a form of documentation for a Python Module.

When creating libraries for external use, you need to properly document your library/module so others have an easy time deciphering it. There is no “universal format” for creating module docstrings (or any docstring for that matter), but there are several key features that every docstring should have.

In this tutorial we will show you how to properly document a Python module with an appropriate docstring.

Documenting Python Modules with Docstrings

Documenting modules is typically done in the following manner:

1. First, we add a short description about the module. This should make it clear to the reader what task(s) the module was created for.
2. A list of all Classes contained within the module, that are available for use when the module is imported.
3. A list of all Functions contained within the module, that are available for use when the module is imported.
4. Any other important information about the module which should be made available to the programmer, such as dependencies.

What’s listed above are the “compulsory” components for a docstring. You are free to modify the docstring and further expand upon it by adding extra detail as long as it’s informative and useful for the programmer.

Let’s create a module docstring of our own, just to see how it’s done. In a new file called mymodule.py, i created the following docstring.

"""
This is my own custom module for 
demonstration purposes.

Classes:
    MyClass1
    MyClass2
    MyClass3

Functions:
    MyFunction1(int, int)
    MyFunction2(int, string) -> string
    MyFunction() -> int
"""

For the functions, you need to specify the proper signatures, along with their return type using type annotations. You can also choose to add a short one-line description for each Class and Function.

Now if we import this module into another file, we can print out it’s docstring using the __doc__ attribute.

import mymodule

print(mymodule.__doc__)

If you run the above code, it will print out the docstring.

To get a better picture on docstrings for modules, let’s examine the docstrings for a few popular Python libraries.

Examples of Docstrings for Modules

The Pickle library is fairly simple, and only comprises of a few Classes and Functions. Hence the docstring for it is fairly simple.

import pickle

print(pickle.__doc__)

Create portable serialized representations of Python objects.

See module copyreg for a mechanism for registering custom picklers.
See module pickletools source for extensive comments.

Classes:

    Pickler
    Unpickler

Functions:

    dump(object, file)
    dumps(object) -> string
    load(file) -> object
    loads(string) -> object

Misc variables:

    __version__
    format_version
    compatible_formats

The regular expression library is extremely tricky for newcomers due to syntax. Even those familiar with regex will have a hard time remembering all the various characters involved and what they mean. Hence the docstring for it actually includes a character guide and many examples.

import re

print(re.__doc__)

Support for regular expressions (RE).

This module provides regular expression matching operations similar to
those found in Perl.  It supports both 8-bit and Unicode strings; both
the pattern and the strings being processed can contain null bytes and
characters outside the US ASCII range.

Regular expressions can contain both special and ordinary characters.
Most ordinary characters, like "A", "a", or "0", are the simplest
regular expressions; they simply match themselves.  You can
concatenate ordinary characters, so last matches the string 'last'.

The special characters are:
    "."      Matches any character except a newline.
    "^"      Matches the start of the string.
    "$"      Matches the end of the string or just before the newline at
             the end of the string.
    "*"      Matches 0 or more (greedy) repetitions of the preceding RE.
             Greedy means that it will match as many repetitions as possible.
    "+"      Matches 1 or more (greedy) repetitions of the preceding RE.
    "?"      Matches 0 or 1 (greedy) of the preceding RE.
    *?,+?,?? Non-greedy versions of the previous three special characters.
    {m,n}    Matches from m to n repetitions of the preceding RE.
    {m,n}?   Non-greedy version of the above.
    "\\"     Either escapes special characters or signals a special sequence.
    []       Indicates a set of characters.
             A "^" as the first character indicates a complementing set.
    ...
    ...
    ...

The docstring is actually much longer but showing the full thing isn’t very feasible. You can run the code yourself to see the full output.

This marks the end of the Python module docstrings Tutorial. Any suggestions or contributions for CodersLegacy are more than welcome. Questions regarding the tutorial content can be asked in the comments section below.