[TIP] Python Testing book review

[Jim Fulton]

On Sun, Mar 7, 2010 at 10:56 AM, Tarek Ziadé <ziade.tarek at gmail.com> wrote:
...
>> Did you try using manuel, http://packages.python.org/manuel/?  I've
>> found many code examples that don't fit the doctest python-prompt
>> style, either because they are module source, or because they aren't
>> even Python. I'm very happy with how the bobo dcumentation,
>> http://bobo.digicool.com/, turned out with manuel's help. Almost all
>> of the bobo examples are tested even though none are in the
>> traditional doctest style.
>
> No, I wasn't aware of that project, it looks like it fixes some issues
> I have mentioned. I'll have a try!

I think you'll like it. :)

> If it doesn't do it already, (I didn't read the whole doc) it could
> try to look for syntax errors in code snippets even if they are not
> tested, as I mentioned. That would cut down typos in doc imho.

This is easy, in many ways. If the source is just a class definition,
for example, you could just exec it.

I'm particularly fond of a manuel-enabled construct that takes the
form:

  prose blah blah blah::

    some source goes here

  .. -> some_variable

    >>> some_variable.strip()
    'some source goes here'

The construct:

  .. -> some_variable

does 2 things:

  - It introduces a ReST comment

  - It assigned the contents of the preceeding block to a Python
    variable, some_variable.

In the Python comment, I make doctest assertions about the source. The
asertion might try compiling it, it might update module source for a
later example to use, make a web request, whatever. :)  The doctest
assertions aren't visible to the reader because their in the ReST
comment.

I recommend looking at the .text files in the bobo documentatin source:

  http://svn.zope.org/bobo/trunk/bobodoctestumentation/src/bobodoctestumentation/

such as:

  http://svn.zope.org/bobo/trunk/bobodoctestumentation/src/bobodoctestumentation/index.txt?view=auto

Jim

--
Jim Fulton