Merge in r66135. Doing also required removing a stale DeprecationWarning along

with moving warnings.catch_warnings() over to keyword-only parameters for its
constructor (as documented in the 2.6 docs).

1 files changed, 49 insertions, 0 deletions

diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
index 27acc71..ccd7b44 100644
--- a/Doc/library/warnings.rst
+++ b/Doc/library/warnings.rst
@@ -247,3 +247,52 @@ Available Functions
    :func:`filterwarnings`, including that of the :option:`-W` command line options
    and calls to :func:`simplefilter`.
 
+
+Available Classes
+-----------------
+
+.. class:: catch_warnings([\*, record=False, module=None])
+
+    A context manager that guards the warnings filter from being permanentally
+    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"
+
+        # 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.
+
+    .. versionadded:: 2.6
+
+    .. versionchanged:: 3.0
+
+       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