Merged revisions 79307,79408,79430,79533,79542,79579-79580,79585-79587,79607-79608,79622,79717,79820,79822,79828,79862,79875,79923-79924,79941-79943,79945,79947,79951-79952 via svnmerge from

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

........
  r79307 | florent.xicluna | 2010-03-22 17:45:50 -0500 (Mon, 22 Mar 2010) | 2 lines

  #7667: Fix doctest failures with non-ASCII paths.
........
  r79408 | victor.stinner | 2010-03-24 20:18:38 -0500 (Wed, 24 Mar 2010) | 2 lines

  Fix a gcc warning introduced by r79397.
........
  r79430 | brian.curtin | 2010-03-25 18:48:54 -0500 (Thu, 25 Mar 2010) | 2 lines

  Fix #6538. Markup RegexObject and MatchObject as classes. Patch by Ryan Arana.
........
  r79533 | barry.warsaw | 2010-03-31 16:07:16 -0500 (Wed, 31 Mar 2010) | 6 lines

  - Issue #8233: When run as a script, py_compile.py optionally takes a single
    argument `-` which tells it to read files to compile from stdin.  Each line
    is read on demand and the named file is compiled immediately.  (Original
    patch by Piotr O?\197?\188arowski).
........
  r79542 | r.david.murray | 2010-03-31 20:28:39 -0500 (Wed, 31 Mar 2010) | 3 lines

  A couple small grammar fixes in test.rst, and rewrite the
  check_warnings docs to be clearer.
........
  r79579 | georg.brandl | 2010-04-02 03:34:41 -0500 (Fri, 02 Apr 2010) | 1 line

  Add 2.6.5.
........
  r79580 | georg.brandl | 2010-04-02 03:39:09 -0500 (Fri, 02 Apr 2010) | 1 line

  #2768: add a note on how to get a file descriptor.
........
  r79585 | georg.brandl | 2010-04-02 04:03:18 -0500 (Fri, 02 Apr 2010) | 1 line

  Remove col-spanning cells in logging docs.
........
  r79586 | georg.brandl | 2010-04-02 04:07:42 -0500 (Fri, 02 Apr 2010) | 1 line

  Document PyImport_ExecCodeModuleEx().
........
  r79587 | georg.brandl | 2010-04-02 04:11:49 -0500 (Fri, 02 Apr 2010) | 1 line

  #8012: clarification in generator glossary entry.
........
  r79607 | andrew.kuchling | 2010-04-02 12:48:23 -0500 (Fri, 02 Apr 2010) | 1 line

  #6647: document that catch_warnings is not thread-safe
........
  r79608 | andrew.kuchling | 2010-04-02 12:54:26 -0500 (Fri, 02 Apr 2010) | 1 line

  #6647: add note to two examples
........
  r79622 | tarek.ziade | 2010-04-02 16:34:19 -0500 (Fri, 02 Apr 2010) | 1 line

  removed documentation on code that was reverted and pushed into distutils2
