Issue #3781: Final cleanup of warnings.catch_warnings and its usage in the test suite. Closes issue w.r.t. 2.6 (R: Brett Cannon)

2 files changed, 45 insertions, 28 deletions

diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index 4c95759..0a2814b 100644
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -291,18 +291,26 @@ The :mod:`test.test_support` module defines the following functions:
    This will run all tests defined in the named module.
 
 
-.. function:: catch_warning(module=warnings, record=True)
+.. function:: check_warnings()
 
-   Return a context manager that guards the warnings filter from being
-   permanently changed and optionally alters the :func:`showwarning`
-   function to record the details of any warnings that are issued in the
-   managed context. Details of the most recent call to :func:`showwarning`
-   are saved directly on the context manager, while details of previous
-   warnings can be retrieved from the ``warnings`` list.
+   A convenience wrapper for ``warnings.catch_warnings()`` that makes
+   it easier to test that a warning was correctly raised with a single
+   assertion. It is approximately equivalent to calling
+   ``warnings.catch_warnings(record=True)``.
+
+   The main difference is that on entry to the context manager, a
+   :class:`WarningRecorder` instance is returned instead of a simple list.
+   The underlying warnings list is available via the recorder object's
+   :attr:`warnings` attribute, while the attributes of the last raised
+   warning are also accessible directly on the object. If no warning has
+   been raised, then the latter attributes will all be :const:`None`.
+
+   A :meth:`reset` method is also provided on the recorder object. This
+   method simply clears the warning list.
 
    The context manager is used like this::
 
-      with catch_warning() as w:
+      with check_warnings() as w:
           warnings.simplefilter("always")
           warnings.warn("foo")
           assert str(w.message) == "foo"
@@ -310,15 +318,8 @@ The :mod:`test.test_support` module defines the following functions:
           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).
+          w.reset()
+          assert len(w.warnings) == 0
 
    .. versionadded:: 2.6
 
@@ -366,4 +367,10 @@ The :mod:`test.test_support` module defines the following classes:
 
    Temporarily unset the environment variable ``envvar``.
 
+.. class:: WarningsRecorder()
+
+   Class used to record warnings for unit tests. See documentation of
+   :func:`check_warnings` above for more details.
+
+   .. versionadded:: 2.6
 
diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
index e9d0182..bb3aa44 100644
--- a/Doc/library/warnings.rst
+++ b/Doc/library/warnings.rst
@@ -163,9 +163,9 @@ ImportWarning can also be enabled explicitly in Python code using::
 Temporarily Suppressing Warnings
 --------------------------------
 
-If you are using code that you know will raise a warning, such some deprecated
-function, but do not want to see the warning, then suppress the warning using
-the :class:`catch_warnings` context manager::
+If you are using code that you know will raise a warning, such as a deprecated
+function, but do not want to see the warning, then it is possible to suppress
+the warning using the :class:`catch_warnings` context manager::
 
     import warnings
 
@@ -216,7 +216,15 @@ the warning has been cleared.
 Once the context manager exits, the warnings filter is restored to its state
 when the context was entered. This prevents tests from changing the warnings
 filter in unexpected ways between tests and leading to indeterminate test
-results.
+results. The :func:`showwarning` function in the module is also restored to
+its original value.
+
+When testing multiple operations that raise the same kind of warning, it
+is important to test them in a manner that confirms each operation is raising
+a new warning (e.g. set warnings to be raised as exceptions and check the
+operations raise exceptions, check that the length of the warning list
+continues to increase after each operation, or else delete the previous
+entries from the warnings list before each new operation).
 
 
 .. _warning-functions:
@@ -330,16 +338,18 @@ Available Context Managers
 
 .. class:: catch_warnings([\*, record=False, module=None])
 
-    A context manager that copies and, upon exit, restores the warnings filter.
-    If the *record* argument is False (the default) the context manager returns
-    :class:`None`. If *record* is true, a list is returned that is populated
-    with objects as seen by a custom :func:`showwarning` function (which also
-    suppresses output to ``sys.stdout``). Each object has attributes with the
-    same names as the arguments to :func:`showwarning`.
+    A context manager that copies and, upon exit, restores the warnings filter
+    and the :func:`showwarning` function.
+    If the *record* argument is :const:`False` (the default) the context manager
+    returns :class:`None` on entry. If *record* is :const:`True`, a list is
+    returned that is progressively populated with objects as seen by a custom
+    :func:`showwarning` function (which also suppresses output to ``sys.stdout``).
+    Each object in the list has attributes with the same names as the arguments to
+    :func:`showwarning`.
 
     The *module* argument takes a module that will be used instead of the
     module returned when you import :mod:`warnings` whose filter will be
-    protected. This arguments exists primarily for testing the :mod:`warnings`
+    protected. This argument exists primarily for testing the :mod:`warnings`
     module itself.
 
     .. note::