Update of /cvsroot/python/python/dist/src/Doc/lib In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv11757/Doc/lib Modified Files: libdoctest.tex Log Message: Added IGNORE_EXCEPTION_DETAIL comparison option. The need is explained in the new docs. DocTestRunner.__run: Separate the determination of the example outcome from reporting that outcome, to squash brittle code duplication and excessive nesting. Index: libdoctest.tex =================================================================== RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdoctest.tex,v retrieving revision 1.40 retrieving revision 1.41 diff -u -d -r1.40 -r1.41 --- libdoctest.tex 30 Aug 2004 16:19:24 -0000 1.40 +++ libdoctest.tex 4 Sep 2004 17:21:02 -0000 1.41 @@ -307,6 +307,9 @@ to be the start of the exception detail. Of course this does the right thing for genuine tracebacks. +\item When the \constant{IGNORE_EXCEPTION_DETAIL} doctest option is + is specified, everything following the leftmost colon is ignored. + \end{itemize} \versionchanged[The ability to handle a multi-line exception detail @@ -365,6 +368,34 @@ is prone to in regular expressions. \end{datadesc} +\begin{datadesc}{IGNORE_EXCEPTION_DETAIL} + When specified, an example that expects an exception passes if + an exception of the expected type is raised, even if the exception + detail does not match. For example, an example expecting + \samp{ValueError: 42} will pass if the actual exception raised is + \samp{ValueError: 3*14}, but will fail, e.g., if + \exception{TypeError} is raised. + + Note that a similar effect can be obtained using \constant{ELLIPSIS}, + and \constant{IGNORE_EXCEPTION_DETAIL} may go away when Python releases + prior to 2.4 become uninteresting. Until then, + \constant{IGNORE_EXCEPTION_DETAIL} is the only clear way to write a + doctest that doesn't care about the exception detail yet continues + to pass under Python releases prior to 2.4 (doctest directives + appear to be comments to them). For example, + +\begin{verbatim} +>>> (1, 2)[3] = 'moo' #doctest: +IGNORE_EXCEPTION_DETAIL +Traceback (most recent call last): + File "<stdin>", line 1, in ? +TypeError: object doesn't support item assignment +\end{verbatim} + + passes under Python 2.4 and Python 2.3. The detail changed in 2.4, + to say "does not" instead of "doesn't". + +\end{datadesc} + \begin{datadesc}{COMPARISON_FLAGS} A bitmask or'ing together all the comparison flags above. \end{datadesc} @@ -463,6 +494,7 @@ \versionchanged[Constants \constant{DONT_ACCEPT_BLANKLINE}, \constant{NORMALIZE_WHITESPACE}, \constant{ELLIPSIS}, + \constant{IGNORE_EXCEPTION_DETAIL}, \constant{REPORT_UDIFF}, \constant{REPORT_CDIFF}, \constant{REPORT_NDIFF}, \constant{REPORT_ONLY_FIRST_FAILURE}, \constant{COMPARISON_FLAGS} and \constant{REPORTING_FLAGS}