Make test.test_support.catch_warnings more robust as discussed on python-dev. Also add explicit tests for it to test_warnings. (forward port of r64910 from trunk)

1 files changed, 24 insertions, 8 deletions

diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index fffcd87..d7a9760 100644
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -211,7 +211,7 @@ This module defines the following exceptions:
    Subclass of :exc:`TestSkipped`. Raised when a resource (such as a network
    connection) is not available. Raised by the :func:`requires` function.
 
-The :mod:`test.test_support` module defines the following constants:
+The :mod:`test.support` module defines the following constants:
 
 
 .. data:: verbose
@@ -278,20 +278,34 @@ The :mod:`test.support` module defines the following functions:
    This will run all tests defined in the named module.
 
 
-.. function:: catch_warning(record=True)
+.. function:: catch_warning(module=warnings, record=True)
 
    Return a context manager that guards the warnings filter from being
-   permanently changed and records the data of the last warning that has been
-   issued. The ``record`` argument specifies whether any raised warnings are
-   captured by the object returned by :func:`warnings.catch_warning` or allowed
-   to propagate as normal.
+   permanently changed and optionally alters the :func:`showwarning`
+   function to record the details of any warnings that are issued in the
+   managed context. Attributes of the most recent warning are saved
+   directly on the context manager, while details of previous warnings
+   can be retrieved from the ``warnings`` list.
 
-   The context manager is typically used like this::
+   The context manager is used like this::
 
       with catch_warning() as w:
+          warnings.simplefilter("always")
           warnings.warn("foo")
           assert str(w.message) == "foo"
-
+          warnings.warn("bar")
+          assert str(w.message) == "bar"
+          assert str(w.warnings[0].message) == "foo"
+          assert str(w.warnings[1].message) == "bar"
+
+   By default, the real :mod:`warnings` module is affected - the ability
+   to select a different module is provided for the benefit of the
+   :mod:`warnings` module's  own unit tests.
+   The ``record`` argument specifies whether or not the :func:`showwarning`
+   function is replaced. Note that recording the warnings in this fashion
+   also prevents them from being written to sys.stderr. If set to ``False``,
+   the standard handling of warning messages is left in place (however, the
+   original handling is still restored at the end of the block).
 
 .. function:: captured_stdout()
 
@@ -331,3 +345,5 @@ The :mod:`test.support` module defines the following classes:
 .. method:: EnvironmentVarGuard.unset(envvar)
 
    Temporarily unset the environment variable ``envvar``.
+
+