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).
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 @@
: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