[Python-3000] doctests vs. unittests (was Re: pimp; restructuring the standard library)

[Phillip J. Eby]

At 01:40 AM 6/29/2007 -0400, Chris McDonough wrote:
>When coverage gets good, "documentation-ness" of tests suffers.

The question is more one of, "documentation for whom?".  You can 
write separate documents for library users than for library 
extenders/developers.  I don't put doctests in docstrings, but if I 
did, I'd probably only put user doctests there.  As it is, I normally 
split my doctests into multiple files for different audiences, or 
under different headings in one large file.

For example, if you look at the BytecodeAssembler documentation:

    http://peak.telecommunity.com/DevCenter/BytecodeAssembler

You'll see that the assertion and invariant testing is mostly 
relegated to a separate section.

Another library I'm working on has two doctest files for users (a 
quick intro and a developer guide/reference) and a separate file that 
tests all the innards.  So, there are a lot of ways to use doctests 
effectively, at least if you're doing them in text files, rather than 
in your docstrings.  I've actually never put a doctest in a 
docstring; it always seems like overkill to me.  (Especially since 
reST doctests can be made into nice HTML pages like the above!)