[Python-Dev] Purpose of Doctests [Was: Best practices for Enum]

Stephen J. Turnbull stephen at xemacs.org
Mon May 20 06:17:04 CEST 2013

Gregory P. Smith writes:

 > I really do applaud the goal of keeping examples in documentation up to
 > date.  But doctest as it is today is the wrong approach to that. A repr
 > mismatch does not mean the example is out of date.

Of course it does.  The user sees something in the doc that's
different from what his interpreter tells him.  That may not bother a
long-time user of the module, or one who hangs out on python-commits
(uh-huh, uh-huh, yeah, right), but it worries new ones, and it should.
"What else may have changed?" is what they should be thinking.

Also, there are many cases where the output of a function is defined
by some external protocol: XML, JSON, RFC xxxx, etc.  Here doctests
are very valuable.

There are lots of testing applications where doctests suck.  There are
lots of testing applications where doctests are pretty much the
optimal balance between ease of creation and ease of maintenance.  I
wouldn't be surprised if there are applications (RAD?) where
*creating* tests as doctests and *converting* to a more
precisely-specified framework in maintenance is best practice.

Maybe somebody (not me, I do far too little testing even with doctests
:-( ) should write an informational PEP.

More information about the Python-Dev mailing list