merge branch 3.5

Author: Anselm Kruis

Doc/c-api/buffer.rst

@@ -40,7 +40,7 @@ protocol <bufferobjects>`.  This protocol has two sides:
 
 Simple objects such as :class:`bytes` and :class:`bytearray` expose their
 underlying buffer in byte-oriented form.  Other forms are possible; for example,
-the elements exposed by a :class:`array.array` can be multi-byte values.
+the elements exposed by an :class:`array.array` can be multi-byte values.
 
 An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase.write`
 method of file objects: any object that can export a series of bytes through

Doc/distutils/index.rst

@@ -15,10 +15,9 @@ very little overhead for build/release/install mechanics.
 .. note::
 
    This guide only covers the basic tools for building and distributing
-   extensions that are provided as part of this version of Python. Third
-   party tools offer easier to use and more secure alternatives. Refer to the
-   `quick recommendations section
-   <https://python-packaging-user-guide.readthedocs.org/en/latest/current.html>`__
+   extensions that are provided as part of this version of Python. Third party
+   tools offer easier to use and more secure alternatives. Refer to the `quick
+   recommendations section <https://packaging.python.org/en/latest/current/>`__
    in the Python Packaging User Guide for more information.
 
 

Doc/distutils/packageindex.rst

@@ -167,7 +167,7 @@ follows::
     username: <username>
     password: <password>
 
-The *distutils* section defines a *index-servers* variable that lists the
+The *distutils* section defines an *index-servers* variable that lists the
 name of all sections describing a repository.
 
 Each section describing a repository defines three variables:

Doc/faq/general.rst

@@ -151,8 +151,8 @@ after a final minor release is made, the Subversion trunk is incremented to the
 next minor version, which becomes the "a0" version,
 e.g. "2.4a0".
 
-See also the documentation for ``sys.version``, ``sys.hexversion``, and
-``sys.version_info``.
+See also the documentation for :data:`sys.version`, :data:`sys.hexversion`, and
+:data:`sys.version_info`.
 
 
 How do I obtain a copy of the Python source?

Doc/faq/programming.rst

@@ -849,7 +849,7 @@ How do I modify a string in place?
 You can't, because strings are immutable.  In most situations, you should
 simply construct a new string from the various parts you want to assemble
 it from.  However, if you need an object with the ability to modify in-place
-unicode data, try using a :class:`io.StringIO` object or the :mod:`array`
+unicode data, try using an :class:`io.StringIO` object or the :mod:`array`
 module::
 
    >>> import io

Doc/howto/descriptor.rst

@@ -319,7 +319,7 @@ Non-data descriptors provide a simple mechanism for variations on the usual
 patterns of binding functions into methods.
 
 To recap, functions have a :meth:`__get__` method so that they can be converted
-to a method when accessed as attributes.  The non-data descriptor transforms a
+to a method when accessed as attributes.  The non-data descriptor transforms an
 ``obj.f(*args)`` call into ``f(obj, *args)``.  Calling ``klass.f(*args)``
 becomes ``f(*args)``.
 

Doc/howto/logging-cookbook.rst

@@ -2288,3 +2288,69 @@ You can of course use the conventional means of decoration::
     @log_if_errors(logger)
     def foo(fail=False):
         ...
+
+
+.. _utc-formatting:
+
+Formatting times using UTC (GMT) via configuration
+--------------------------------------------------
+
+Sometimes you want to format times using UTC, which can be done using a class
+such as `UTCFormatter`, shown below::
+
+    import logging
+    import time
+
+    class UTCFormatter(logging.Formatter):
+        converter = time.gmtime
+
+and you can then use the ``UTCFormatter`` in your code instead of
+:class:`~logging.Formatter`. If you want to do that via configuration, you can
+use the :func:`~logging.config.dictConfig` API with an approach illustrated by
+the following complete example::
+
+    import logging
+    import logging.config
+    import time
+
+    class UTCFormatter(logging.Formatter):
+        converter = time.gmtime
+
+    LOGGING = {
+        'version': 1,
+        'disable_existing_loggers': False,
+        'formatters': {
+            'utc': {
+                '()': UTCFormatter,
+                'format': '%(asctime)s %(message)s',
+            },
+            'local': {
+                'format': '%(asctime)s %(message)s',
+            }
+        },
+        'handlers': {
+            'console1': {
+                'class': 'logging.StreamHandler',
+                'formatter': 'utc',
+            },
+            'console2': {
+                'class': 'logging.StreamHandler',
+                'formatter': 'local',
+            },
+        },
+        'root': {
+            'handlers': ['console1', 'console2'],
+       }
+    }
+
+    if __name__ == '__main__':
+        logging.config.dictConfig(LOGGING)
+        logging.warning('The local time is %s', time.asctime())
+
+When this script is run, it should print something like::
+
+    2015-10-17 12:53:29,501 The local time is Sat Oct 17 13:53:29 2015
+    2015-10-17 13:53:29,501 The local time is Sat Oct 17 13:53:29 2015
+
+showing how the time is formatted both as local time and UTC, one for each
+handler.

