#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.

diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
index 50626e9b0ceef2c3da501eb99ba2226d7582a3f4..fb63fde3e4420b290c2ac013759f101b87163a96 100644 (file)
--- 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 7050e0ad16e0c4efcb2fd7e27a715491284f984f..b9ad68411b4e9773d2cb2cf1b349f889fee3ec09 100644 (file)
--- 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 d212ad6be1ea97dfdc82cc7bea39b76e43127315..be824f45d8bf6bd5a4bd227eea855b1d53e86d4a 100644 (file)
--- 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 a1029eda3ff7877123d683e1156fab37a403cbd6..5eb84747f8a93499695e44216dc769f7b22cecb0 100644 (file)
--- a/Lib/test/test_doctest.py
+++ b/Lib/test/test_doctest.py
@@ -2096,22 +2096,9 @@ def test_DocTestSuite():
          >>> suite.run(unittest.TestResult())
          <unittest.result.TestResult run=0 errors=0 failures=0>
 
-       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())
          <unittest.result.TestResult run=0 errors=0 failures=0>
 
@@ -2121,6 +2108,22 @@ def test_DocTestSuite():
          >>> suite.run(unittest.TestResult())
          <unittest.result.TestResult run=9 errors=0 failures=4>
 
+       We can also provide a DocTestFinder:
+
+         >>> finder = doctest.DocTestFinder()
+         >>> suite = doctest.DocTestSuite('test.sample_doctest',
+         ...                          test_finder=finder)
+         >>> suite.run(unittest.TestResult())
+         <unittest.result.TestResult run=9 errors=0 failures=4>
+
+       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())
+         <unittest.result.TestResult run=0 errors=0 failures=0>
+
        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 d3866fd6a2705719a938c1422cab5bd409ab6869..4767ddee99c39f12ee2b92dd990f50e73a6d6157 100644 (file)
--- 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 b86cc7ffdd9d6fa14d7f569f1745b0b0896a708a..b3020931eb543b03333f216d5c5980422df137c7 100644 (file)
--- 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
 ----