Merged revisions 79607-79608 via svnmerge from

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

........
  r79607 | andrew.kuchling | 2010-04-02 19:48:23 +0200 (Fr, 02 Apr 2010) | 1 line

  #6647: document that catch_warnings is not thread-safe
........
  r79608 | andrew.kuchling | 2010-04-02 19:54:26 +0200 (Fr, 02 Apr 2010) | 1 line

  #6647: add note to two examples
........

diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
index 866da5cde0ccb23180161bded8574b725ba7ba1d..86ca5135aa8844a01af274ce7ac44da2f4cd28d5 100644 (file)
--- a/Doc/library/warnings.rst
+++ b/Doc/library/warnings.rst
@@ -178,7 +178,10 @@ the warning using the :class:`catch_warnings` context manager::
 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.
+of deprecated code.  Note: this can only be guaranteed in a single-threaded
+application. If two or more threads use the :class:`catch_warnings` context
+manager at the same time, the behavior is undefined.
+
 
 
 .. _warning-testing:
@@ -216,7 +219,9 @@ 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. The :func:`showwarning` function in the module is also restored to
-its original value.
+its original value.  Note: this can only be guaranteed in a single-threaded
+application. If two or more threads use the :class:`catch_warnings` context
+manager at the same time, the behavior is undefined.
 
 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
@@ -356,6 +361,14 @@ Available Context Managers
     protected. This argument exists primarily for testing the :mod:`warnings`
     module itself.
 
+    .. note::
+
+        The :class:`catch_warnings` manager works by replacing and
+        then later restoring the module's
+        :func:`showwarning` function and internal list of filter
+        specifications.  This means the context manager is modifying
+        global state and therefore is not thread-safe.
+
     .. note::
 
         In Python 3.0, the arguments to the constructor for