[Python-Dev] Purpose of Doctests [Was: Best practices for Enum] (original) (raw)

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