# Module doctest version 0.9.5
# Released to the public domain 29-Jun-1999,
# by Tim Peters (
[email protected]).
doctest.py provides a flexible framework for automatically testing
examples in docstrings. It's very easy to use (well, at least to
use as intended ...):
+ Run some illuminating examples in an interactive session.
+ Paste a copy of that session into a docstring, interspersed freely
among your docstring prose.
+ Add a few lines of boilerplate code to the end of the module, to
invoke the doctest magic when your module is run directly as a
script: the docstring examples will be found and interpreted,
verifying they still work exactly as advertised.
Extensive docs are in doctest.py's docstrings, and some even serve
as non-trivial examples of doctest's intended use. Warning: thinking
too hard about how doctest manages to run docstring examples of its
own use in its own source code can make your head explode <kaboom>.
PROBLEMS WITH EMACS PYTHON MODE, JPYTHON, NETSCAPE
If doctest.py fails to compile, or fails one of its own tests, do whatever
you have to do to make sure each line of the file ends with a sole newline
(without a preceding carriage return). Some methods of downloading (via
Netscape in particular) damage the file by "helpfully" changing its line
endings. JPython is particularly sensitive to this.
Also, wrt Emacs, because doctest includes examples of its own use in its
own docstrings, and the examples themselves contain docstrings, there are
some very complicated nested triple-quoted strings in doctest.py. These
confuse pymode a little, and there's nothing pymode can do about this --
don't even ask. It will not be a problem in your own docstring examples,
unless you also nest docstrings (in which case, grow up <wink>).
