[Python-Dev] Request for review

[Nick Coghlan]

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