doctest

[Tim Peters]

[Thomas Heller, on a doctest "pretty printer"]

...

> 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...

Then maybe, to the extent that the output isn't interesting, it does indeed
not make for good docs.

....
> 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?

Trying to *guess* what is and isn't important in a chunk of output is
something doctest has always avoided to date.  As I said last time,

    but it's a tradeoff:  doctest strove to be 100% WYSIWYG,
    and the "doc" part of "doctest" does suffer when that fails.

> Will it skip sections like these ' at xxx>', where xxx is a
> hex number?

I don't think so, but it may do "something like that" if a more precise
definition of "sections like these" can be formulated.

For a start, Python puts a leading 0x before the address in such reprs:

>>> C
<class __main__.C at 0x006A5450>
>>> C()
<__main__.C instance at 0x006AC0D0>
>>>

so the weakest I'd be inclined to entertain is substituting away a match of
the regexp

    r' at 0[xX][\da-fA-F]+>'

That wouldn't hide the varying addresses attached to your "handle" output,
though.