[Python-Dev] Request for review
Nick Coghlan
ncoghlan at gmail.com
Thu Apr 13 10:32:19 CEST 2006
Tim Peters wrote:
> [Georg Brandl]
>> Hm. This broke a few doctests. I can fix them, but I wonder if
>> doctest should accept a bare exception name if the exception
>> is defined in the current module.
>
> No.
>
>> Or should it ignore the module name altogether?
>
> No. doctest strives to be magic-free WYSIWYG. If someone _intends_
> the module name to be optional in a doctest, they should explicitly
> use doctest's ELLIPSIS option.
There's already a little bit of magic in the way doctest handles exceptions. I
always use doctest.IGNORE_EXCEPTION_DETAIL so that everything after the first
colon on the last line gets ignored when matching exceptions. That allows me
to include the text of the exception in the documentation so its clear what
the associated problem is, without worrying about spurious failures due to
variations in the exact wording of the error message.
Using an ellipsis instead would get essentially the same effect from a test
point of view, but would result in less effective documentation. Given that
the option exists, I assume I'm not the only who thinks that way.
To get back to the original question of ignoring module names, I wonder if
doctext should actually try to be a bit cleverer about the way it matches
exceptions when the ignore exception detail flag is in effect.
At the moment, documenting something as raising ZeroDivisionError in a
doctest, but then actually raising a differently named subclass (such as
decimal.DivisionByZero) in the code will result in a failed test.
IMO, this is a spurious failure if I've told the doctest engine that I don't
care about the details of exceptions raised - there's nothing wrong with the
documentation, as the following relationship holds:
Py> issubclass(decimal.DivisionByZero, ZeroDivisionError)
True
The fact that what the call raises is technically an instance of a subclass
rather than of the listed class is really an implementation detail, just like
the text in the associated error message. The important point is that an
except clause covering the documented exception type will catch the raised
exception.
The doctest machinery has access to both the expected exception name, the
actual exception raised, and the dictionary used to execute the test, so
something like "issubclass(exc_type, eval(expected_exc_name, test_globs))"
should do the trick (with a bit of work to extract the expected exception
name, naturally).
Cheers,
Nick.
--
Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia
---------------------------------------------------------------
http://www.boredomandlaziness.org
More information about the Python-Dev
mailing list