Handling common doctest issues

Good Python includes docstrings inside every module, class, function, and method. One important element of a docstring is an example. While doctest can make the example into a unit test case, the literal matching of the expected text output against the actual text can cause problems. There are some Python objects that do not have a consistent text representation.

For example, object hash values are randomized. This often results in the order of elements in a set collection being unpredictable. We have several choices for creating test case example output:

• Write tests that can tolerate randomization (often by converting to a sorted structure)
• Stipulate a value for the PYTHONHASHSEED environment variable
• Require that Python be run with the -R option to disable hash randomization entirely

There are several other considerations beyond simple variability in the location of keys or items in a set. Here are some other...