Doc/install/index.rst

@@ -28,16 +28,16 @@ modules and extensions.
 
 .. note::
 
-   This guide only covers the basic tools for installing extensions that are
-   provided as part of this version of Python. Third party tools offer easier
-   to use and more secure alternatives. Refer to the
-   `quick recommendations section
-   <https://python-packaging-user-guide.readthedocs.org/en/latest/current.html>`__
+   This guide only covers the basic tools for building and distributing
+   extensions that are provided as part of this version of Python. Third party
+   tools offer easier to use and more secure alternatives. Refer to the `quick
+   recommendations section <https://packaging.python.org/en/latest/current/>`__
    in the Python Packaging User Guide for more information.
 
 
 .. _inst-intro:
 
+
 Introduction
 ============
 
@@ -148,7 +148,7 @@ into.  For example, if you've just downloaded a module source distribution
 
 On Windows, you'd probably download :file:`foo-1.0.zip`.  If you downloaded the
 archive file to :file:`C:\\Temp`, then it would unpack into
-:file:`C:\\Temp\\foo-1.0`; you can use either a archive manipulator with a
+:file:`C:\\Temp\\foo-1.0`; you can use either an archive manipulator with a
 graphical user interface (such as WinZip) or a command-line tool (such as
 :program:`unzip` or :program:`pkunzip`) to unpack the archive.  Then, open a
 command prompt window and run::

Doc/library/argparse.rst

@@ -530,7 +530,7 @@ allow_abbrev
 ^^^^^^^^^^^^
 
 Normally, when you pass an argument list to the
-:meth:`~ArgumentParser.parse_args` method of a :class:`ArgumentParser`,
+:meth:`~ArgumentParser.parse_args` method of an :class:`ArgumentParser`,
 it :ref:`recognizes abbreviations <prefix-matching>` of long options.
 
 This feature can be disabled by setting ``allow_abbrev`` to ``False``::

Doc/library/asyncio-eventloops.rst

@@ -57,9 +57,9 @@ asyncio currently provides two implementations of event loops:
 
 Example to use a :class:`ProactorEventLoop` on Windows::
 
-    import asyncio, os
+    import asyncio, sys
 
-    if os.name == 'nt':
+    if sys.platform == 'win32':
         loop = asyncio.ProactorEventLoop()
         asyncio.set_event_loop(loop)
 
@@ -198,4 +198,3 @@ Access to the global loop policy
 
    Set the current event loop policy. If *policy* is ``None``, the default
    policy is restored.
-

Doc/library/asyncio-protocol.rst

@@ -148,7 +148,7 @@ WriteTransport
       high-water limit.  Neither *high* nor *low* can be negative.
 
       The defaults are implementation-specific.  If only the
-      high-water limit is given, the low-water limit defaults to a
+      high-water limit is given, the low-water limit defaults to an
       implementation-specific value less than or equal to the
       high-water limit.  Setting *high* to zero forces *low* to zero as
       well, and causes :meth:`pause_writing` to be called whenever the

Doc/library/asyncio-stream.rst

@@ -9,6 +9,13 @@ Streams (high-level API)
 Stream functions
 ================
 
+.. note::
+
+   The top-level functions in this module are meant convenience wrappers
+   only; there's really nothing special there, and if they don't do
+   exactly what you want, feel free to copy their code.
+
+
 .. coroutinefunction:: open_connection(host=None, port=None, \*, loop=None, limit=None, \*\*kwds)
 
    A wrapper for :meth:`~BaseEventLoop.create_connection()` returning a (reader,
@@ -26,10 +33,6 @@ Stream functions
    instance to use) and *limit* (to set the buffer limit passed to the
    :class:`StreamReader`).
 
-   (If you want to customize the :class:`StreamReader` and/or
-   :class:`StreamReaderProtocol` classes, just copy the code -- there's really
-   nothing special here except some convenience.)
-
    This function is a :ref:`coroutine <coroutine>`.
 
 .. coroutinefunction:: start_server(client_connected_cb, host=None, port=None, \*, loop=None, limit=None, \*\*kwds)

Doc/library/asyncio-subprocess.rst

@@ -12,9 +12,9 @@ On Windows, the default event loop is :class:`SelectorEventLoop` which does not
 support subprocesses. :class:`ProactorEventLoop` should be used instead.
 Example to use it on Windows::
 
