Merged revisions 72506,72525-72526,72551,72558,72616,72654-72655,72689,72745,72750,72802,72812,72822,72824,72826-72827,72833,72876,72890,72923,72946,73026,73042,73045,73047,73065,73068-73069 via svnmerge from

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

........
  r72506 | vinay.sajip | 2009-05-09 07:07:17 -0500 (Sat, 09 May 2009) | 1 line

  Issue #5971: StreamHandler.handleError now swallows IOErrors which occur when trying to print a traceback.
........
  r72525 | benjamin.peterson | 2009-05-09 20:38:02 -0500 (Sat, 09 May 2009) | 1 line

  close file explicitly
........
  r72526 | benjamin.peterson | 2009-05-09 21:29:00 -0500 (Sat, 09 May 2009) | 1 line

  make sure files are closed using the with statement
........
  r72551 | benjamin.peterson | 2009-05-10 09:16:47 -0500 (Sun, 10 May 2009) | 1 line

  use isinstance
........
  r72558 | benjamin.peterson | 2009-05-10 18:52:09 -0500 (Sun, 10 May 2009) | 1 line

  sys.setdefaultencoding() strikes me as a bad example
........
  r72616 | benjamin.peterson | 2009-05-13 19:33:10 -0500 (Wed, 13 May 2009) | 1 line

  importlib.import_module is better these days
........
  r72654 | benjamin.peterson | 2009-05-14 17:37:49 -0500 (Thu, 14 May 2009) | 1 line

  prevent refleaks from threads
........
  r72655 | benjamin.peterson | 2009-05-14 17:40:34 -0500 (Thu, 14 May 2009) | 1 line

  a useful decorator for cleaning up threads
........
  r72689 | benjamin.peterson | 2009-05-16 13:44:34 -0500 (Sat, 16 May 2009) | 1 line

  use skipTest()
........
  r72745 | benjamin.peterson | 2009-05-17 09:16:29 -0500 (Sun, 17 May 2009) | 1 line

  ignore .rst files in sphinx its self
........
  r72750 | benjamin.peterson | 2009-05-17 11:59:27 -0500 (Sun, 17 May 2009) | 1 line

  chop off slash
........
  r72802 | georg.brandl | 2009-05-20 13:35:27 -0500 (Wed, 20 May 2009) | 1 line

  #6051: refer to email examples for better way to construct email messages.
........
  r72812 | michael.foord | 2009-05-21 17:57:02 -0500 (Thu, 21 May 2009) | 1 line

  Rename TestCase._result to _resultForDoCleanups to avoid potential clashes in TestCase subclasses. Issue 6072.
........
  r72822 | georg.brandl | 2009-05-22 04:33:25 -0500 (Fri, 22 May 2009) | 1 line

  #6084: fix example.
........
  r72824 | georg.brandl | 2009-05-22 04:43:17 -0500 (Fri, 22 May 2009) | 1 line

  Fix references to file-related functions and methods (os.* vs file.*).
........
  r72826 | georg.brandl | 2009-05-22 04:49:42 -0500 (Fri, 22 May 2009) | 1 line

  Fix confusing wording.
........
  r72827 | georg.brandl | 2009-05-22 04:50:30 -0500 (Fri, 22 May 2009) | 1 line

  s/use/call/
........
  r72833 | georg.brandl | 2009-05-22 12:00:17 -0500 (Fri, 22 May 2009) | 1 line

  #6078: _warnings is a builtin module and has no standard init_warnings function.
........
  r72876 | benjamin.peterson | 2009-05-23 15:59:09 -0500 (Sat, 23 May 2009) | 1 line

  remove mention of old ctypes version
........
  r72890 | gregory.p.smith | 2009-05-24 13:00:13 -0500 (Sun, 24 May 2009) | 2 lines

  add a versionadded tag for set_tunnel
........
  r72923 | michael.foord | 2009-05-25 15:36:56 -0500 (Mon, 25 May 2009) | 1 line

  Make assertSequenceEqual error messages less cryptic, particularly for nested sequences.
........
  r72946 | ronald.oussoren | 2009-05-26 13:44:48 -0500 (Tue, 26 May 2009) | 2 lines

  Fixes issue 6110
........
  r73026 | r.david.murray | 2009-05-29 14:30:27 -0500 (Fri, 29 May 2009) | 3 lines

  Issue 6141: document that the first item of args is still the
  command name even when executable is specified.
