From 1976d9bf6d5525821e1cb005a05acbf55a340dfa Mon Sep 17 00:00:00 2001 From: R David Murray Date: Mon, 14 Apr 2014 20:28:36 -0400 Subject: [PATCH] #15916: if there are no docstrings, make empty suite, not an error. This makes doctest work like unittest: if the test case is empty, that just means there are zero tests run, it's not an error. The existing behavior was broken, since it only gave an error if there were *no* docstrings, and zero tests run if there were docstrings but none of them contained tests. So this makes it self-consistent as well. Patch by Glenn Jones. --- Doc/library/doctest.rst | 12 +++--------- Doc/whatsnew/3.5.rst | 4 ++++ Lib/doctest.py | 9 --------- Lib/test/test_doctest.py | 33 ++++++++++++++++++--------------- Misc/ACKS | 1 + Misc/NEWS | 3 +++ 6 files changed, 29 insertions(+), 33 deletions(-) diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index 50626e9b0c..fb63fde3e4 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -1058,15 +1058,9 @@ from text files and modules with doctests: This function uses the same search technique as :func:`testmod`. - .. note:: - Unlike :func:`testmod` and :class:`DocTestFinder`, this function raises - a :exc:`ValueError` if *module* contains no docstrings. You can prevent - this error by passing a :class:`DocTestFinder` instance as the - *test_finder* argument with its *exclude_empty* keyword argument set - to ``False``:: - - >>> finder = doctest.DocTestFinder(exclude_empty=False) - >>> suite = doctest.DocTestSuite(test_finder=finder) + .. versionchanged:: 3.5 + :func:`DocTestSuite` returns an empty :class:`unittest.TestSuite` if *module* + contains no docstrings instead of raising :exc:`ValueError`. Under the covers, :func:`DocTestSuite` creates a :class:`unittest.TestSuite` out diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst index 7050e0ad16..b9ad68411b 100644 --- a/Doc/whatsnew/3.5.rst +++ b/Doc/whatsnew/3.5.rst @@ -154,6 +154,10 @@ Improved Modules applications where startup time is paramount (contributed by Brett Cannon in :issue:`17621`). +* :func:`doctest.DocTestSuite` returns an empty :class:`unittest.TestSuite` if + *module* contains no docstrings instead of raising :exc:`ValueError` + (contributed by Glenn Jones in :issue:`15916`). + Optimizations ============= diff --git a/Lib/doctest.py b/Lib/doctest.py index d212ad6be1..be824f45d8 100644 --- a/Lib/doctest.py +++ b/Lib/doctest.py @@ -2376,15 +2376,6 @@ def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None, suite = _DocTestSuite() suite.addTest(SkipDocTestCase(module)) return suite - elif not tests: - # Why do we want to do this? Because it reveals a bug that might - # otherwise be hidden. - # It is probably a bug that this exception is not also raised if the - # number of doctest examples in tests is zero (i.e. if no doctest - # examples were found). However, we should probably not be raising - # an exception at all here, though it is too late to make this change - # for a maintenance release. See also issue #14649. - raise ValueError(module, "has no docstrings") tests.sort() suite = _DocTestSuite() diff --git a/Lib/test/test_doctest.py b/Lib/test/test_doctest.py index a1029eda3f..5eb84747f8 100644 --- a/Lib/test/test_doctest.py +++ b/Lib/test/test_doctest.py @@ -2096,22 +2096,9 @@ def test_DocTestSuite(): >>> suite.run(unittest.TestResult()) - However, if DocTestSuite finds no docstrings, it raises an error: + The module need not contain any docstrings either: - >>> try: - ... doctest.DocTestSuite('test.sample_doctest_no_docstrings') - ... except ValueError as e: - ... error = e - - >>> print(error.args[1]) - has no docstrings - - You can prevent this error by passing a DocTestFinder instance with - the `exclude_empty` keyword argument set to False: - - >>> finder = doctest.DocTestFinder(exclude_empty=False) - >>> suite = doctest.DocTestSuite('test.sample_doctest_no_docstrings', - ... test_finder=finder) + >>> suite = doctest.DocTestSuite('test.sample_doctest_no_docstrings') >>> suite.run(unittest.TestResult()) @@ -2121,6 +2108,22 @@ def test_DocTestSuite(): >>> suite.run(unittest.TestResult()) + We can also provide a DocTestFinder: + + >>> finder = doctest.DocTestFinder() + >>> suite = doctest.DocTestSuite('test.sample_doctest', + ... test_finder=finder) + >>> suite.run(unittest.TestResult()) + + + The DocTestFinder need not return any tests: + + >>> finder = doctest.DocTestFinder() + >>> suite = doctest.DocTestSuite('test.sample_doctest_no_docstrings', + ... test_finder=finder) + >>> suite.run(unittest.TestResult()) + + We can supply global variables. If we pass globs, they will be used instead of the module globals. Here we'll pass an empty globals, triggering an extra error: diff --git a/Misc/ACKS b/Misc/ACKS index d3866fd6a2..4767ddee99 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -630,6 +630,7 @@ Thomas Jollans Nicolas Joly Brian K. Jones Evan Jones +Glenn Jones Jeremy Jones Richard Jones Irmen de Jong diff --git a/Misc/NEWS b/Misc/NEWS index b86cc7ffdd..b3020931eb 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -203,6 +203,9 @@ Library - Issue #20334: inspect.Signature and inspect.Parameter are now hashable. +- Issue #15916: doctest.DocTestSuite returns an empty unittest.TestSuite instead + of raising ValueError if it finds no tests + IDLE ---- -- 2.50.1