Handling common doctest issues

Good Python includes docstrings inside every module, class, function, and method. Many tools can create useful, informative documentation from minimally complete docstrings.

One important element of a docstring is an example. The example becomes a kind of unit test case. Doctest does simple, literal matching of the expected output against the actual output. There are some Python objects, however, that are not consistent every time they're referred to.

For example, all object hash values are randomized. This means that the order of elements in a set or the order of keys in a dictionary can vary. 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...