diff options
| -rw-r--r-- | Doc/lib/libdoctest.tex | 15 | ||||
| -rw-r--r-- | Lib/doctest.py | 9 | ||||
| -rw-r--r-- | Lib/test/test_doctest.py | 19 | ||||
| -rw-r--r-- | Misc/NEWS | 4 |
4 files changed, 47 insertions, 0 deletions
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 @@ 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 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 @@ __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 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 @@ 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: @@ -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. |