Patch #1475231: add a new SKIP doctest option, thanks to

Edward Loper.

Doc/lib/libdoctest.tex

@@ -616,6 +616,20 @@ TypeError: object doesn't support item assignment
 
 \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 @@ can be useful.
     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

Lib/doctest.py

@@ -54,6 +54,7 @@ __all__ = [
     'DONT_ACCEPT_BLANKLINE',
     'NORMALIZE_WHITESPACE',
     'ELLIPSIS',
+    'SKIP',
     'IGNORE_EXCEPTION_DETAIL',
     'COMPARISON_FLAGS',
     'REPORT_UDIFF',
@@ -136,12 +137,14 @@ DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
 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 @@ class DocTestRunner:
                     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 @@ def testmod(m=None, name=None, globs=None, verbose=None, isprivate=None,
         DONT_ACCEPT_BLANKLINE
         NORMALIZE_WHITESPACE
         ELLIPSIS
+        SKIP
         IGNORE_EXCEPTION_DETAIL
         REPORT_UDIFF
         REPORT_CDIFF
@@ -1914,6 +1922,7 @@ def testfile(filename, module_relative=True, name=None, package=None,
         DONT_ACCEPT_BLANKLINE
         NORMALIZE_WHITESPACE
         ELLIPSIS
+        SKIP
         IGNORE_EXCEPTION_DETAIL
         REPORT_UDIFF
         REPORT_CDIFF

Lib/test/test_doctest.py

@@ -1079,6 +1079,25 @@ output to match any substring in the actual output:
     ...                 # 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:
 

Misc/NEWS

@@ -86,6 +86,10 @@ Extension Modules
 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.