[Python-checkins] r45701 - in python/trunk: Doc/lib/libdoctest.tex Lib/doctest.py Lib/test/test_doctest.py Misc/NEWS

tim.peters python-checkins at python.org
Tue Apr 25 05:31:37 CEST 2006


Author: tim.peters
Date: Tue Apr 25 05:31:36 2006
New Revision: 45701

Modified:
   python/trunk/Doc/lib/libdoctest.tex
   python/trunk/Lib/doctest.py
   python/trunk/Lib/test/test_doctest.py
   python/trunk/Misc/NEWS
Log:
Patch #1475231:  add a new SKIP doctest option, thanks to
Edward Loper.


Modified: python/trunk/Doc/lib/libdoctest.tex
==============================================================================
--- python/trunk/Doc/lib/libdoctest.tex	(original)
+++ python/trunk/Doc/lib/libdoctest.tex	Tue Apr 25 05:31:36 2006
@@ -616,6 +616,20 @@
 
 \end{datadesc}
 
+\begin{datadesc}{SKIP}
+
+    When specified, do not run the example at all.  This can be useful
+    in contexts where doctest examples serve as both documentation and
+    test cases, and an example should be included for documentation
+    purposes, but should not be checked.  E.g., the example's output
+    might be random; or the example might depend on resources which
+    would be unavailable to the test driver.
+
+    The SKIP flag can also be used for temporarily "commenting out"
+    examples.
+
+\end{datadesc}
+
 \begin{datadesc}{COMPARISON_FLAGS}
     A bitmask or'ing together all the comparison flags above.
 \end{datadesc}
@@ -744,6 +758,7 @@
     were added; by default \code{<BLANKLINE>} in expected output
     matches an empty line in actual output; and doctest directives
     were added]{2.4}
+\versionchanged[Constant \constant{SKIP} was added]{2.5}
 
 There's also a way to register new option flag names, although this
 isn't useful unless you intend to extend \refmodule{doctest} internals

Modified: python/trunk/Lib/doctest.py
==============================================================================
--- python/trunk/Lib/doctest.py	(original)
+++ python/trunk/Lib/doctest.py	Tue Apr 25 05:31:36 2006
@@ -54,6 +54,7 @@
     'DONT_ACCEPT_BLANKLINE',
     'NORMALIZE_WHITESPACE',
     'ELLIPSIS',
+    'SKIP',
     'IGNORE_EXCEPTION_DETAIL',
     'COMPARISON_FLAGS',
     'REPORT_UDIFF',
@@ -136,12 +137,14 @@
 DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
 NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
 ELLIPSIS = register_optionflag('ELLIPSIS')
+SKIP = register_optionflag('SKIP')
 IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')
 
 COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 |
                     DONT_ACCEPT_BLANKLINE |
                     NORMALIZE_WHITESPACE |
                     ELLIPSIS |
+                    SKIP |
                     IGNORE_EXCEPTION_DETAIL)
 
 REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
@@ -1233,6 +1236,10 @@
                     else:
                         self.optionflags &= ~optionflag
 
+            # If 'SKIP' is set, then skip this example.
+            if self.optionflags & SKIP:
+                continue
+
             # Record that we started this example.
             tries += 1
             if not quiet:
@@ -1792,6 +1799,7 @@
         DONT_ACCEPT_BLANKLINE
         NORMALIZE_WHITESPACE
         ELLIPSIS
+        SKIP
         IGNORE_EXCEPTION_DETAIL
         REPORT_UDIFF
         REPORT_CDIFF
@@ -1914,6 +1922,7 @@
         DONT_ACCEPT_BLANKLINE
         NORMALIZE_WHITESPACE
         ELLIPSIS
+        SKIP
         IGNORE_EXCEPTION_DETAIL
         REPORT_UDIFF
         REPORT_CDIFF

Modified: python/trunk/Lib/test/test_doctest.py
==============================================================================
--- python/trunk/Lib/test/test_doctest.py	(original)
+++ python/trunk/Lib/test/test_doctest.py	Tue Apr 25 05:31:36 2006
@@ -1079,6 +1079,25 @@
     ...                 # doctest: +NORMALIZE_WHITESPACE
     [0,    1, ...,   18,    19]
 
+The SKIP flag causes an example to be skipped entirely.  I.e., the
+example is not run.  It can be useful in contexts where doctest
+examples serve as both documentation and test cases, and an example
+should be included for documentation purposes, but should not be
+checked (e.g., because its output is random, or depends on resources
+which would be unavailable.)  The SKIP flag can also be used for
+'commenting out' broken examples.
+
+    >>> import unavailable_resource           # doctest: +SKIP
+    >>> unavailable_resource.do_something()   # doctest: +SKIP
+    >>> unavailable_resource.blow_up()        # doctest: +SKIP
+    Traceback (most recent call last):
+        ...
+    UncheckedBlowUpError:  Nobody checks me.
+
+    >>> import random
+    >>> print random.random() # doctest: +SKIP
+    0.721216923889
+
 The REPORT_UDIFF flag causes failures that involve multi-line expected
 and actual outputs to be displayed using a unified diff:
 

Modified: python/trunk/Misc/NEWS
==============================================================================
--- python/trunk/Misc/NEWS	(original)
+++ python/trunk/Misc/NEWS	Tue Apr 25 05:31:36 2006
@@ -86,6 +86,10 @@
 Library
 -------
 
+- Patch #1475231: ``doctest`` has a new ``SKIP`` option, which causes
+  a doctest to be skipped (the code is not run, and the expected output
+  or exception is ignored).
+
 - Fixed contextlib.nested to cope with exceptions being raised and
   caught inside exit handlers.
 


More information about the Python-checkins mailing list