........
  r73042 | benjamin.peterson | 2009-05-29 22:10:52 -0500 (Fri, 29 May 2009) | 1 line

  no fdatasync on macos
........
  r73045 | georg.brandl | 2009-05-30 02:26:04 -0500 (Sat, 30 May 2009) | 1 line

  #6146: fix markup bug.
........
  r73047 | georg.brandl | 2009-05-30 05:33:23 -0500 (Sat, 30 May 2009) | 1 line

  Fix some more small markup problems.
........
  r73065 | antoine.pitrou | 2009-05-30 16:39:25 -0500 (Sat, 30 May 2009) | 3 lines

  The test for #5330 wasn't correct.
........
  r73068 | antoine.pitrou | 2009-05-30 16:45:40 -0500 (Sat, 30 May 2009) | 3 lines

  Update ACKS
........
  r73069 | benjamin.peterson | 2009-05-30 19:42:42 -0500 (Sat, 30 May 2009) | 1 line

  fix signature
........

13 files changed, 50 insertions, 37 deletions

diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst
index a75e450..6ad4f7b 100644
--- a/Doc/c-api/buffer.rst
+++ b/Doc/c-api/buffer.rst
@@ -137,7 +137,7 @@ Buffer related functions
    Return 1 if *obj* supports the buffer interface otherwise 0.
 
 
-.. cfunction:: int PyObject_GetBuffer(PyObject *obj, PyObject *view, int flags)
+.. cfunction:: int PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)
 
       Export *obj* into a :ctype:`Py_buffer`, *view*.  These arguments must
       never be *NULL*.  The *flags* argument is a bit field indicating what
diff --git a/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst
index 6be9810..d863177 100644
--- a/Doc/c-api/sequence.rst
+++ b/Doc/c-api/sequence.rst
@@ -50,7 +50,7 @@ Sequence Protocol
 
 .. cfunction:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)
 
-   Return the *i*th element of *o*, or *NULL* on failure. This is the equivalent of
+   Return the *i*\ th element of *o*, or *NULL* on failure. This is the equivalent of
    the Python expression ``o[i]``.
 
 
@@ -62,14 +62,14 @@ Sequence Protocol
 
 .. cfunction:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)
 
-   Assign object *v* to the *i*th element of *o*.  Returns ``-1`` on failure.  This
+   Assign object *v* to the *i*\ th element of *o*.  Returns ``-1`` on failure.  This
    is the equivalent of the Python statement ``o[i] = v``.  This function *does
    not* steal a reference to *v*.
 
 
 .. cfunction:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)
 
-   Delete the *i*th element of object *o*.  Returns ``-1`` on failure.  This is the
+   Delete the *i*\ th element of object *o*.  Returns ``-1`` on failure.  This is the
    equivalent of the Python statement ``del o[i]``.
 
 
@@ -131,7 +131,7 @@ Sequence Protocol
 
 .. cfunction:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)
 
-   Return the *i*th element of *o*, assuming that *o* was returned by
+   Return the *i*\ th element of *o*, assuming that *o* was returned by
    :cfunc:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.
 
 
@@ -147,7 +147,7 @@ Sequence Protocol
 
 .. cfunction:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)
 
-   Return the *i*th element of *o* or *NULL* on failure. Macro form of
+   Return the *i*\ th element of *o* or *NULL* on failure. Macro form of
    :cfunc:`PySequence_GetItem` but without checking that
    :cfunc:`PySequence_Check(o)` is true and without adjustment for negative
    indices.
diff --git a/Doc/conf.py b/Doc/conf.py
index 551452b..352c15f 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -46,6 +46,9 @@ unused_docs = [
     'library/xml.etree',
 ]
 
+# Ignore .rst in Sphinx its self.
+exclude_trees = ['tools/sphinx']
+
 # Relative filename of the reference count data file.
 refcount_file = 'data/refcounts.dat'
 
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index ba80478..039289a 100644
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -1207,8 +1207,7 @@ constructs a new Python object each time!
 Variable-sized data types
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-``ctypes`` provides some support for variable-sized arrays and structures (this
-was added in version 0.9.9.7).
+``ctypes`` provides some support for variable-sized arrays and structures.
 
 The ``resize`` function can be used to resize the memory buffer of an existing
 ctypes object.  The function takes the object as first argument, and the