........
  r79717 | antoine.pitrou | 2010-04-03 16:22:38 -0500 (Sat, 03 Apr 2010) | 4 lines

  Fix wording / typography, and a slightly misleading statement
  (memoryviews don't support complex structures right now)
........
  r79820 | benjamin.peterson | 2010-04-05 22:34:09 -0500 (Mon, 05 Apr 2010) | 1 line

  ready _sre types
........
  r79822 | georg.brandl | 2010-04-06 03:18:15 -0500 (Tue, 06 Apr 2010) | 1 line

  #8320: document return value of recv_into().
........
  r79828 | georg.brandl | 2010-04-06 09:33:44 -0500 (Tue, 06 Apr 2010) | 1 line

  Add JP.
........
  r79862 | georg.brandl | 2010-04-06 15:27:59 -0500 (Tue, 06 Apr 2010) | 1 line

  Fix syntax.
........
  r79875 | mark.dickinson | 2010-04-06 17:18:23 -0500 (Tue, 06 Apr 2010) | 1 line

  More NaN consistency doc fixes.
........
  r79923 | georg.brandl | 2010-04-10 06:15:24 -0500 (Sat, 10 Apr 2010) | 1 line

  #8360: skipTest was added in 2.7.
........
  r79924 | georg.brandl | 2010-04-10 06:16:59 -0500 (Sat, 10 Apr 2010) | 1 line

  #8346: update version.
........
  r79941 | andrew.kuchling | 2010-04-10 20:39:36 -0500 (Sat, 10 Apr 2010) | 1 line

  Two grammar fixes
........
  r79942 | andrew.kuchling | 2010-04-10 20:40:06 -0500 (Sat, 10 Apr 2010) | 1 line

  Punctuation fix
........
  r79943 | andrew.kuchling | 2010-04-10 20:40:30 -0500 (Sat, 10 Apr 2010) | 1 line

  Add various items
........
  r79945 | andrew.kuchling | 2010-04-10 20:40:49 -0500 (Sat, 10 Apr 2010) | 1 line

  name correct
........
  r79947 | andrew.kuchling | 2010-04-10 20:44:13 -0500 (Sat, 10 Apr 2010) | 1 line

  Remove distutils section
........
  r79951 | andrew.kuchling | 2010-04-11 07:48:08 -0500 (Sun, 11 Apr 2010) | 1 line

  Two typo fixes
........
  r79952 | andrew.kuchling | 2010-04-11 07:49:37 -0500 (Sun, 11 Apr 2010) | 1 line

  Add two items
........

1 files changed, 41 insertions, 31 deletions

diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index 9f013f8058..cfd5b10cda 100644
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -221,15 +221,15 @@ The :mod:`test.support` module defines the following constants:
 
 .. data:: TESTFN
 
-   Set to the name that a temporary file could use. Any temporary file that is
-   created should be closed and unlinked (removed).
+   Set to a name that is safe to use as the name of a temporary file.  Any
+   temporary file that is created should be closed and unlinked (removed).
 
 The :mod:`test.support` module defines the following functions:
 
 
 .. function:: forget(module_name)
 
-   Remove the module named *module_name* from ``sys.modules`` and deletes any
+   Remove the module named *module_name* from ``sys.modules`` and delete any
    byte-compiled files of the module.
 
 
@@ -272,49 +272,55 @@ The :mod:`test.support` module defines the following functions:
    This will run all tests defined in the named module.
 
 
-.. function:: check_warnings(*filters, quiet=None)
+.. function:: check_warnings(*filters, quiet=True)
 
-   A convenience wrapper for ``warnings.catch_warnings()`` that makes
-   it easier to test that a warning was correctly raised with a single
-   assertion. It is approximately equivalent to calling
-   ``warnings.catch_warnings(record=True)``.
+   A convenience wrapper for :func:`warnings.catch_warnings()` that makes it
+   easier to test that a warning was correctly raised.  It is approximately
+   equivalent to calling ``warnings.catch_warnings(record=True)`` with
+   :meth:`warnings.simplefilter` set to ``always`` and with the option to
+   automatically validate the results that are recorded.
 
-   It accepts 2-tuples ``("message regexp", WarningCategory)`` as positional
-   arguments. If there's some ``*filters`` defined, or if the optional keyword
-   argument ``quiet`` is :const:`False`, it checks if the warnings are
-   effective. If some filter did not catch any warning, the test fails. If some
-   warnings are not caught, the test fails, too. To disable these checks, set
-   argument ``quiet`` to :const:`True`.
+   ``check_warnings`` accepts 2-tuples of the form ``("message regexp",
+   WarningCategory)`` as positional arguments. If one or more *filters* are
+   provided, or if the optional keyword argument *quiet* is :const:`False`,
+   it checks to make sure the warnings are as expected:  each specified filter
+   must match at least one of the warnings raised by the enclosed code or the
+   test fails, and if any warnings are raised that do not match any of the
+   specified filters the test fails.  To disable the first of these checks,
+   set *quiet* to :const:`True`.
 
-   Without argument, it defaults to::
+   If no arguments are specified, it defaults to::
 
       check_warnings(("", Warning), quiet=True)
 
-   Additionally, on entry to the context manager, a :class:`WarningRecorder`
-   instance is returned. The underlying warnings list is available via the
-   recorder object's :attr:`warnings` attribute, while the attributes of the
-   last raised warning are also accessible directly on the object. If no
-   warning has been raised, then the latter attributes will all be
-   :const:`None`.
+   In this case all warnings are caught and no errors are raised.
 
-   A :meth:`reset` method is also provided on the recorder object. This
-   method simply clears the warnings list.
+   On entry to the context manager, a :class:`WarningRecorder` instance is
+   returned. The underlying warnings list from
+   :func:`~warnings.catch_warnings` is available via the recorder object's
+   :attr:`warnings` attribute.  As a convenience, the attributes of the object
+   representing the most recent warning can also be accessed directly through
+   the recorder object (see example below).  If no warning has been raised,
+   then any of the attributes that would otherwise be expected on an object
+   representing a warning will return :const:`None`.
 
-   The context manager may be used like this::
+   The recorder object also has a :meth:`reset` method, which clears the
+   warnings list.
 
-      import warnings
-
-      with check_warnings(quiet=False):
-          exec('assert(False, "Hey!")')
-          warnings.warn(UserWarning("Hide me!"))
+   The context manager is designed to be used like this::
 
       with check_warnings(("assertion is always true", SyntaxWarning),
                           ("", UserWarning)):
           exec('assert(False, "Hey!")')
           warnings.warn(UserWarning("Hide me!"))
 
+   In this case if either warning was not raised, or some other warning was
+   raised, :func:`check_warnings` would raise an error.
+
+   When a test needs to look more deeply into the warnings, rather than
+   just checking whether or not they occurred, code like this can be used::
+
       with check_warnings(quiet=True) as w:
-          warnings.simplefilter("always")
           warnings.warn("foo")
           assert str(w.args[0]) == "foo"
           warnings.warn("bar")
@@ -324,8 +330,12 @@ The :mod:`test.support` module defines the following functions:
           w.reset()
           assert len(w.warnings) == 0
 
+
+   Here all warnings will be caught, and the test code tests the captured
+   warnings directly.
+
    .. versionchanged:: 3.2
-      New optional attributes ``*filters`` and ``quiet``.
+      New optional arguments *filters* and *quiet*.
 
 
 .. function:: captured_stdout()