[Guido]
... doctest_script(multi_line_string) -- specifies a doctest script, for use by the doctest module (if this is absent, it will continue to look in the doc string). I like to separate the doctest script from the actual documentation string because, when used for rigorous unit testing (as in Jim&Tim's talk at PyCON), the doctest script is too long to double as reasonable documentation. Maybe this should be imported from the doctest module.
Let me try to squash this one before it gains traction from people who don't use doctest anyway <wink>. Burying a large triple-quoted string inside a function call inside an indented "list" isn't going to help the readability of anything. Zope use is moving toward putting large doctests into their own .py file, or, more recently, into their own .txt file. An example of the former: http://cvs.zope.org/ZODB/src/ZODB/tests/testmvcc.py The idea that "too long" makes for unreasonable documentation doesn't make sense to me: these long doctests read like tutorials liberally sprinkled with Python examples, and are the best docs some of these subsystems will ever have. Indeed, the Python Tutorial is a prime example of something that "should be" a doctest, and I think that's exceptionally good documentation. Of course this doesn't preclude putting a judiciously few examples in docstrings either (also for doctest chewing), but I'd rather encourage people who want more than that to go all the way, and write a tutorial-style large doctest in its own file.