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
........

10 files changed, 153 insertions, 46 deletions

diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index 1511a257b8..6ae175a8ec 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -40,7 +40,7 @@ The :mod:`functools` module defines the following functions:
 .. function:: total_ordering(cls)
 
    Given a class defining one or more rich comparison ordering methods, this
-   class decorator supplies the rest.  This simplies the effort involved
+   class decorator supplies the rest.  This simplifies the effort involved
    in specifying all of the possible rich comparison operations:
 
    The class must define one of :meth:`__lt__`, :meth:`__le__`,
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 347c72c7b1..6324806678 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -2012,6 +2012,84 @@ supports sending logging messages to a remote or local Unix syslog.
       or integers - if strings are passed, internal mapping dictionaries are
       used to convert them to integers.
 
+      **Priorities**
+
+      +--------------------------+---------------+
+      | Name (string)            | Symbolic value|
+      +==========================+===============+
+      | ``alert``                | LOG_ALERT     |
+      +--------------------------+---------------+
+      | ``crit`` or ``critical`` | LOG_CRIT      |
+      +--------------------------+---------------+
+      | ``debug``                | LOG_DEBUG     |
+      +--------------------------+---------------+
+      | ``emerg`` or ``panic``   | LOG_EMERG     |
+      +--------------------------+---------------+
+      | ``err`` or ``error``     | LOG_ERR       |
+      +--------------------------+---------------+
+      | ``info``                 | LOG_INFO      |
+      +--------------------------+---------------+
+      | ``notice``               | LOG_NOTICE    |
+      +--------------------------+---------------+
+      | ``warn`` or ``warning``  | LOG_WARNING   |
+      +--------------------------+---------------+
+
+      **Facilities**
+
+      +---------------+---------------+
+      | Name (string) | Symbolic value|
+      +===============+===============+
+      | ``auth``      | LOG_AUTH      |
+      +---------------+---------------+
+      | ``authpriv``  | LOG_AUTHPRIV  |
+      +---------------+---------------+
+      | ``cron``      | LOG_CRON      |
+      +---------------+---------------+
+      | ``daemon``    | LOG_DAEMON    |
+      +---------------+---------------+
+      | ``ftp``       | LOG_FTP       |
+      +---------------+---------------+
+      | ``kern``      | LOG_KERN      |
+      +---------------+---------------+
+      | ``lpr``       | LOG_LPR       |
+      +---------------+---------------+
+      | ``mail``      | LOG_MAIL      |
+      +---------------+---------------+
+      | ``news``      | LOG_NEWS      |
+      +---------------+---------------+
+      | ``syslog``    | LOG_SYSLOG    |
+      +---------------+---------------+
+      | ``user``      | LOG_USER      |
+      +---------------+---------------+
+      | ``uucp``      | LOG_UUCP      |
+      +---------------+---------------+
+      | ``local0``    | LOG_LOCAL0    |
+      +---------------+---------------+
+      | ``local1``    | LOG_LOCAL1    |
+      +---------------+---------------+
+      | ``local2``    | LOG_LOCAL2    |
+      +---------------+---------------+
+      | ``local3``    | LOG_LOCAL3    |
+      +---------------+---------------+
+      | ``local4``    | LOG_LOCAL4    |
+      +---------------+---------------+
+      | ``local5``    | LOG_LOCAL5    |
+      +---------------+---------------+
+      | ``local6``    | LOG_LOCAL6    |
+      +---------------+---------------+
+      | ``local7``    | LOG_LOCAL7    |
+      +---------------+---------------+
+
+   .. method:: mapPriority(levelname)
+
+      Maps a logging level name to a syslog priority name.
+      You may need to override this if you are using custom levels, or
+      if the default algorithm is not suitable for your needs. The
+      default algorithm maps ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR`` and
+      ``CRITICAL`` to the equivalent syslog names, and all other level
+      names to "warning".
+
+.. _nt-eventlog-handler:
 
 NTEventLogHandler
 ^^^^^^^^^^^^^^^^^
diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index 09bccbc3a0..9c3bd03698 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -345,9 +345,9 @@ Constants
    :exc:`ValueError` for invalid operations like ``sqrt(-1.0)`` or ``log(0.0)``
    (where C99 Annex F recommends signaling invalid operation or divide-by-zero),
    and :exc:`OverflowError` for results that overflow (for example,
-   ``exp(1000.0)``).  A *NaN* will not be returned from any of the functions
-   above unless one or more of the input arguments was a *NaN*; in that case,
-   most functions will return a *NaN*, but (again following C99 Annex F) there
+   ``exp(1000.0)``).  A NaN will not be returned from any of the functions
+   above unless one or more of the input arguments was a NaN; in that case,
+   most functions will return a NaN, but (again following C99 Annex F) there
    are some exceptions to this rule, for example ``pow(float('nan'), 0.0)`` or
    ``hypot(float('nan'), float('inf'))``.
 
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 05471549bb..dacf87afd7 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -437,6 +437,10 @@ process will then be assigned 3, 4, 5, and so forth.  The name "file descriptor"
 is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
 by file descriptors.
 
+The :meth:`~file.fileno` method can be used to obtain the file descriptor
+associated with a file object when required.  Note that using the file
+descriptor directly will bypass the file object methods, ignoring aspects such
+as internal buffering of data.
 
 .. function:: close(fd)
 
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index 0fee6d5cdb..e73aefb139 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -622,9 +622,9 @@ correspond to Unix system calls applicable to sockets.
 
    Receive up to *nbytes* bytes from the socket, storing the data into a buffer
    rather than creating a new bytestring.  If *nbytes* is not specified (or 0),
-   receive up to the size available in the given buffer. See the Unix manual page
-   :manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults
-   to zero.
+   receive up to the size available in the given buffer.  Returns the number of
+   bytes received.  See the Unix manual page :manpage:`recv(2)` for the meaning
+   of the optional argument *flags*; it defaults to zero.
 
 
 .. method:: socket.send(bytes[, flags])
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 70eeca3895..46a481aee2 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -2143,12 +2143,12 @@ An example of dictionary view usage::
 
 .. _typememoryview:
 
-memoryview Types
-================
+memoryview type
+===============
 
-:class:`memoryview`\s allow Python code to access the internal data of an object
-that supports the buffer protocol without copying.  Memory can be interpreted as
-simple bytes or complex data structures.
+:class:`memoryview` objects allow Python code to access the internal data
+of an object that supports the buffer protocol without copying.  Memory
+is generally interpreted as simple bytes.
 
 .. class:: memoryview(obj)
 
diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst
index 8b53b57824..50a5148606 100644
--- a/Doc/library/tarfile.rst
+++ b/Doc/library/tarfile.rst
@@ -212,7 +212,7 @@ object, see :ref:`tarinfo-objects` for details.
 A :class:`TarFile` object can be used as a context manager in a :keyword:`with`
 statement. It will automatically be closed when the block is completed. Please
 note that in the event of an exception an archive opened for writing will not
-be finalized, only the internally used file object will be closed. See the
+be finalized; only the internally used file object will be closed. See the
 :ref:`tar-examples` section for a use case.
 
 .. versionadded:: 3.2
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()
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index 5ed75d5a87..9bd85d52da 100644
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -661,6 +661,8 @@ Test cases
       Calling this during the a test method or :meth:`setUp` skips the current
       test.  See :ref:`unittest-skipping` for more information.
 
+      .. versionadded:: 2.7
+
 
    .. method:: debug()
 
diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
index 36d47ad12a..67d93fab5c 100644
--- a/Doc/library/warnings.rst
+++ b/Doc/library/warnings.rst
@@ -180,7 +180,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:
@@ -218,7 +221,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
@@ -337,3 +342,11 @@ Available Context Managers
     module returned when you import :mod:`warnings` whose filter will be
     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.