Patch #1475231: add a new SKIP doctest option, thanks to
Edward Loper.
diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex
index 7c4cb41..4c4f228 100644
--- a/Doc/lib/libdoctest.tex
+++ b/Doc/lib/libdoctest.tex
@@ -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
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:
diff --git a/Misc/NEWS b/Misc/NEWS
index d972b5a..d8fa987 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -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.