doctest

[Thomas Heller]

"Tim Peters" <tim.one at comcast.net> writes:

> [Thomas Heller]
>> This simple script reads the ctypes docs written in StructuredText,
>> and runs and tests the code examples in it:
>>
>> """
>> import doctest
>>
>> ex = doctest._extract_examples(file("tutorial.stx").read())
>> doctest._run_examples(ex, {}, 0, "tutorial.stx", 0, 0)
>> """

>> Do I understand correctly that the doctest-pretty printer will
>> eventually remove the remaining 'warts', ie that doctest complains
>> about the address part in this?
>>
>> >>> class X(object): pass
>> ...
>> >>> x = X()
>> >>> x
>> >>> <__main__.X object at 0x008FA3F0>
>
> Probably, but it's a tradeoff:  doctest strove to be 100% WYSIWYG, and the
> "doc" part of "doctest" does suffer when that fails.  In this case, I think
> your example makes for poor documentation:  what are you really trying to
> communicate?

The ctypes tutorial contains (among others) code examples like this:

      >>> from ctypes import *
      >>> windll.kernel32
      <WinDLL 'kernel32', handle 77e80000 at 7ecfe8>
      >>> cdll.msvcrt
      <CDLL 'msvcrt', handle 78000000 at 80b010>

This may not be the best documentation, but it shows what the programmer
sees when he experiments with ctypes at the command prompt.  Neither the
repr string nor the type of the result is particularly interesting...

>  If it's that X() creates an X object, then
>
>>>> class X(object): pass
>>>> x = X()
>>>> type(x) is X
> True
>
> is a much cleaner statement.

I used the script above to make sure that the code examples in the
ctypes tutorial are correct (they weren't).  And it seems doctest is a
fantastic way to show that.

Of course it's easy to skim the output manually and see that the
following failure is a minor detail:
"""
*****************************************************************
Failure in example: print windll.kernel32
from line #30 of tutorial.stx
Expected: <WinDLL 'kernel32', handle 77e80000 at 7ecfe8>
Got: <WinDLL 'kernel32', handle 77e40000 at 995d00>
"""

OTOH, it would make more efficient testing if no error would be reported
;-)  How will the doctest pretty printer handle things like these?
Will it skip sections like these ' at xxx>', where xxx is a hex number?

Thomas