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)
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 @@
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 @@
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 @@
.. method:: EnvironmentVarGuard.unset(envvar)
Temporarily unset the environment variable ``envvar``.
+
+