Merged revisions 66321 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r66321 | brett.cannon | 2008-09-08 17:49:16 -0700 (Mon, 08 Sep 2008) | 7 lines

  warnings.catch_warnings() now returns a list or None instead of the custom
  WarningsRecorder object. This makes the API simpler to use as no special object
  must be learned.

  Closes issue 3781.
  Review by Benjamin Peterson.
........

1 files changed, 73 insertions, 37 deletions

diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
index e3d3b5b..f9d01b2 100644
--- a/Doc/library/warnings.rst
+++ b/Doc/library/warnings.rst
@@ -160,6 +160,67 @@ ImportWarning can also be enabled explicitly in Python code using::
    warnings.simplefilter('default', ImportWarning)
 
 
+.. _warning-suppress:
+
+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::
+
+    import warnings
+
+    def fxn():
+        warnings.warn("deprecated", DeprecationWarning)
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        fxn()
+
+While within the context manager all warnings will simply be ignored. This
+allows you to use known-deprecated code without having to see the warning while
+not suppressing the warning for other code that might not be aware of its use
+of deprecated code.
+
+
+.. _warning-testing:
+
+Testing Warnings
+----------------
+
+To test warnings raised by code, use the :class:`catch_warnings` context
+manager. With it you can temporarily mutate the warnings filter to facilitate
+your testing. For instance, do the following to capture all raised warnings to
+check::
+
+    import warnings
+
+    def fxn():
+        warnings.warn("deprecated", DeprecationWarning)
+
+    with warnings.catch_warnings(record=True) as w:
+        # Cause all warnings to always be triggered.
+        warnings.simplefilter("always")
+        # Trigger a warning.
+        fxn()
+        # Verify some things
+        assert len(w) == 1
+        assert isinstance(w[-1].category, DeprecationWarning)
+        assert "deprecated" in str(w[-1].message)
+
+One can also cause all warnings to be exceptions by using ``error`` instead of
+``always``. One thing to be aware of is that if a warning has already been
+raised because of a ``once``/``default`` rule, then no matter what filters are
+set the warning will not be seen again unless the warnings registry related to
+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.
+
+
 .. _warning-functions:
 
 Available Functions
@@ -248,31 +309,22 @@ Available Functions
    and calls to :func:`simplefilter`.
 
 
-Available Classes
------------------
+Available Context Managers
+--------------------------
 
 .. class:: catch_warnings([\*, record=False, module=None])
 
-    A context manager that guards the warnings filter from being permanently
-    mutated. The manager returns an instance of :class:`WarningsRecorder`. The 
-    *record* argument specifies whether warnings that would typically be
-    handled by :func:`showwarning` should instead be recorded by the
-    :class:`WarningsRecorder` instance. This argument is typically set when
-    testing for expected warnings behavior. The *module* argument may be a
-    module object that is to be used instead of the :mod:`warnings` module.
-    This argument should only be set when testing the :mod:`warnings` module 
-    or some similar use-case.
-
-    Typical usage of the context manager is like so::
-
-        def fxn():
-            warn("fxn is deprecated", DeprecationWarning)
-            return "spam spam bacon spam"
+    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`.
 
-        # The function 'fxn' is known to raise a DeprecationWarning.
-        with catch_warnings() as w:
-            warnings.filterwarning('ignore', 'fxn is deprecated', DeprecationWarning)
-            fxn()  # DeprecationWarning is temporarily suppressed.
+    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`
+    module itself.
 
     .. versionadded:: 2.6
 
@@ -280,19 +332,3 @@ Available Classes
 
        Constructor arguments turned into keyword-only arguments.
 
-
-.. class:: WarningsRecorder()
-
-    A subclass of :class:`list` that stores all warnings passed to
-    :func:`showwarning` when returned by a :class:`catch_warnings` context
-    manager created with its *record* argument set to ``True``. Each recorded
-    warning is represented by an object whose attributes correspond to the
-    arguments to :func:`showwarning`. As a convenience, a
-    :class:`WarningsRecorder` instance has the attributes of the last
-    recorded warning set on the :class:`WarningsRecorder` instance as well.
-
-    .. method:: reset()
-
-        Delete all recorded warnings.
-
-    .. versionadded:: 2.6