python
diff --git a/‎Doc/c-api/init.rst‎
Lines changed: 4 additions & 0 deletions b/‎Doc/c-api/init.rst‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎Doc/c-api/unicode.rst‎
Lines changed: 17 additions & 12 deletions b/‎Doc/c-api/unicode.rst‎
Lines changed: 17 additions & 12 deletions
diff --git a/‎Doc/documenting/markup.rst‎
Lines changed: 4 additions & 2 deletions b/‎Doc/documenting/markup.rst‎
Lines changed: 4 additions & 2 deletions
diff --git a/‎Doc/library/codecs.rst‎
Lines changed: 1 addition & 1 deletion b/‎Doc/library/codecs.rst‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎Doc/library/datetime.rst‎
Lines changed: 4 additions & 0 deletions b/‎Doc/library/datetime.rst‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎Doc/library/functions.rst‎
Lines changed: 7 additions & 11 deletions b/‎Doc/library/functions.rst‎
Lines changed: 7 additions & 11 deletions
diff --git a/‎Doc/library/hashlib.rst‎
Lines changed: 2 additions & 2 deletions b/‎Doc/library/hashlib.rst‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎Doc/library/inspect.rst‎
Lines changed: 5 additions & 0 deletions b/‎Doc/library/inspect.rst‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎Doc/library/logging.rst‎
Lines changed: 52 additions & 3 deletions b/‎Doc/library/logging.rst‎
Lines changed: 52 additions & 3 deletions
diff --git a/‎Doc/library/shelve.rst‎
Lines changed: 26 additions & 19 deletions b/‎Doc/library/shelve.rst‎
Lines changed: 26 additions & 19 deletions
@@ -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()
 
@@ -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)
 
@@ -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
 
 
@@ -988,7 +988,7 @@ particular, the following variants typically exist:
 +-----------------+--------------------------------+--------------------------------+
 | cp1255          | windows-1255                   | Hebrew                         |
 +-----------------+--------------------------------+--------------------------------+
-| cp1256          | windows1256                    | Arabic                         |
+| cp1256          | windows-1256                   | Arabic                         |
 +-----------------+--------------------------------+--------------------------------+
 | cp1257          | windows-1257                   | Baltic languages               |
 +-----------------+--------------------------------+--------------------------------+
 
@@ -63,13 +63,15 @@ 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
    :attr:`day`.
 
 
 .. 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,13 +80,15 @@ 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`,
    and :attr:`tzinfo`.
 
 
 .. class:: timedelta
+   :noindex:
 
    A duration expressing the difference between two :class:`date`, :class:`time`,
    or :class:`datetime` instances to microsecond resolution.
 
@@ -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, ...)
 
@@ -1176,10 +1172,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:
 
@@ -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.
 
 
@@ -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)
 
 
@@ -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')
 
@@ -1493,6 +1493,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
 ---------------
@@ -1608,9 +1657,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.
 
 
@@ -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