We saw previously how it was possible to ask at the REPL for help on Python functions. Let's look at how to add this self-documenting capability to our own module.

API documentation in Python uses a facility called docstrings. Docstrings are literal strings which occur as the first statement within a named block, such as a function or module. Let's document the fetch_words() function:

def fetch_words(url):
    """Fetch a list of words from a URL."""
    with urlopen(url) as story:
        story_words = []
        for line in story:
            line_words = line.decode('utf-8').split()
            for word in line_words:
                story_words.append(word)
    return story_words

We use triple-quoted strings even for single-line docstrings because they can be easily expanded to add more detail.

One Python convention for docstrings is documented in PEP 257, although it is not widely adopted. Various tools, such as Sphinx, are available to build HTML documentation from Python docstrings, and each tool mandates its preferred docstring format. Our preference is to use the form presented in Google's Python style-guide, since it is amenable to being machine parsed whilst still remaining readable at the console:

def fetch_words(url):
    """Fetch a list of words from a URL.

    Args:
        url: The URL of a UTF-8 text document.

    Returns:
        A list of strings containing the words from
        the document.
    """
    with urlopen(url) as story:
        story_words = []
        for line in story:
            line_words = line.decode('utf-8').split()
            for word in line_words:
                story_words.append(word)
    return story_words

Now we'll access this help() from the REPL:

$ python3
Python 3.5.0 (default, Nov 3 2015, 13:17:02)
[GCC 4.2.1 Compatible Apple LLVM 6.1.0 (clang-602.0.53)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from words import *
>>> help(fetch_words)

Help on function fetch_words in module words:

fetch_words(url)
    Fetch a list of words from a URL.

    Args:
        url: The URL of a UTF-8 text document.

    Returns:
        A list of strings containing the words from
        the document.

We'll add similar docstrings for our other functions:

def print_items(items):
    """Print items one per line.

    Args:
        items: An iterable series of printable items.
    """
    for item in items:
        print(item)


def main(url):
    """Print each word from a text document from at a URL.

    Args:
        url: The URL of a UTF-8 text document.
    """
    words = fetch_words(url)
    print_items(words)

And one for the module itself. Module docstrings should be placed at the beginning of the module, before any statements:

"""Retrieve and print words from a URL.

Usage:

 python3 words.py <URL>
"""
import sys
from urllib.request import urlopen

Now when we request help() on the module as a whole, we get quite a lot of useful information:

$ python3
Python 3.5.0 (default, Nov 3 2015, 13:17:02)
[GCC 4.2.1 Compatible Apple LLVM 6.1.0 (clang-602.0.53)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import words
>>> help(words)

Help on module words:

NAME
    words - Retrieve and print words from a URL.

DESCRIPTION
    Usage:
        python3 words.py <URL>

FUNCTIONS
    fetch_words(url)
        Fetch a list of words from a URL.

        Args:
            url: The URL of a UTF-8 text document.

        Returns:
           A list of strings containing the words from
           the document.

    main(url)
       Print each word from a text document from at a URL.

       Args:
       url: The URL of a UTF-8 text document.

    print_items(items)
        Print items one per line.

        Args:
        items: An iterable series of printable items.

FILE
    /Users/sixtynorth/the-python-apprentice/words.py

(END)