diff --git a/Doc/library/email-examples.rst b/Doc/library/email-examples.rst
index f606f9b..c1b16da 100644
--- a/Doc/library/email-examples.rst
+++ b/Doc/library/email-examples.rst
@@ -1,3 +1,5 @@
+.. _email-examples:
+
 :mod:`email`: Examples
 ----------------------
 
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 7d8e1b3..43fa9b0 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -73,9 +73,9 @@ The following exceptions are only used as base classes for other exceptions.
 
 .. exception:: LookupError
 
-   The base class for the exceptions that are raised when a key or index used on a
-   mapping or sequence is invalid: :exc:`IndexError`, :exc:`KeyError`.  This can be
-   raised directly by :func:`sys.setdefaultencoding`.
+   The base class for the exceptions that are raised when a key or index used on
+   a mapping or sequence is invalid: :exc:`IndexError`, :exc:`KeyError`.  This
+   can be raised directly by :func:`codecs.lookup`.
 
 
 .. exception:: EnvironmentError
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index f0c7195..732dfa2 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1209,7 +1209,7 @@ are always available.  They are listed here in alphabetical order.
       >>> list(zipped)
       [(1, 4), (2, 5), (3, 6)]
       >>> x2, y2 = zip(*zip(x, y))
-      >>> x == x2, y == y2
+      >>> x == list(x2) and y == list(y2)
       True
 
 
@@ -1272,7 +1272,7 @@ are always available.  They are listed here in alphabetical order.
    names.
 
    If you simply want to import a module (potentially within a package) by name,
-   you can get it from :data:`sys.modules`::
+   you can call :func:`__import__` and then look it up in :data:`sys.modules`::
 
       >>> import sys
       >>> name = 'foo.bar.baz'
diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst
index 8362948..3632242 100644
--- a/Doc/library/http.client.rst
+++ b/Doc/library/http.client.rst
@@ -384,6 +384,8 @@ HTTPConnection Objects
    Set the debugging level (the amount of debugging output printed). The default
    debug level is ``0``, meaning no debugging output is printed.
 
+   .. versionadded:: 2.7
+
 
 .. method:: HTTPConnection.connect()
 
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 2213740..9bb2fc6 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -386,9 +386,9 @@ by file descriptors.
    .. note::
 
       This function is intended for low-level I/O and must be applied to a file
-      descriptor as returned by :func:`open` or :func:`pipe`.  To close a "file
+      descriptor as returned by :func:`os.open` or :func:`pipe`.  To close a "file
       object" returned by the built-in function :func:`open` or by :func:`popen` or
-      :func:`fdopen`, use its :meth:`close` method.
+      :func:`fdopen`, use its :meth:`~file.close` method.
 
 
 .. function:: closerange(fd_low, fd_high)
@@ -439,6 +439,9 @@ by file descriptors.
    Force write of file with filedescriptor *fd* to disk. Does not force update of
    metadata. Availability: Unix.
 
+   .. note::
+      This function is not available on MacOS.
+
 
 .. function:: fpathconf(fd, name)
 
@@ -514,8 +517,8 @@ by file descriptors.
    .. note::
 
       This function is intended for low-level I/O.  For normal usage, use the built-in
-      function :func:`open`, which returns a "file object" with :meth:`read` and
-      :meth:`write` methods (and many more).  To wrap a file descriptor in a "file
+      function :func:`open`, which returns a "file object" with :meth:`~file.read` and
+      :meth:`~file.write` methods (and many more).  To wrap a file descriptor in a "file
       object", use :func:`fdopen`.
 
 
@@ -544,22 +547,22 @@ by file descriptors.
    .. note::
 
       This function is intended for low-level I/O and must be applied to a file
-      descriptor as returned by :func:`open` or :func:`pipe`.  To read a "file object"
+      descriptor as returned by :func:`os.open` or :func:`pipe`.  To read a "file object"
       returned by the built-in function :func:`open` or by :func:`popen` or
