This article contains tips on using docstrings in Python. docstrings are the way you document your modules, classes, and functions--their purpose, how to use them, and even examples that can be used as testing inputs.
Using docstrings Edit
Python has a useful approach to code documentation called the docstring. This is simply a block of quoted text summarizing the purpose and usage of a Python object. By convention, they are enclosed in triple double-quotes (
"""..."""). For example:
def add(x, y): """Return the sum of x and y.""" return x + y
The docstring is the first string literal to appear in an object's definition. Here, the object is the add function. An object's docstring shows up when you use the built-in "help" function:
>>> help(add) Help on function add in module __main__: add(x, y) Return the sum of x and y.
You can look up any object's docstring via the
>>> print add.__doc__ Return the sum of x and y.
A module may also have a docstring; again, it's simply the first block of quoted text to appear in the module:
#! /usr/bin/env python # opts.py """This module provides an interface for defining command-line-style options, and for reading and storing their values as specified by the user. """ [module code]
The docstring for a module should be like a mini-manual for using the module. A descriptive opening sentence should tell users the purpose of the module, or a summary of what it does, followed by a mention of what classes and functions are most significant.
For further reference, see PEP 257: Docstring Conventions.
Using doctest Edit
You can include tests, in the form of examples, in your Python modules' docstrings. Properly written, these tests can be executed and verified by the doctest module.
First, include some tests in your module's docstring. Here's one of the test cases from the module docstring in libtovid/opts.py:
""" (...) To get and set options individually, do this: >>> useropts['width'] = 5.0 >>> useropts['width'] 5.0 """
This is just what it looks like: a copy-paste of statements and their output from the python interpreter. You can include as many of these as you like in your module's docstring. (Just be careful to use only statements and results that will always be the same; don't include an object's memory address, an unsorted list, or anything else that might be random or unpredictable.)
Now, you can use doctest on your module:
>>> from libtovid import opts >>> from doctest import testmod >>> testmod(opts) (0, 2) >>>
This says that 0 tests failed, and 2 tests passed. testmod() is looking in module opts for any blocks of documentation that look like python statements and output. testmod() runs them, and checks to make sure the output matches what's expected. You can run it in verbose mode like this:
>>> testmod(opts, verbose=True) Trying: useropts['width'] = 5.0 Expecting nothing ok Trying: useropts['width'] Expecting: 5.0 ok >>>
Some schools of thought encourage writing tests for code before writing the code itself; the doctest module is well suited for this approach, because it allows you to write "examples" that define how you expect your program to behave. Well-written doctests also help to keep the documentation in sync with the code, ensuring that any change in behavior is reflected in the accompanying docstring.