[Python-checkins] cpython (merge 3.4 -> 3.5): Issue24756: clarify usage of run_docstring_examples()

[ethan.furman]

https://hg.python.org/cpython/rev/767cc99020d2
changeset:   98026:767cc99020d2
branch:      3.5
parent:      98020:ea16232f0d50
parent:      98025:ce595a047bd9
user:        Ethan Furman <ethan at stoneleaf.us>
date:        Thu Sep 17 22:21:36 2015 -0700
summary:
  Issue24756: clarify usage of run_docstring_examples()

files:
  Doc/library/doctest.rst |  30 ++++++++++++++++++++++------
  1 files changed, 23 insertions(+), 7 deletions(-)


diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -914,15 +914,10 @@
    above, except that *globs* defaults to ``m.__dict__``.
 
 
-There's also a function to run the doctests associated with a single object.
-This function is provided for backward compatibility.  There are no plans to
-deprecate it, but it's rarely useful:
-
-
 .. function:: run_docstring_examples(f, globs, verbose=False, name="NoName", compileflags=None, optionflags=0)
 
-   Test examples associated with object *f*; for example, *f* may be a module,
-   function, or class object.
+   Test examples associated with object *f*; for example, *f* may be a string,
+   a module, a function, or a class object.
 
    A shallow copy of dictionary argument *globs* is used for the execution context.
 
@@ -1815,6 +1810,27 @@
 * Define a ``__test__`` dictionary mapping from regression test topics to
   docstrings containing test cases.
 
+When you have placed your tests in a module, the module can itself be the test
+runner.  When a test fails, you can arrange for your test runner to re-run only
+the failing doctest while you debug the problem.  Here is a minimal example of
+such a test runner::
+
+    if __name__ == '__main__':
+        import doctest
+        flags = doctest.REPORT_NDIFF|doctest.FAIL_FAST
+        if len(sys.argv) > 1:
+            name = sys.argv[1]
+            if name in globals():
+                obj = globals()[name]
+            else:
+                obj = __test__[name]
+            doctest.run_docstring_examples(obj, globals(), name=name,
+                                           optionflags=flags)
+        else:
+            fail, total = doctest.testmod(optionflags=flags)
+            print("{} failures out of {} tests".format(fail, total))
+
+
 .. rubric:: Footnotes
 
 .. [#] Examples containing both expected output and an exception are not supported.

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