[Python-Dev] Doctest and Footnotes (original) (raw)

Benji York benji at zope.com
Tue Jul 11 05:36:07 CEST 2006

A coworker of mine (Gary Poster) had a really good idea a couple weeks ago: teach doctest about ReST-style footnotes. I implemented it over the weekend and brought it to Tim Peter's attention today. Tim generally liked the idea and suggested I bring it up here.

Here's the idea: when a footnote is referenced in prose, execute the code associated with the footnote at that point. For example:

""" After initializing the system [#init]_ it is possible to retrieve status information:

 >>> system.status()
 'good to go'

[snip some of the doctest]

.. [#init] Initialize the system: >>> system = System() >>> system.init() """

The footnote code is executed every time the footnote is referenced, and is /not/ executed at any other time (i.e. it's not executed at the point the footnote is defined). A warning is generated if a footnote (that includes code) is defined but never used.

This would allow moving repetitive or verbose code (e.g. tests for corner cases) into footnotes so they won't hinder the documentation aspect of a test. It also allows defining reusable bits of setup code, freeing the doctest author to structure the prose as they wish instead of being constrained by having to place bits of code with common environmental needs together.

I've implemented this in a branch of zope.testing (which contains a copy of a post-Python 2.4.3 version of doctest (http://tinyurl.com/nekam). The behavior is controlled by an optionflag, much like ELLIPSIS or NORMALIZE_WHITESPACE. Tim has given me a few pointers on improvements to make, which I'll work on this week.

Thoughts/questions?

Benji York Senior Software Engineer Zope Corporation

More information about the Python-Dev mailing list