17 files changed, 152 insertions, 72 deletions
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index b2baab5..d79c123 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -371,6 +371,10 @@ Initialization, Finalization, and Threads
    Set the default "home" directory, that is, the location of the standard
    Python libraries.  The libraries are searched in
    :file:`{home}/lib/python{version}` and :file:`{home}/lib/python{version}`.
+   The argument should point to a zero-terminated character string in static
+   storage whose contents will not change for the duration of the program's
+   execution.  No code in the Python interpreter will change the contents of
+   this storage.
 
 
 .. cfunction:: w_char* Py_GetPythonHome()
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index dc48158..4c0d6a4 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -476,10 +476,13 @@ These are the UTF-32 codec APIs:
       *byteorder == 0:  native order
       *byteorder == 1:  big endian
 
-   and then switches if the first four bytes of the input data are a byte order mark
-   (BOM) and the specified byte order is native order.  This BOM is not copied into
-   the resulting Unicode string.  After completion, *\*byteorder* is set to the
-   current byte order at the end of input data.
+   If ``*byteorder`` is zero, and the first four bytes of the input data are a
+   byte order mark (BOM), the decoder switches to this byte order and the BOM is
+   not copied into the resulting Unicode string.  If ``*byteorder`` is ``-1`` or
+   ``1``, any byte order mark is copied to the output.
+
+   After completion, *\*byteorder* is set to the current byte order at the end
+   of input data.
 
    In a narrow build codepoints outside the BMP will be decoded as surrogate pairs.
 
@@ -500,8 +503,7 @@ These are the UTF-32 codec APIs:
 .. cfunction:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
 
    Return a Python bytes object holding the UTF-32 encoded value of the Unicode
-   data in *s*.  If *byteorder* is not ``0``, output is written according to the
-   following byte order::
+   data in *s*.  Output is written according to the following byte order::
 
       byteorder == -1: little endian
       byteorder == 0:  native byte order (writes a BOM mark)
@@ -541,10 +543,14 @@ These are the UTF-16 codec APIs:
       *byteorder == 0:  native order
       *byteorder == 1:  big endian
 
-   and then switches if the first two bytes of the input data are a byte order mark
-   (BOM) and the specified byte order is native order.  This BOM is not copied into
-   the resulting Unicode string.  After completion, *\*byteorder* is set to the
-   current byte order at the end of input data.
+   If ``*byteorder`` is zero, and the first two bytes of the input data are a
+   byte order mark (BOM), the decoder switches to this byte order and the BOM is
+   not copied into the resulting Unicode string.  If ``*byteorder`` is ``-1`` or
+   ``1``, any byte order mark is copied to the output (where it will result in
+   either a ``\ufeff`` or a ``\ufffe`` character).
+
+   After completion, *\*byteorder* is set to the current byte order at the end
+   of input data.
 
    If *byteorder* is *NULL*, the codec starts in native order mode.
 
@@ -563,8 +569,7 @@ These are the UTF-16 codec APIs:
 .. cfunction:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
 
    Return a Python bytes object holding the UTF-16 encoded value of the Unicode
-   data in *s*.  If *byteorder* is not ``0``, output is written according to the
-   following byte order::
+   data in *s*.  Output is written according to the following byte order::
 
       byteorder == -1: little endian
       byteorder == 0:  native byte order (writes a BOM mark)
diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst
index 3577c96..421971a 100644
--- a/Doc/documenting/markup.rst
+++ b/Doc/documenting/markup.rst
@@ -597,8 +597,10 @@ units as well as normal text:
    An important bit of information about an API that a user should be aware of
    when using whatever bit of API the warning pertains to.  The content of the
    directive should be written in complete sentences and include all appropriate
-   punctuation.  This should only be chosen over ``note`` for information
-   regarding the possibility of crashes, data loss, or security implications.
+   punctuation.  In the interest of not scaring users away from pages filled
+   with warnings, this directive should only be chosen over ``note`` for
+   information regarding the possibility of crashes, data loss, or security
+   implications.
 
 .. describe:: versionadded
 
diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index 6e02063..c3e7407 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -986,7 +986,7 @@ particular, the following variants typically exist:
 +-----------------+--------------------------------+--------------------------------+
 | cp1255          | windows-1255                   | Hebrew                         |
 +-----------------+--------------------------------+--------------------------------+