-      :func:`fdopen`, or :data:`sys.stdin`, use its :meth:`read` or :meth:`readline`
-      methods.
+      :func:`fdopen`, or :data:`sys.stdin`, use its :meth:`~file.read` or
+      :meth:`~file.readline` methods.
 
 
 .. function:: tcgetpgrp(fd)
 
    Return the process group associated with the terminal given by *fd* (an open
-   file descriptor as returned by :func:`open`). Availability: Unix.
+   file descriptor as returned by :func:`os.open`). Availability: Unix.
 
 
 .. function:: tcsetpgrp(fd, pg)
 
    Set the process group associated with the terminal given by *fd* (an open file
-   descriptor as returned by :func:`open`) to *pg*. Availability: Unix.
+   descriptor as returned by :func:`os.open`) to *pg*. Availability: Unix.
 
 
 .. function:: ttyname(fd)
@@ -577,13 +580,13 @@ by file descriptors.
    .. note::
 
       This function is intended for low-level I/O and must be applied to a file
-      descriptor as returned by :func:`open` or :func:`pipe`.  To write a "file
+      descriptor as returned by :func:`os.open` or :func:`pipe`.  To write a "file
       object" returned by the built-in function :func:`open` or by :func:`popen` or
-      :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its :meth:`write`
-      method.
+      :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
+      :meth:`~file.write` method.
 
 The following constants are options for the *flags* parameter to the
-:func:`open` function.  They can be combined using the bitwise OR operator
+:func:`~os.open` function.  They can be combined using the bitwise OR operator
 ``|``.  Some of them are not available on all platforms.  For descriptions of
 their availability and use, consult the :manpage:`open(2)` manual page on Unix
 or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>` on Windows.
@@ -660,7 +663,7 @@ Files and Directories
    .. note::
 
       Using :func:`access` to check if a user is authorized to e.g. open a file before
-      actually doing so using :func:`open` creates a  security hole, because the user
+      actually doing so using :func:`open` creates a security hole, because the user
       might exploit the short time interval  between checking and opening the file to
       manipulate it.
 
diff --git a/Doc/library/rlcompleter.rst b/Doc/library/rlcompleter.rst
index 293160a..6b3befc 100644
--- a/Doc/library/rlcompleter.rst
+++ b/Doc/library/rlcompleter.rst
@@ -52,7 +52,7 @@ Completer objects have the following method:
 
 .. method:: Completer.complete(text, state)
 
-   Return the *state*th completion for *text*.
+   Return the *state*\ th completion for *text*.
 
    If called for *text* that doesn't include a period character (``'.'``), it will
    complete from names currently defined in :mod:`__main__`, :mod:`builtins` and
diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst
index 5363120..070220e 100644
--- a/Doc/library/smtplib.rst
+++ b/Doc/library/smtplib.rst
@@ -364,3 +364,8 @@ example doesn't do any processing of the :rfc:`822` headers.  In particular, the
    server.sendmail(fromaddr, toaddrs, msg)
    server.quit()
 
+.. note::
+
+   In general, you will want to use the :mod:`email` package's features to
+   construct an email message, which you can then convert to a string and send
+   via :meth:`sendmail`; see :ref:`email-examples`.
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index 9853e62..3318d43 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -34,9 +34,12 @@ This module defines one class called :class:`Popen`:
    Arguments are:
 
    *args* should be a string, or a sequence of program arguments.  The program
-   to execute is normally the first item in the args sequence or the string if a
-   string is given, but can be explicitly set by using the *executable*
-   argument.
+   to execute is normally the first item in the args sequence or the string if
+   a string is given, but can be explicitly set by using the *executable*
+   argument.  When *executable* is given, the first item in the args sequence
+   is still treated by most programs as the command name, which can then be
+   different from the actual executable name.  On Unix, it becomes the display
+   name for the executing program in utilities such as :program:`ps`.
 
    On Unix, with *shell=False* (default): In this case, the Popen class uses
    :meth:`os.execvp` to execute the child program. *args* should normally be a
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index dc8d2cf..ced3398 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -815,12 +815,8 @@ then you will end up importing ``pkg.mod``. If you execute ``from ..subpkg2
 imprt mod`` from within ``pkg.subpkg1`` you will import ``pkg.subpkg2.mod``.
 The specification for relative imports is contained within :pep:`328`.
 
-
-.. index:: builtin: __import__
-
-The built-in function :func:`__import__` is provided to support applications
-that determine which modules need to be loaded dynamically; refer to
-:ref:`built-in-funcs` for additional information.
+:func:`importlib.import_module` is provided to support applications that
+determine which modules need to be loaded dynamically.
 
 
 .. _future: