[Python-checkins] cpython: #15916: if there are no docstrings, make empty suite, not an error.

[r.david.murray]

http://hg.python.org/cpython/rev/57fb5441a4aa
changeset:   90309:57fb5441a4aa
parent:      90305:14e874736d3a
user:        R David Murray <rdmurray at bitdance.com>
date:        Mon Apr 14 20:28:36 2014 -0400
summary:
  #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.

files:
  Doc/library/doctest.rst  |  12 ++-------
  Doc/whatsnew/3.5.rst     |   4 +++
  Lib/doctest.py           |   9 -------
  Lib/test/test_doctest.py |  35 +++++++++++++++------------
  Misc/ACKS                |   1 +
  Misc/NEWS                |   3 ++
  6 files changed, 30 insertions(+), 34 deletions(-)


diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -1058,15 +1058,9 @@
 
    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
--- a/Doc/whatsnew/3.5.rst
+++ b/Doc/whatsnew/3.5.rst
@@ -154,6 +154,10 @@
   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
--- a/Lib/doctest.py
+++ b/Lib/doctest.py
@@ -2376,15 +2376,6 @@
         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
--- a/Lib/test/test_doctest.py
+++ b/Lib/test/test_doctest.py
@@ -2096,22 +2096,9 @@
          >>> suite.run(unittest.TestResult())
          <unittest.result.TestResult run=0 errors=0 failures=0>
 
-       However, if DocTestSuite finds no docstrings, it raises an error:
-
-         >>> 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)
+       The module need not contain any docstrings either:
+
+         >>> 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 @@
          >>> 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
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -630,6 +630,7 @@
 Nicolas Joly
 Brian K. Jones
 Evan Jones
+Glenn Jones
 Jeremy Jones
 Richard Jones
 Irmen de Jong
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -203,6 +203,9 @@
 
 - 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
 ----
 

-- 
Repository URL: http://hg.python.org/cpython