-| cp1256          | windows1256                    | Arabic                         |
+| cp1256          | windows-1256                   | Arabic                         |
 +-----------------+--------------------------------+--------------------------------+
 | cp1257          | windows-1257                   | Baltic languages               |
 +-----------------+--------------------------------+--------------------------------+
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index df04cf3..c1d3113 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -63,6 +63,7 @@ Available Types
 
 
 .. class:: date
+   :noindex:
 
    An idealized naive date, assuming the current Gregorian calendar always was, and
    always will be, in effect. Attributes: :attr:`year`, :attr:`month`, and
@@ -70,6 +71,7 @@ Available Types
 
 
 .. class:: time
+   :noindex:
 
    An idealized time, independent of any particular day, assuming that every day
    has exactly 24\*60\*60 seconds (there is no notion of "leap seconds" here).
@@ -78,6 +80,7 @@ Available Types
 
 
 .. class:: datetime
+   :noindex:
 
    A combination of a date and a time. Attributes: :attr:`year`, :attr:`month`,
    :attr:`day`, :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`,
@@ -85,6 +88,7 @@ Available Types
 
 
 .. class:: timedelta
+   :noindex:
 
    A duration expressing the difference between two :class:`date`, :class:`time`,
    or :class:`datetime` instances to microsecond resolution.
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 9cd2175..465339a 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -600,16 +600,12 @@ are always available.  They are listed here in alphabetical order.
 .. function:: locals()
 
    Update and return a dictionary representing the current local symbol table.
+   Free variables are returned by :func:`locals` when it is called in function
+   blocks, but not in class blocks.
 
    .. note::
-
       The contents of this dictionary should not be modified; changes may not
-      affect the values of local variables used by the interpreter.
-
-   Free variables are returned by :func:`locals` when it is called in a function
-   block.  Modifications of free variables may not affect the values used by the
-   interpreter.  Free variables are not returned in class blocks.
-
+      affect the values of local and free variables used by the interpreter.
 
 .. function:: map(function, iterable, ...)
 
@@ -1172,10 +1168,10 @@ are always available.  They are listed here in alphabetical order.
 
 .. function:: vars([object])
 
-   Without arguments, return a dictionary corresponding to the current local symbol
-   table.  With a module, class or class instance object as argument (or anything
-   else that has a :attr:`__dict__` attribute), returns a dictionary corresponding
-   to the object's symbol table.
+   Without an argument, act like :func:`locals`.
+
+   With a module, class or class instance object as argument (or anything else that
+   has a :attr:`__dict__` attribute), return that attribute.
 
    .. note::
       The returned dictionary should not be modified:
diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst
index f63d957..a776df1 100644
--- a/Doc/library/hashlib.rst
+++ b/Doc/library/hashlib.rst
@@ -86,11 +86,11 @@ The following values are provided as constant attributes of the hash objects
 returned by the constructors:
 
 
-.. data:: digest_size
+.. data:: hash.digest_size
 
    The size of the resulting hash in bytes.
 
-.. data:: block_size
+.. data:: hash.block_size
 
    The internal block size of the hash algorithm in bytes.
 
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index 03bdf3e..ad88e3d 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -508,6 +508,11 @@ line.
 
    Return the frame object for the caller's stack frame.
 
+   This function relies on Python stack frame support in the interpreter, which
+   isn't guaranteed to exist in all implementations of Python. If running in
+   an implementation without Python stack frame support this function returns
+   ``None``.
+
 
 .. function:: stack(context=1)
 
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index bb736af..6ff9b8b 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -57,7 +57,7 @@ default handler so that debug messages are written to a file::
 
    import logging
    LOG_FILENAME = '/tmp/logging_example.out'
-   logging.basicConfig(filename=LOG_FILENAME,level=logging.DEBUG,)
+   logging.basicConfig(filename=LOG_FILENAME,level=logging.DEBUG)
 
    logging.debug('This message should go to the log file')
 
@@ -1447,6 +1447,55 @@ printed on the console; on the server side, you should see something like::
       69 myapp.area2     WARNING  Jail zesty vixen who grabbed pay from quack.
       69 myapp.area2     ERROR    The five boxing wizards jump quickly.
 
+Using arbitrary objects as messages
+-----------------------------------
+
+In the preceding sections and examples, it has been assumed that the message
+passed when logging the event is a string. However, this is not the only
+possibility. You can pass an arbitrary object as a message, and its
+:meth:`__str__` method will be called when the logging system needs to convert
+it to a string representation. In fact, if you want to, you can avoid
+computing a string representation altogether - for example, the
+:class:`SocketHandler` emits an event by pickling it and sending it over the
+wire.
+
+Optimization
+------------
+
+Formatting of message arguments is deferred until it cannot be avoided.
+However, computing the arguments passed to the logging method can also be
+expensive, and you may want to avoid doing it if the logger will just throw
+away your event. To decide what to do, you can call the :meth:`isEnabledFor`
+method which takes a level argument and returns true if the event would be
+created by the Logger for that level of call. You can write code like this::
+
+    if logger.isEnabledFor(logging.DEBUG):
+        logger.debug("Message with %s, %s", expensive_func1(),
+                                            expensive_func2())
+
+so that if the logger's threshold is set above ``DEBUG``, the calls to
+:func:`expensive_func1` and :func:`expensive_func2` are never made.
+
+There are other optimizations which can be made for specific applications which
+need more precise control over what logging information is collected. Here's a
+list of things you can do to avoid processing during logging which you don't
+need:
+
++-----------------------------------------------+----------------------------------------+
+| What you don't want to collect                | How to avoid collecting it             |
++===============================================+========================================+
+| Information about where calls were made from. | Set ``logging._srcfile`` to ``None``.  |
++-----------------------------------------------+----------------------------------------+
+| Threading information.                        | Set ``logging.logThreads`` to ``0``.   |
++-----------------------------------------------+----------------------------------------+
+| Process information.                          | Set ``logging.logProcesses`` to ``0``. |
++-----------------------------------------------+----------------------------------------+
+
+Also note that the core logging module only includes the basic handlers. If
+you don't import :mod:`logging.handlers` and :mod:`logging.config`, they won't
+take up any memory.
+
+.. _handler:
 
 Handler Objects
 ---------------
@@ -1562,9 +1611,9 @@ file-like object (or, more precisely, any object which supports :meth:`write`
 and :meth:`flush` methods).
 
 
-.. class:: StreamHandler(strm=None)
+.. class:: StreamHandler(stream=None)
 
-   Returns a new instance of the :class:`StreamHandler` class. If *strm* is
+   Returns a new instance of the :class:`StreamHandler` class. If *stream* is
    specified, the instance will use it for logging output; otherwise, *sys.stderr*
    will be used.
 
diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst
index 10242fd..e386290 100644
--- a/Doc/library/shelve.rst
+++ b/Doc/library/shelve.rst
@@ -27,27 +27,39 @@ lots of shared  sub-objects.  The keys are ordinary strings.
 
    Because of Python semantics, a shelf cannot know when a mutable
    persistent-dictionary entry is modified.  By default modified objects are
-   written only when assigned to the shelf (see :ref:`shelve-example`).  If
-   the optional *writeback* parameter is set to *True*, all entries accessed
-   are cached in memory, and written back at close time; this can make it
-   handier to mutate mutable entries in the persistent dictionary, but, if
-   many entries are accessed, it can consume vast amounts of memory for the
-   cache, and it can make the close operation very slow since all accessed
-   entries are written back (there is no way to determine which accessed
-   entries are mutable, nor which ones were actually mutated).
+   written only when assigned to the shelf (see :ref:`shelve-example`).  If the
+   optional *writeback* parameter is set to *True*, all entries accessed are
+   cached in memory, and written back on :meth:`sync` and :meth:`close`; this
+   can make it handier to mutate mutable entries in the persistent dictionary,
+   but, if many entries are accessed, it can consume vast amounts of memory for
+   the cache, and it can make the close operation very slow since all accessed
+   entries are written back (there is no way to determine which accessed entries
+   are mutable, nor which ones were actually mutated).
+
+   .. note::
+
+      Do not rely on the shelf being closed automatically; always call
+      :meth:`close` explicitly when you don't need it any more, or use a
+      :keyword:`with` statement with :func:`contextlib.closing`.
+
 
 Shelf objects support all methods supported by dictionaries.  This eases the
 transition from dictionary based scripts to those requiring persistent storage.
 
-One additional method is supported:
-
+Two additional methods are supported:
 
 .. method:: Shelf.sync()
 
-   Write back all entries in the cache if the shelf was opened with *writeback* set
-   to *True*. Also empty the cache and synchronize the persistent dictionary on
-   disk, if feasible.  This is called automatically when the shelf is closed with
-   :meth:`close`.
+   Write back all entries in the cache if the shelf was opened with *writeback*
+   set to :const:`True`.  Also empty the cache and synchronize the persistent
+   dictionary on disk, if feasible.  This is called automatically when the shelf
+   is closed with :meth:`close`.
+
+.. method:: Shelf.close()
+
+   Synchronize and close the persistent *dict* object.  Operations on a closed
+   shelf will fail with a :exc:`ValueError`.
+
 
 .. seealso::
 
@@ -71,11 +83,6 @@ Restrictions
   database should be fairly small, and in rare cases key collisions may cause
   the database to refuse updates.
 
-* Depending on the implementation, closing a persistent dictionary may or may
-  not be necessary to flush changes to disk.  The :meth:`__del__` method of the
-  :class:`Shelf` class calls the :meth:`close` method, so the programmer generally
-  need not do this explicitly.
-
 * The :mod:`shelve` module does not support *concurrent* read/write access to
   shelved objects.  (Multiple simultaneous read accesses are safe.)  When a
   program has a shelf open for writing, no other program should have it open for
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 8f56bb0..3b02f98 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1148,6 +1148,8 @@ functions based on regular expressions.
         >>> titlecase("they're bill's friends.")
         "They're Bill's Friends."
 
+   For 8-bit strings, this method is locale-dependent.
+
 
 .. method:: str.translate(map)
 
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index e895e4c..b786034 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -337,12 +337,12 @@ always available.
    does not have to hold true for third-party extensions as it is implementation
    specific.
 
-   The *default* argument allows to define a value which will be returned
-   if the object type does not provide means to retrieve the size and would
-   cause a `TypeError`.
+   If given, *default* will be returned if the object does not provide means to
+   retrieve the size.  Otherwise a `TypeError` will be raised.
 
-   :func:`getsizeof` calls the object's __sizeof__ method and adds an additional
-   garbage collector overhead if the object is managed by the garbage collector.
+   :func:`getsizeof` calls the object's ``__sizeof__`` method and adds an
+   additional garbage collector overhead if the object is managed by the garbage
+   collector.
 
 
 .. function:: _getframe([depth])
@@ -352,7 +352,8 @@ always available.
    that is deeper than the call stack, :exc:`ValueError` is raised.  The default
    for *depth* is zero, returning the frame at the top of the call stack.
 
-   This function should be used for internal and specialized purposes only.
+   This function should be used for internal and specialized purposes only. It
+   is not guaranteed to exist in all implementations of Python.
 
 
 .. function:: getprofile()
diff --git a/Doc/library/termios.rst b/Doc/library/termios.rst
index df29496..591850e 100644
--- a/Doc/library/termios.rst
+++ b/Doc/library/termios.rst
@@ -89,7 +89,7 @@ technique using a separate :func:`tcgetattr` call and a :keyword:`try` ...
 :keyword:`finally` statement to ensure that the old tty attributes are restored
 exactly no matter what happens::
 
-   def getpass(prompt = "Password: "):
+   def getpass(prompt="Password: "):
        import termios, sys
        fd = sys.stdin.fileno()
        old = termios.tcgetattr(fd)
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index aa7f46a..f642111 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -23,7 +23,7 @@ This module defines the following functions and objects:
 .. function:: active_count()
 
    Return the number of :class:`Thread` objects currently alive.  The returned
-   count is equal to the length of the list returned by :func:`enumerate`.
+   count is equal to the length of the list returned by :func:`.enumerate`.
 
 
 .. function:: Condition()
@@ -301,7 +301,7 @@ impossible to detect the termination of alien threads.
 
       Roughly, a thread is alive from the moment the :meth:`start` method
       returns until its :meth:`run` method terminates. The module function
-      :func:`enumerate` returns a list of all alive threads.
+      :func:`.enumerate` returns a list of all alive threads.
 
    .. attribute:: daemon
 
diff --git a/Doc/tutorial/interpreter.rst b/Doc/tutorial/interpreter.rst
index 6c6bc16..bca02ed 100644
--- a/Doc/tutorial/interpreter.rst
+++ b/Doc/tutorial/interpreter.rst
@@ -31,7 +31,7 @@ command into the command prompt in a DOS box::
 Typing an end-of-file character (:kbd:`Control-D` on Unix, :kbd:`Control-Z` on
 Windows) at the primary prompt causes the interpreter to exit with a zero exit
 status.  If that doesn't work, you can exit the interpreter by typing the
-following commands: ``import sys; sys.exit()``.
+following command: ``quit()``.
 
 The interpreter's line-editing features usually aren't very sophisticated.  On
 Unix, whoever installed the interpreter may have enabled support for the GNU
diff --git a/Doc/tutorial/modules.rst b/Doc/tutorial/modules.rst
index 1023ba8..d4bfbda 100644
--- a/Doc/tutorial/modules.rst
+++ b/Doc/tutorial/modules.rst
@@ -107,6 +107,10 @@ In most cases Python programmers do not use this facility since it introduces
 an unknown set of names into the interpreter, possibly hiding some things
 you have already defined.
 
+Note that in general the practice of importing ``*`` from a module or package is
+frowned upon, since it often causes poorly readable code. However, it is okay to
+use it to save typing in interactive sessions.
+
 .. note::
 
    For efficiency reasons, each module is only imported once per interpreter
@@ -445,14 +449,9 @@ Importing \* From a Package
 
 Now what happens when the user writes ``from sound.effects import *``?  Ideally,
 one would hope that this somehow goes out to the filesystem, finds which
-submodules are present in the package, and imports them all.  Unfortunately,
-this operation does not work very well on Windows platforms, where the
-filesystem does not always have accurate information about the case of a
-filename.  On these platforms, there is no guaranteed way to know whether a file
-:file:`ECHO.PY` should be imported as a module :mod:`echo`, :mod:`Echo` or
-:mod:`ECHO`.  (For example, Windows 95 has the annoying practice of showing all
-file names with a capitalized first letter.)  The DOS 8+3 filename restriction
-adds another interesting problem for long module names.
+submodules are present in the package, and imports them all.  This could take a
+long time and importing sub-modules might have unwanted side-effects that should
+only happen when the sub-module is explicitly imported.
 
 The only solution is for the package author to provide an explicit index of the
 package.  The :keyword:`import` statement uses the following convention: if a package's
@@ -487,10 +486,9 @@ current namespace because they are defined in the :mod:`sound.effects` package
 when the ``from...import`` statement is executed.  (This also works when
 ``__all__`` is defined.)
 
-Note that in general the practice of importing ``*`` from a module or package is
-frowned upon, since it often causes poorly readable code. However, it is okay to
-use it to save typing in interactive sessions, and certain modules are designed
-to export only names that follow certain patterns.
+Although certain modules are designed to export only names that follow certain
+patterns when you use ``import *``, it is still considered bad practise in
+production code.
 
 Remember, there is nothing wrong with using ``from Package import
 specific_submodule``!  In fact, this is the recommended notation unless the
diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst
index f5f7d19..e92af99 100644
--- a/Doc/whatsnew/2.7.rst
+++ b/Doc/whatsnew/2.7.rst
@@ -505,6 +505,13 @@ changes, or look through the Subversion logs for all the details.
     differences.  :meth:`assertDictContainsSubset` checks whether
     all of the key/value pairs in *first* are found in *second*.
 
+  * :meth:`assertAlmostEqual` and :meth:`assertNotAlmostEqual` short-circuit
+    (automatically pass or fail without checking decimal places) if the objects
+    are equal.
+
+  * :meth:`loadTestsFromName` properly honors the ``suiteClass`` attribute of
+    the :class:`TestLoader`. (Fixed by Mark Roddy; :issue:`6866`.)
+
   * A new hook, :meth:`addTypeEqualityFunc` takes a type object and a
     function.  The :meth:`assertEqual` method will use the function
     when both of the objects being compared are of the specified type.