-    import asyncio, os
+    import asyncio, sys
 
-    if os.name == 'nt':
+    if sys.platform == 'win32':
         loop = asyncio.ProactorEventLoop()
         asyncio.set_event_loop(loop)
 

Doc/library/chunk.rst

@@ -47,7 +47,7 @@ Usually an IFF-type file consists of one or more chunks.  The proposed usage of
 the :class:`Chunk` class defined here is to instantiate an instance at the start
 of each chunk and read from the instance until it reaches the end, after which a
 new instance can be instantiated. At the end of the file, creating a new
-instance will fail with a :exc:`EOFError` exception.
+instance will fail with an :exc:`EOFError` exception.
 
 
 .. class:: Chunk(file, align=True, bigendian=True, inclheader=False)

Doc/library/concurrent.futures.rst

@@ -90,7 +90,7 @@ Executor Objects
 ThreadPoolExecutor
 ------------------
 
-:class:`ThreadPoolExecutor` is a :class:`Executor` subclass that uses a pool of
+:class:`ThreadPoolExecutor` is an :class:`Executor` subclass that uses a pool of
 threads to execute calls asynchronously.
 
 Deadlocks can occur when the callable associated with a :class:`Future` waits on
@@ -304,7 +304,7 @@ The :class:`Future` class encapsulates the asynchronous execution of a callable.
 
        Added callables are called in the order that they were added and are
        always called in a thread belonging to the process that added them.  If
-       the callable raises a :exc:`Exception` subclass, it will be logged and
+       the callable raises an :exc:`Exception` subclass, it will be logged and
        ignored.  If the callable raises a :exc:`BaseException` subclass, the
        behavior is undefined.
 

Doc/library/contextlib.rst

@@ -142,7 +142,7 @@ Functions and classes provided:
    is hardwired to stdout.
 
    For example, the output of :func:`help` normally is sent to *sys.stdout*.
-   You can capture that output in a string by redirecting the output to a
+   You can capture that output in a string by redirecting the output to an
    :class:`io.StringIO` object::
 
         f = io.StringIO()

Doc/library/ctypes.rst

@@ -39,7 +39,7 @@ loads libraries which export functions using the standard ``cdecl`` calling
 convention, while *windll* libraries call functions using the ``stdcall``
 calling convention. *oledll* also uses the ``stdcall`` calling convention, and
 assumes the functions return a Windows :c:type:`HRESULT` error code. The error
-code is used to automatically raise a :class:`OSError` exception when the
+code is used to automatically raise an :class:`OSError` exception when the
 function call fails.
 
 .. versionchanged:: 3.3

Doc/library/difflib.rst

@@ -98,9 +98,9 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
       *wrapcolumn* is an optional keyword to specify column number where lines are
       broken and wrapped, defaults to ``None`` where lines are not wrapped.
 
-      *linejunk* and *charjunk* are optional keyword arguments passed into ``ndiff()``
+      *linejunk* and *charjunk* are optional keyword arguments passed into :func:`ndiff`
       (used by :class:`HtmlDiff` to generate the side by side HTML differences).  See
-      ``ndiff()`` documentation for argument default values and descriptions.
+      :func:`ndiff` documentation for argument default values and descriptions.
 
    The following methods are public:
 
@@ -278,7 +278,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
    generating the delta lines) in unified diff format.
 
    Unified diffs are a compact way of showing just the lines that have changed plus
-   a few lines of context.  The changes are shown in a inline style (instead of
+   a few lines of context.  The changes are shown in an inline style (instead of
    separate before/after blocks).  The number of context lines is set by *n* which
    defaults to three.
 

Doc/library/email.parser.rst

@@ -146,7 +146,7 @@ have the same API as the :class:`Parser` and :class:`BytesParser` classes.
       methods on file-like objects.
 
       The text contained in *fp* must be formatted as a block of :rfc:`2822`
-      style headers and header continuation lines, optionally preceded by a
+      style headers and header continuation lines, optionally preceded by an
       envelope header.  The header block is terminated either by the end of the
       data or by a blank line.  Following the header block is the body of the
       message (which may contain MIME-encoded subparts).
@@ -189,7 +189,7 @@ have the same API as the :class:`Parser` and :class:`BytesParser` classes.
       methods on file-like objects.
 
       The bytes contained in *fp* must be formatted as a block of :rfc:`2822`
-      style headers and header continuation lines, optionally preceded by a
+      style headers and header continuation lines, optionally preceded by an
       envelope header.  The header block is terminated either by the end of the
       data or by a blank line.  Following the header block is the body of the
       message (which may contain MIME-encoded subparts, including subparts