doctest: address in output
 

Recently (30 minutes ago...) I need to write a doctring
of the following type:

>>> import mymodule
>>> mymodule.do_something()
<mymodule.coolObj object at ...>

And I wanted to run doctest on this module. Now, I agree that avoiding
addresses in test output is a good thing in general; but, in this case I
wanted the '...' to match whatever address the object happened to be at.

Here's a patch to doctest.py to enable this functionality:
(against python-2.2.3)

--- /usr/lib/python2.2/doctest.py 2003-10-15 22:41:35.000000000 -0500
+++ mydoctest.py 2004-05-03 21:08:55.000000000 -0500
@@ -288,6 +288,7 @@
_isPS2 = re.compile(r"(\s*)" + re.escape(PS2)).match
_isEmpty = re.compile(r"\s*$").match
_isComment = re.compile(r"\s*#").match
+_subAddress = re.compile(r"0x[0-9a-f]*>$").sub
del re

from types import StringTypes as _StringTypes
@@ -451,6 +452,11 @@
if verbose:
out("ok\n")
continue
+ got = _subAddress('...>', got)
+ if got == want:
+ if verbose:
+ out("ok\n")
+ continue
state = FAIL

assert state in (FAIL, BOOM)


I was impressed by how easy it was to figure out how to make this
change... I can't even *imagine* trying to fiddle with the standard
library in, say, C++.

In fact, it's only with python that I've really experienced the true
potential of Open Source: it's invariably too much work to change a
C/C++ program written by someone else. It takes too long to understand
what is going on; you have to go through a lengthy compile; you have to
worry about installation. Python makes it all so easy.

I've hardly ever modified a C/C++ application that I've downloaded from
somewhere---and I've almost always made small tweaks to the ones in python.
These days I prefer python applications simply because I know I'll be able
to *actually* change them to suit my needs, rather than theoretically have
the ability to change them.

-param

Re: doctest: address in output
 

Param> Recently (30 minutes ago...) I need to write a doctring of the
Param> following type:

>>>> import mymodule
>>>> mymodule.do_something()
Param> <mymodule.coolObj object at ...>

Param> And I wanted to run doctest on this module. Now, I agree that
Param> avoiding addresses in test output is a good thing in general;
Param> but, in this case I wanted the '...' to match whatever address
Param> the object happened to be at.

[patch elided]

Why not just change your doctest to be

>>> import mymodule
>>> isinstance(mymodule.do_something(), mymodule.coolObj)
True

? That avoids two problems, the issue of addresses and the possibility that
the repr() of your coolObj class changes.

Skip

Re: doctest: address in output
 

> > >>> mymodule.do_something()
> > <mymodule.coolObj object at ...>
>
> Why not just change your doctest to be
>
> >>> import mymodule
> >>> isinstance(mymodule.do_something(), mymodule.coolObj)
> True
>
> ? That avoids two problems, the issue of addresses and the possibility that
> the repr() of your coolObj class changes.

Because the former seems to be *much* easier to read than the latter.

The return value of the function is designed to be ignored in normal
use. Doing something with it, like assigning it to a variable or using
isinstance() as you suggest, would make the documentation both unclear
as well as harder to read than it should be.

Making a doctest hard to read would go against the purpose of having
doctests at all. I may as well use the unittest module then.

-param

Re: doctest: address in output
 

>> > >>> mymodule.do_something()
>> > <mymodule.coolObj object at ...>
>>
>> Why not just change your doctest to be
>>
>> >>> import mymodule
>> >>> isinstance(mymodule.do_something(), mymodule.coolObj)
>> True
>>
>> ? That avoids two problems, the issue of addresses and the possibility that
>> the repr() of your coolObj class changes.

Param> Because the former seems to be *much* easier to read than the
Param> latter.

Param> The return value of the function is designed to be ignored in
Param> normal use.

Then make it return None and use a different function on those presumably
rare occasions where you need it.

Param> Doing something with it, like assigning it to a variable or using
Param> isinstance() as you suggest, would make the documentation both
Param> unclear as well as harder to read than it should be.

My apologies. It was unclear to me that you intended this to be primarily
documentation. I thought since you were running doctest it was primarily a
test case.

Param> Making a doctest hard to read would go against the purpose of
Param> having doctests at all. I may as well use the unittest module
Param> then.

Maybe not if the "test" part of "doctest" is more important than the "doc"
part.

Skip

Re: doctest: address in output
 

> >> > >>> mymodule.do_something()
> >> > <mymodule.coolObj object at ...>
>
> Param> The return value of the function is designed to be ignored in
> Param> normal use.
>
> Then make it return None and use a different function on those presumably
> rare occasions where you need it.

I may realize later that the interface is inappropriate; but I don't want
to change it because of what the testing framework wants. (Yes, difficulty
in testing often hints at problems in the code, but in this particular
case I think the problem is in the testing framework)

> Maybe not if the "test" part of "doctest" is more important than the "doc"
> part.

I started writing it as documentation, and then realized that it could be
made to do double duty for testing. And, it could be checked
automatically so that it didn't become inaccurate.

Anyway, the patch I posted works for me. It could be made more robust
and/or general in case other people are interested.

-param