Patch #1475231: add a new SKIP doctest option, thanks to
Edward Loper.
diff --git a/Lib/doctest.py b/Lib/doctest.py
index 70c355a..900d871 100644
--- a/Lib/doctest.py
+++ b/Lib/doctest.py
@@ -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
diff --git a/Lib/test/test_doctest.py b/Lib/test/test_doctest.py
index b17607d..d39aa42 100644
--- a/Lib/test/test_doctest.py
+++ b/Lib/test/test_doctest.py
@@ -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: