diff --git a/Doc/library/aifc.rst b/Doc/library/aifc.rst
index caecfbc..6fbcf28 100644
--- a/Doc/library/aifc.rst
+++ b/Doc/library/aifc.rst
@@ -226,7 +226,7 @@
    file parameters have been set.
 
    .. versionchanged:: 3.4
-      Any :term:`bytes-like object`\ s are now accepted.
+      Any :term:`bytes-like object` is now accepted.
 
 
 .. method:: aifc.writeframesraw(data)
@@ -235,7 +235,7 @@
    updated.
 
    .. versionchanged:: 3.4
-      Any :term:`bytes-like object`\ s are now accepted.
+      Any :term:`bytes-like object` is now accepted.
 
 
 .. method:: aifc.close()
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index 9d54964..df84169 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -488,7 +488,7 @@
 
    * *stdout*: Either a file-like object representing the pipe to be connected
      to the subprocess's standard output stream using
-     :meth:`~BaseEventLoop.connect_write_pipe`, or the constant
+     :meth:`~BaseEventLoop.connect_read_pipe`, or the constant
      :const:`subprocess.PIPE` (the default). By default a new pipe will be
      created and connected.
 
@@ -589,8 +589,8 @@
 
    Arrange for a callback to be called in the specified executor.
 
-   *executor* is a :class:`~concurrent.futures.Executor` instance,
-   the default executor is used if *executor* is ``None``.
+   The *executor* argument should be an :class:`~concurrent.futures.Executor`
+   instance. The default executor is used if *executor* is ``None``.
 
    This method is a :ref:`coroutine <coroutine>`.
 
diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst
index dabe7d8..80c974a 100644
--- a/Doc/library/asyncio-protocol.rst
+++ b/Doc/library/asyncio-protocol.rst
@@ -376,8 +376,8 @@
 Flow control callbacks
 ----------------------
 
-These callbacks may be called on :class:`Protocol` and
-:class:`SubprocessProtocol` instances:
+These callbacks may be called on :class:`Protocol`,
+:class:`DatagramProtocol` and :class:`SubprocessProtocol` instances:
 
 .. method:: BaseProtocol.pause_writing()
 
@@ -402,6 +402,15 @@
    are important to ensure that things go as expected when either
    mark is zero.
 
+.. note::
+   On BSD systems (OS X, FreeBSD, etc.) flow control is not supported
+   for :class:`DatagramProtocol`, because send failures caused by
+   writing too many packets cannot be detected easily.  The socket
+   always appears 'ready' and excess packets are dropped; an
+   :class:`OSError` with errno set to :const:`errno.ENOBUFS` may or
+   may not be raised; if it is raised, it will be reported to
+   :meth:`DatagramProtocol.error_received` but otherwise ignored.
+
 
 Coroutines and protocols
 ------------------------
@@ -488,6 +497,6 @@
 :meth:`Transport.close` can be called immediately after
 :meth:`WriteTransport.write` even if data are not sent yet on the socket: both
 methods are asynchronous. ``yield from`` is not needed because these transport
-methods don't return coroutines.
+methods are not coroutines.
 
 
diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst
index 5e6e657..861bcc0 100644
--- a/Doc/library/asyncio-subprocess.rst
+++ b/Doc/library/asyncio-subprocess.rst
@@ -8,16 +8,16 @@
 
 .. function:: create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds)
 
-   Run the shell command *cmd* given as a string. Return a :class:`Process`
+   Run the shell command *cmd* given as a string. Return a :class:`~asyncio.subprocess.Process`
    instance.
 
-   This function returns a :ref:`coroutine object <coroutine>`.
+   This function is a :ref:`coroutine <coroutine>`.
 
 .. function:: create_subprocess_exec(\*args, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds)
 
-   Create a subprocess. Return a :class:`Process` instance.
+   Create a subprocess. Return a :class:`~asyncio.subprocess.Process` instance.
 
-   This function returns a :ref:`coroutine object <coroutine>`.
+   This function is a :ref:`coroutine <coroutine>`.
 
 Use the :meth:`BaseEventLoop.connect_read_pipe` and
 :meth:`BaseEventLoop.connect_write_pipe` methods to connect pipes.
diff --git a/Doc/library/asyncio-sync.rst b/Doc/library/asyncio-sync.rst
index de38131..a299f09 100644
--- a/Doc/library/asyncio-sync.rst
+++ b/Doc/library/asyncio-sync.rst
@@ -64,7 +64,7 @@
 
    .. method:: locked()
 
-      Return ``True`` if lock is acquired.
+      Return ``True`` if the lock is acquired.
 
    .. method:: acquire()
 
@@ -73,7 +73,7 @@
       This method blocks until the lock is unlocked, then sets it to locked and
       returns ``True``.
 
-      This method returns a :ref:`coroutine object <coroutine>`.
+      This method is a :ref:`coroutine <coroutine>`.
 
    .. method:: release()
 
@@ -141,6 +141,15 @@
 
    A new :class:`Lock` object is created and used as the underlying lock.
 
+   .. method:: acquire()
+
+      Acquire the underlying lock.
+
+      This method blocks until the lock is unlocked, then sets it to locked and
+      returns ``True``.
+
+      This method is a :ref:`coroutine <coroutine>`.
+
    .. method:: notify(n=1)
 
       By default, wake up one coroutine waiting on this condition, if any.
@@ -156,6 +165,10 @@
          call until it can reacquire the lock. Since :meth:`notify` does not
          release the lock, its caller should.
 
+   .. method:: locked()
+
+      Return ``True`` if the underlying lock is acquired.
+
    .. method:: notify_all()
 
       Wake up all threads waiting on this condition. This method acts like
@@ -163,6 +176,18 @@
       calling thread has not acquired the lock when this method is called, a
       :exc:`RuntimeError` is raised.
 
+   .. method:: release()
+
+      Release the underlying lock.
+
+      When the lock is locked, reset it to unlocked, and return. If any other
+      coroutines are blocked waiting for the lock to become unlocked, allow
+      exactly one of them to proceed.
+
+      When invoked on an unlocked lock, a :exc:`RuntimeError` is raised.
+
+      There is no return value.
+
    .. method:: wait()
 
       Wait until notified.
diff --git a/Doc/library/audioop.rst b/Doc/library/audioop.rst
index fbb7fc6..ce127aa 100644
--- a/Doc/library/audioop.rst
+++ b/Doc/library/audioop.rst
@@ -12,10 +12,8 @@
 
 .. versionchanged:: 3.4
    Support for 24-bit samples was added.
-
-.. versionchanged:: 3.4
-   Any :term:`bytes-like object`\ s are now accepted by all functions in this
-   module.  Strings no more supported.
+   All functions now accept any :term:`bytes-like object`.
+   String input now results in an immediate error.
 
 .. index::
    single: Intel/DVI ADPCM
@@ -82,7 +80,7 @@
    "Byteswap" all samples in a fragment and returns the modified fragment.
    Converts big-endian samples to little-endian and vice versa.
 
-   .. versionadded: 3.4
+   .. versionadded:: 3.4
 
 
 .. function:: cross(fragment, width)
diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst
index 3d1f087..02b4d7b 100644
--- a/Doc/library/base64.rst
+++ b/Doc/library/base64.rst
@@ -1,27 +1,33 @@
-:mod:`base64` --- RFC 3548: Base16, Base32, Base64 Data Encodings
-=================================================================
+:mod:`base64` --- Base16, Base32, Base64, Base85 Data Encodings
+===============================================================
 
 .. module:: base64
-   :synopsis: RFC 3548: Base16, Base32, Base64 Data Encodings
+   :synopsis: RFC 3548: Base16, Base32, Base64 Data Encodings;
+              Base85 and Ascii85
 
 
 .. index::
    pair: base64; encoding
    single: MIME; base64 encoding
 
-This module provides data encoding and decoding as specified in :rfc:`3548`.
-This standard defines the Base16, Base32, and Base64 algorithms for encoding
-and decoding arbitrary binary strings into ASCII-only byte strings that can be
+This module provides functions for encoding binary data to printable
+ASCII characters and decoding such encodings back to binary data.
+It provides encoding and decoding functions for the encodings specified in
+in :rfc:`3548`, which defines the Base16, Base32, and Base64 algorithms,
+and for the de-facto standard Ascii85 and Base85 encodings.
+
+The :rfc:`3548` encodings are suitable for encoding binary data so that it can
 safely sent by email, used as parts of URLs, or included as part of an HTTP
 POST request.  The encoding algorithm is not the same as the
 :program:`uuencode` program.
 
-There are two interfaces provided by this module.  The modern interface
-supports encoding and decoding ASCII byte string objects using all three
-alphabets. Additionally, the decoding functions of the modern interface also
-accept Unicode strings containing only ASCII characters. The legacy interface
-provides for encoding and decoding to and from file-like objects as well as
-byte strings, but only using the Base64 standard alphabet.
+There are two :rfc:`3548` interfaces provided by this module.  The modern
+interface supports encoding and decoding ASCII byte string objects using all
+three :rfc:`3548` defined alphabets (normal, URL-safe, and filesystem-safe).
+Additionally, the decoding functions of the modern interface also accept
+Unicode strings containing only ASCII characters. The legacy interface provides
+for encoding and decoding to and from file-like objects as well as byte
+strings, but only using the Base64 standard alphabet.
 
 .. versionchanged:: 3.3
    ASCII-only Unicode strings are now accepted by the decoding functions of
@@ -29,7 +35,7 @@
 
 .. versionchanged:: 3.4
    Any :term:`bytes-like object`\ s are now accepted by all
-   encoding and decoding functions in this module.
+   encoding and decoding functions in this module.  Ascii85/Base85 support added.
 
 The modern interface provides:
 
diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst
index a20c4be..ccc9dc6 100644
--- a/Doc/library/csv.rst
+++ b/Doc/library/csv.rst
@@ -142,36 +142,43 @@
 
 The :mod:`csv` module defines the following classes:
 
-.. class:: DictReader(csvfile, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)
+.. class:: DictReader(csvfile, fieldnames=None, restkey=None, restval=None, \
+                      dialect='excel', *args, **kwds)
 
-   Create an object which operates like a regular reader but maps the information
-   read into a dict whose keys are given by the optional  *fieldnames* parameter.
-   If the *fieldnames* parameter is omitted, the values in the first row of the
-   *csvfile* will be used as the fieldnames.  If the row read has more fields
-   than the fieldnames sequence, the remaining data is added as a sequence
-   keyed by the value of *restkey*.  If the row read has fewer fields than the
-   fieldnames sequence, the remaining keys take the value of the optional
-   *restval* parameter.  Any other optional or keyword arguments are passed to
-   the underlying :class:`reader` instance.
+   Create an object which operates like a regular reader but maps the
+   information read into a dict whose keys are given by the optional
+   *fieldnames* parameter.  The *fieldnames* parameter is a :mod:`sequence
+   <collections.abc>` whose elements are associated with the fields of the
+   input data in order. These elements become the keys of the resulting
+   dictionary.  If the *fieldnames* parameter is omitted, the values in the
+   first row of the *csvfile* will be used as the fieldnames.  If the row read
+   has more fields than the fieldnames sequence, the remaining data is added as
+   a sequence keyed by the value of *restkey*.  If the row read has fewer
+   fields than the fieldnames sequence, the remaining keys take the value of
+   the optional *restval* parameter.  Any other optional or keyword arguments
+   are passed to the underlying :class:`reader` instance.
 
 
-.. class:: DictWriter(csvfile, fieldnames, restval='', extrasaction='raise', dialect='excel', *args, **kwds)
+.. class:: DictWriter(csvfile, fieldnames, restval='', extrasaction='raise', \
+                      dialect='excel', *args, **kwds)
 
-   Create an object which operates like a regular writer but maps dictionaries onto
-   output rows.  The *fieldnames* parameter identifies the order in which values in
-   the dictionary passed to the :meth:`writerow` method are written to the
-   *csvfile*.  The optional *restval* parameter specifies the value to be written
-   if the dictionary is missing a key in *fieldnames*.  If the dictionary passed to
-   the :meth:`writerow` method contains a key not found in *fieldnames*, the
-   optional *extrasaction* parameter indicates what action to take.  If it is set
-   to ``'raise'`` a :exc:`ValueError` is raised.  If it is set to ``'ignore'``,
-   extra values in the dictionary are ignored.  Any other optional or keyword
-   arguments are passed to the underlying :class:`writer` instance.
+   Create an object which operates like a regular writer but maps dictionaries
+   onto output rows.  The *fieldnames* parameter is a :mod:`sequence
+   <collections.abc>` of keys that identify the order in which values in the
+   dictionary passed to the :meth:`writerow` method are written to the
+   *csvfile*.  The optional *restval* parameter specifies the value to be
+   written if the dictionary is missing a key in *fieldnames*.  If the
+   dictionary passed to the :meth:`writerow` method contains a key not found in
+   *fieldnames*, the optional *extrasaction* parameter indicates what action to
+   take.  If it is set to ``'raise'`` a :exc:`ValueError` is raised.  If it is
+   set to ``'ignore'``, extra values in the dictionary are ignored.  Any other
+   optional or keyword arguments are passed to the underlying :class:`writer`
+   instance.
 
-   Note that unlike the :class:`DictReader` class, the *fieldnames* parameter of
-   the :class:`DictWriter` is not optional.  Since Python's :class:`dict` objects
-   are not ordered, there is not enough information available to deduce the order
-   in which the row should be written to the *csvfile*.
+   Note that unlike the :class:`DictReader` class, the *fieldnames* parameter
+   of the :class:`DictWriter` is not optional.  Since Python's :class:`dict`
+   objects are not ordered, there is not enough information available to deduce
+   the order in which the row should be written to the *csvfile*.
 
 
 .. class:: Dialect
diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst
index 314636e..f3e60b4 100644
--- a/Doc/library/curses.rst
+++ b/Doc/library/curses.rst
@@ -12,7 +12,7 @@
 de-facto standard for portable advanced terminal handling.
 
 While curses is most widely used in the Unix environment, versions are available
-for DOS, OS/2, and possibly other systems as well.  This extension module is
+for Windows, DOS, and possibly other systems as well.  This extension module is
 designed to match the API of ncurses, an open-source curses library hosted on
 Linux and the BSD variants of Unix.
 
diff --git a/Doc/library/distutils.rst b/Doc/library/distutils.rst
index 6666a9b..8e3732b 100644
--- a/Doc/library/distutils.rst
+++ b/Doc/library/distutils.rst
@@ -12,14 +12,15 @@
 100%-pure Python, or may be extension modules written in C, or may be
 collections of Python packages which include modules coded in both Python and C.
 
+Most Python users will *not* want to use this module directly, but instead
+use the cross-version tools maintained by the Python Packaging Authority.
+Refer to the `Python Packaging User Guide <http://packaging.python.org>`_
+for more information.
 
-User documentation and API reference are provided in another document:
+For the benefits of packaging tool authors and users seeking a deeper
+understanding of the details of the current packaging and distribution
+system, the legacy :mod:`distutils` based user documentation and API
+reference remain available:
 
-.. seealso::
-
-   :ref:`distutils-index`
-      The manual for developers and packagers of Python modules.  This describes
-      how to prepare :mod:`distutils`\ -based packages so that they may be
-      easily installed into an existing Python installation.  It also contains
-      instructions for end-users wanting to install a distutils-based package,
-      :ref:`install-index`.
+* :ref:`install-index`
+* :ref:`distutils-index`
diff --git a/Doc/library/email-examples.rst b/Doc/library/email-examples.rst
index 294e131..cbbcb78 100644
--- a/Doc/library/email-examples.rst
+++ b/Doc/library/email-examples.rst
@@ -40,8 +40,10 @@
 .. literalinclude:: ../includes/email-alternative.py
 
 
-Examples using the Provision API
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _email-contentmanager-api-examples:
+
+Examples using the Provisional API
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Here is a reworking of the last example using the provisional API.  To make
 things a bit more interesting, we include a related image in the html part, and
 we save a copy of what we are going to send to disk, as well as sending it.
diff --git a/Doc/library/email.contentmanager.rst b/Doc/library/email.contentmanager.rst
index 5162da1..8f0bfdb 100644
--- a/Doc/library/email.contentmanager.rst
+++ b/Doc/library/email.contentmanager.rst
@@ -54,6 +54,7 @@
    documented in this module because of the provisional nature of the code, the
    implementation lives in the :mod:`email.message` module.
 
+.. currentmodule:: email.message
 
 .. class:: EmailMessage(policy=default)
 
@@ -235,6 +236,16 @@
       all other headers intact and in their original order.
 
 
+.. class:: MIMEPart(policy=default)
+
+    This class represents a subpart of a MIME message.  It is identical to
+    :class:`EmailMessage`, except that no :mailheader:`MIME-Version` headers are
+    added when :meth:`~EmailMessage.set_content` is called, since sub-parts do
+    not need their own :mailheader:`MIME-Version` headers.
+
+
+.. currentmodule:: email.contentmanager
+
 .. class:: ContentManager()
 
    Base class for content managers.  Provides the standard registry mechanisms
@@ -305,14 +316,6 @@
       values of *typekey*, see :meth:`set_content`.
 
 
-.. class:: MIMEPart(policy=default)
-
-    This class represents a subpart of a MIME message.  It is identical to
-    :class:`EmailMessage`, except that no :mailheader:`MIME-Version` headers are
-    added when :meth:`~EmailMessage.set_content` is called, since sub-parts do
-    not need their own :mailheader:`MIME-Version` headers.
-
-
 Content Manager Instances
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst
index 84a5f51..58f708c 100644
--- a/Doc/library/email.message.rst
+++ b/Doc/library/email.message.rst
@@ -466,7 +466,7 @@
       to ``False``.
 
 
-   .. method:: set_param(param, value, header='Content-Type', requote=True,
+   .. method:: set_param(param, value, header='Content-Type', requote=True, \
                          charset=None, language='', replace=False)
 
       Set a parameter in the :mailheader:`Content-Type` header.  If the
@@ -488,7 +488,7 @@
       end of the list of headers.  If *replace* is ``True``, the header
       will be updated in place.
 
-      .. versionchanged: 3.4 ``replace`` keyword was added.
+      .. versionchanged:: 3.4 ``replace`` keyword was added.
 
 
    .. method:: del_param(param, header='content-type', requote=True)
diff --git a/Doc/library/email.policy.rst b/Doc/library/email.policy.rst
index c2f9e6a..97358f0 100644
--- a/Doc/library/email.policy.rst
+++ b/Doc/library/email.policy.rst
@@ -419,7 +419,7 @@
       additional arguments.  By default ``content_manager`` is set to
       :data:`~email.contentmanager.raw_data_manager`.
 
-      .. versionadded 3.4
+      .. versionadded:: 3.4
 
 
    The class provides the following concrete implementations of the abstract
diff --git a/Doc/library/ensurepip.rst b/Doc/library/ensurepip.rst
index 0d82135..8012f51 100644
--- a/Doc/library/ensurepip.rst
+++ b/Doc/library/ensurepip.rst
@@ -28,7 +28,7 @@
 
 .. seealso::
 
-   :ref:`install-index`
+   :ref:`installing-index`
       The end user guide for installing Python packages
 
    :pep:`453`: Explicit bootstrapping of pip in Python installations
diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index 628f91c..fc7267b 100644
--- a/Doc/library/enum.rst
+++ b/Doc/library/enum.rst
@@ -139,7 +139,7 @@
     >>> Color['green']
     <Color.green: 2>
 
-If have an enum member and need its :attr:`name` or :attr:`value`::
+If you have an enum member and need its :attr:`name` or :attr:`value`::
 
     >>> member = Color.red
     >>> member.name
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index c2017cc..0aac1bf 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -265,7 +265,6 @@
       :exc:`mmap.error` have been merged into :exc:`OSError`.
 
    .. versionchanged:: 3.4
-
       The :attr:`filename` attribute is now the original file name passed to
       the function, instead of the name encoded to or decoded from the
       filesystem encoding.  Also, the :attr:`filename2` attribute was added.
diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst
index fba199b..c2c7401 100644
--- a/Doc/library/fractions.rst
+++ b/Doc/library/fractions.rst
@@ -99,7 +99,9 @@
       value of *flt*, which must be a :class:`float`. Beware that
       ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``
 
-      .. note:: From Python 3.2 onwards, you can also construct a
+      .. note::
+
+         From Python 3.2 onwards, you can also construct a
          :class:`Fraction` instance directly from a :class:`float`.
 
 
@@ -108,7 +110,9 @@
       This class method constructs a :class:`Fraction` representing the exact
       value of *dec*, which must be a :class:`decimal.Decimal` instance.
 
-      .. note:: From Python 3.2 onwards, you can also construct a
+      .. note::
+
+         From Python 3.2 onwards, you can also construct a
          :class:`Fraction` instance directly from a :class:`decimal.Decimal`
          instance.
 
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 4371969..2b37069 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -540,12 +540,13 @@
    A call to ``format(value, format_spec)`` is translated to
    ``type(value).__format__(format_spec)`` which bypasses the instance
    dictionary when searching for the value's :meth:`__format__` method.  A
-   :exc:`TypeError` exception is raised if the method is not found or if either
-   the *format_spec* or the return value are not strings.
+   :exc:`TypeError` exception is raised if the method search reaches
+   :mod:`object` and the *format_spec* is non-empty, or if either the
+   *format_spec* or the return value are not strings.
 
-   .. versionadded:: 3.4
+   .. versionchanged:: 3.4
       ``object().__format__(format_spec)`` raises :exc:`TypeError`
-      if *format_spec* is not empty string.
+      if *format_spec* is not an empty string.
 
 
 .. _func-frozenset:
@@ -609,12 +610,26 @@
 
    This function is added to the built-in namespace by the :mod:`site` module.
 
+   .. versionchanged:: 3.4
+      Changes to :mod:`pydoc` and :mod:`inspect` mean that the reported
+      signatures for callables are now more comprehensive and consistent.
+
 
 .. function:: hex(x)
 
-   Convert an integer number to a hexadecimal string. The result is a valid Python
-   expression.  If *x* is not a Python :class:`int` object, it has to define an
-   :meth:`__index__` method that returns an integer.
+   Convert an integer number to a lowercase hexadecimal string
+   prefixed with "0x", for example:
+
+      >>> hex(255)
+      '0xff'
+      >>> hex(-42)
+      '-0x2a'
+
+   If x is not a Python :class:`int` object, it has to define an __index__()
+   method that returns an integer.
+
+   See also :func:`int` for converting a hexadecimal string to an
+   integer using a base of 16.
 
    .. note::
 
@@ -780,6 +795,9 @@
    such as ``sorted(iterable, key=keyfunc, reverse=True)[0]`` and
    ``heapq.nlargest(1, iterable, key=keyfunc)``.
 
+   .. versionadded:: 3.4
+      The *default* keyword-only argument.
+
 
 .. _func-memoryview:
 .. function:: memoryview(obj)
@@ -811,6 +829,9 @@
    such as ``sorted(iterable, key=keyfunc)[0]`` and ``heapq.nsmallest(1,
    iterable, key=keyfunc)``.
 
+   .. versionadded:: 3.4
+      The *default* keyword-only argument.
+
 .. function:: next(iterator[, default])
 
    Retrieve the next item from the *iterator* by calling its
diff --git a/Doc/library/getopt.rst b/Doc/library/getopt.rst
index b6ab3df..f9a1e53 100644
--- a/Doc/library/getopt.rst
+++ b/Doc/library/getopt.rst
@@ -10,6 +10,7 @@
 --------------
 
 .. note::
+
    The :mod:`getopt` module is a parser for command line options whose API is
    designed to be familiar to users of the C :c:func:`getopt` function. Users who
    are unfamiliar with the C :c:func:`getopt` function or who would like to write
diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst
index 8f4cd70..d27902e 100644
--- a/Doc/library/hashlib.rst
+++ b/Doc/library/hashlib.rst
@@ -101,18 +101,18 @@
 
 .. data:: algorithms_guaranteed
 
-   Contains the names of the hash algorithms guaranteed to be supported
+   A set containing the names of the hash algorithms guaranteed to be supported
    by this module on all platforms.
 
    .. versionadded:: 3.2
 
 .. data:: algorithms_available
 
-   Contains the names of the hash algorithms that are available
-   in the running Python interpreter.  These names will be recognized
-   when passed to :func:`new`.  :attr:`algorithms_guaranteed`
-   will always be a subset.  Duplicate algorithms with different
-   name formats may appear in this set (thanks to OpenSSL).
+   A set containing the names of the hash algorithms that are available in the
+   running Python interpreter.  These names will be recognized when passed to
+   :func:`new`.  :attr:`algorithms_guaranteed` will always be a subset.  The
+   same algorithm may appear multiple times in this set under different names
+   (thanks to OpenSSL).
 
    .. versionadded:: 3.2
 
diff --git a/Doc/library/hmac.rst b/Doc/library/hmac.rst
index 2e9b0b2..4858235 100644
--- a/Doc/library/hmac.rst
+++ b/Doc/library/hmac.rst
@@ -23,9 +23,8 @@
    defaults to the :data:`hashlib.md5` constructor.
 
    .. versionchanged:: 3.4
-      Parameter *key* can be a bytes or bytearray object. Parameter *msg* can
-      be of any type supported by :mod:`hashlib`.
-
+      Parameter *key* can be a bytes or bytearray object.
+      Parameter *msg* can be of any type supported by :mod:`hashlib`.
       Paramter *digestmod* can be the name of a hash algorithm.
 
    .. deprecated:: 3.4
diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst
index 0f7c8b3..dd19fb4 100644
--- a/Doc/library/http.server.rst
+++ b/Doc/library/http.server.rst
@@ -351,7 +351,7 @@
 
 The :class:`SimpleHTTPRequestHandler` class can be used in the following
 manner in order to create a very basic webserver serving files relative to
-the current directory. ::
+the current directory::
 
    import http.server
    import socketserver
@@ -365,15 +365,17 @@
    print("serving at port", PORT)
    httpd.serve_forever()
 
+.. _http-server-cli:
+
 :mod:`http.server` can also be invoked directly using the :option:`-m`
 switch of the interpreter with a ``port number`` argument.  Similar to
-the previous example, this serves files relative to the current directory. ::
+the previous example, this serves files relative to the current directory::
 
         python -m http.server 8000
 
-By default, server binds itself to all interfaces. To restrict it to bind to a
-particular interface only, ``--bind ADDRESS`` argument can be used. For e.g, to
-restrict the server to bind only to localhost. ::
+By default, server binds itself to all interfaces.  The option ``-b/--bind``
+specifies a specific address to which it should bind.  For example, the
+following command causes the server to bind to localhost only::
 
         python -m http.server 8000 --bind 127.0.0.1
 
@@ -422,7 +424,7 @@
    reasons.  Problems with the CGI script will be translated to error 403.
 
 :class:`CGIHTTPRequestHandler` can be enabled in the command line by passing
-the ``--cgi`` option.::
+the ``--cgi`` option::
 
         python -m http.server --cgi 8000
 
diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index a81ccfd..3b55b06 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -134,7 +134,7 @@
 
    When :func:`reload` is executed:
 
-   * Python modules' code is recompiled and the module-level code re-executed,
+   * Python module's code is recompiled and the module-level code re-executed,
      defining a new set of objects which are bound to names in the module's
      dictionary by reusing the :term:`loader` which originally loaded the
      module.  The ``init`` function of extension modules is not called a second
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index ccb2bd7..0c08712 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -729,6 +729,11 @@
       Consider using the new :ref:`Signature Object <inspect-signature-object>`
       interface, which provides a better way of introspecting functions.
 
+   .. versionchanged:: 3.4
+      This function is now based on :func:`signature`, but still ignores
+      ``__wrapped__`` attributes and includes the already bound first
+      parameter in the signature output for bound methods.
+
 
 .. function:: getargvalues(frame)
 
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index c80198b..79f65e0 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -686,6 +686,7 @@
    :exc:`UnsupportedOperation`.
 
    .. warning::
+
       :class:`BufferedRWPair` does not attempt to synchronize accesses to
       its underlying raw streams.  You should not pass it the same object
       as reader and writer; use :class:`BufferedRandom` instead.
diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst
index 9ccf262..9625e71 100644
--- a/Doc/library/ipaddress.rst
+++ b/Doc/library/ipaddress.rst
@@ -154,20 +154,20 @@
    .. attribute:: is_private
 
       ``True`` if the address is allocated for private networks.  See
-      iana-ipv4-special-registry (for IPv4) or iana-ipv6-special-registry
+      iana-ipv4-special-registry_ (for IPv4) or iana-ipv6-special-registry_
       (for IPv6).
 
    .. attribute:: is_global
 
       ``True`` if the address is allocated for public networks.  See
-      iana-ipv4-special-registry (for IPv4) or iana-ipv6-special-registry
+      iana-ipv4-special-registry_ (for IPv4) or iana-ipv6-special-registry_
       (for IPv6).
 
-   .. versionadded:: 3.4
+      .. versionadded:: 3.4
 
    .. attribute:: is_unspecified
 
-      ``True`` if the address is unspecified.  See :RFC:`5375` (for IPv4)
+      ``True`` if the address is unspecified.  See :RFC:`5735` (for IPv4)
       or :RFC:`2373` (for IPv6).
 
    .. attribute:: is_reserved
@@ -184,6 +184,9 @@
       ``True`` if the address is reserved for link-local usage.  See
       :RFC:`3927`.
 
+.. _iana-ipv4-special-registry: http://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml
+.. _iana-ipv6-special-registry: http://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml
+
 
 .. class:: IPv6Address(address)
 
@@ -218,18 +221,23 @@
    The long form of the address representation, with all leading zeroes and
    groups consisting entirely of zeroes included.
 
+
+   For the following attributes, see the corresponding documention of the
+   :class:`IPv4Address` class:
+
    .. attribute:: packed
    .. attribute:: version
    .. attribute:: max_prefixlen
    .. attribute:: is_multicast
    .. attribute:: is_private
+   .. attribute:: is_global
    .. attribute:: is_unspecified
    .. attribute:: is_reserved
    .. attribute:: is_loopback
    .. attribute:: is_link_local
 
-      Refer to the corresponding attribute documentation in
-      :class:`IPv4Address`
+      .. versionadded:: 3.4
+         is_global
 
    .. attribute:: is_site_local
 
diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst
index 5fb1b7a..171b0a3 100644
--- a/Doc/library/logging.config.rst
+++ b/Doc/library/logging.config.rst
@@ -148,7 +148,9 @@
    send it to the socket as a string of bytes preceded by a four-byte length
    string packed in binary using ``struct.pack('>L', n)``.
 
-   .. note:: Because portions of the configuration are passed through
+   .. note::
+
+      Because portions of the configuration are passed through
       :func:`eval`, use of this function may open its users to a security risk.
       While the function only binds to a socket on ``localhost``, and so does
       not accept connections from remote machines, there are scenarios where
@@ -752,7 +754,9 @@
 :class:`~logging.Formatter` can present exception tracebacks in an expanded or
 condensed format.
 
-.. note:: Due to the use of :func:`eval` as described above, there are
+.. note::
+
+   Due to the use of :func:`eval` as described above, there are
    potential security risks which result from using the :func:`listen` to send
    and receive configurations via sockets. The risks are limited to where
    multiple users with no mutual trust run code on the same machine; see the
diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index 7c3ab59..3c41672 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -36,9 +36,9 @@
 
 .. function:: copysign(x, y)
 
-   Return *x* with the sign of *y*.  On a platform that supports
-   signed zeros, ``copysign(1.0, -0.0)`` returns *-1.0*.
-
+   Return a float with the magnitude (absolute value) of *x* but the sign of
+   *y*.  On platforms that support signed zeros, ``copysign(1.0, -0.0)``
+   returns *-1.0*.
 
 .. function:: fabs(x)
 
diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index a8872e7..b303e16 100644
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -136,9 +136,11 @@
     Available on Unix platforms which support passing file descriptors
     over Unix pipes.
 
-Before Python 3.4 *fork* was the only option available on Unix.  Also,
-prior to Python 3.4, child processes would inherit all the parents
-inheritable handles on Windows.
+.. versionchanged:: 3.4
+   *spawn* added on all unix platforms, and *forkserver* added for
+     some unix platforms.
+   Child processes no longer inherit all of the parents inheritable
+     handles on Windows.
 
 On Unix using the *spawn* or *forkserver* start methods will also
 start a *semaphore tracker* process which tracks the unlinked named
@@ -1474,7 +1476,7 @@
 
       *exposed* is used to specify a sequence of method names which proxies for
       this typeid should be allowed to access using
-      :meth:`BaseProxy._callMethod`.  (If *exposed* is ``None`` then
+      :meth:`BaseProxy._callmethod`.  (If *exposed* is ``None`` then
       :attr:`proxytype._exposed_` is used instead if it exists.)  In the case
       where no exposed list is specified, all "public methods" of the shared
       object will be accessible.  (Here a "public method" means any attribute
@@ -1853,25 +1855,30 @@
    callbacks and has a parallel map implementation.
 
    *processes* is the number of worker processes to use.  If *processes* is
-   ``None`` then the number returned by :func:`os.cpu_count` is used.  If
-   *initializer* is not ``None`` then each worker process will call
+   ``None`` then the number returned by :func:`os.cpu_count` is used.
+
+   If *initializer* is not ``None`` then each worker process will call
    ``initializer(*initargs)`` when it starts.
 
+   *maxtasksperchild* is the number of tasks a worker process can complete
+   before it will exit and be replaced with a fresh worker process, to enable
+   unused resources to be freed. The default *maxtasksperchild* is None, which
+   means worker processes will live as long as the pool.
+
+   *context* can be used to specify the context used for starting
+   the worker processes.  Usually a pool is created using the
+   function :func:`multiprocessing.Pool` or the :meth:`Pool` method
+   of a context object.  In both cases *context* is set
+   appropriately.
+
    Note that the methods of the pool object should only be called by
    the process which created the pool.
 
    .. versionadded:: 3.2
-      *maxtasksperchild* is the number of tasks a worker process can complete
-      before it will exit and be replaced with a fresh worker process, to enable
-      unused resources to be freed. The default *maxtasksperchild* is None, which
-      means worker processes will live as long as the pool.
+      *maxtasksperchild*
 
    .. versionadded:: 3.4
-      *context* can be used to specify the context used for starting
-      the worker processes.  Usually a pool is created using the
-      function :func:`multiprocessing.Pool` or the :meth:`Pool` method
-      of a context object.  In both cases *context* is set
-      appropriately.
+      *context*
 
    .. note::
 
diff --git a/Doc/library/operator.rst b/Doc/library/operator.rst
index fa3bcdd..3bcbaa4 100644
--- a/Doc/library/operator.rst
+++ b/Doc/library/operator.rst
@@ -240,9 +240,9 @@
 
 .. function:: length_hint(obj, default=0)
 
-   Return an estimated length for the object *o*. First trying to return its
+   Return an estimated length for the object *o*. First try to return its
    actual length, then an estimate using :meth:`object.__length_hint__`, and
-   finally returning the default value.
+   finally return the default value.
 
    .. versionadded:: 3.4
 
diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index 269856c..3771ab0 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -193,11 +193,17 @@
 
 .. function:: ismount(path)
 
-   Return ``True`` if pathname *path* is a :dfn:`mount point`: a point in a file
-   system where a different file system has been mounted.  The function checks
-   whether *path*'s parent, :file:`path/..`, is on a different device than *path*,
-   or whether :file:`path/..` and *path* point to the same i-node on the same
-   device --- this should detect mount points for all Unix and POSIX variants.
+   Return ``True`` if pathname *path* is a :dfn:`mount point`: a point in a
+   file system where a different file system has been mounted.  On POSIX, the
+   function checks whether *path*'s parent, :file:`path/..`, is on a different
+   device than *path*, or whether :file:`path/..` and *path* point to the same
+   i-node on the same device --- this should detect mount points for all Unix
+   and POSIX variants.  On Windows, a drive letter root and a share UNC are
+   always mount points, and for any other path ``GetVolumePathName`` is called
+   to see if it is different from the input path.
+
+   .. versionadded:: 3.4
+      Support for detecting non-root mount points on Windows.
 
 
 .. function:: join(path1[, path2[, ...]])
@@ -251,7 +257,7 @@
 .. function:: samefile(path1, path2)
 
    Return ``True`` if both pathname arguments refer to the same file or directory.
-   On Unix, this is determined by the device number and i-node number and raises an
+   This is determined by the device number and i-node number and raises an
    exception if a :func:`os.stat` call on either pathname fails.
 
    Availability: Unix, Windows.
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 1fc8de9..f50e5d9 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -260,7 +260,9 @@
 
    Availability: Unix.
 
-   .. note:: On Mac OS X, :func:`getgroups` behavior differs somewhat from
+   .. note::
+
+      On Mac OS X, :func:`getgroups` behavior differs somewhat from
       other Unix platforms. If the Python interpreter was built with a
       deployment target of :const:`10.5` or earlier, :func:`getgroups` returns
       the list of effective group ids associated with the current user process;
@@ -940,8 +942,9 @@
    the C library.
 
    .. versionchanged:: 3.4
-      Add :data:`O_TMPFILE` constant. It's only available on Linux Kernel 3.11
-      or newer.
+      Add :data:`O_PATH` on systems that support it.
+      Add :data:`O_TMPFILE`, only available on Linux Kernel 3.11
+        or newer.
 
 
 .. function:: openpty()
@@ -2653,7 +2656,7 @@
    Fork a child process.  Return ``0`` in the child and the child's process id in the
    parent.  If an error occurs :exc:`OSError` is raised.
 
-   Note that some platforms including FreeBSD <= 6.3, Cygwin and OS/2 EMX have
+   Note that some platforms including FreeBSD <= 6.3 and Cygwin have
    known issues when using fork() from a thread.
 
    .. warning::
@@ -2899,7 +2902,6 @@
    :manpage:`times(2)` or the corresponding Windows Platform API documentation.
    On Windows, only :attr:`user` and :attr:`system` are known; the other
    attributes are zero.
-   On OS/2, only :attr:`elapsed` is known; the other attributes are zero.
 
    Availability: Unix, Windows.
 
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 3aa9d4b..ec1dc4f 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -522,6 +522,36 @@
       ValueError: '/etc/passwd' does not start with '/usr'
 
 
+.. method:: PurePath.with_name(name)
+
+   Return a new path with the :attr:`name` changed.  If the original path
+   doesn't have a name, ValueError is raised::
+
+      >>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
+      >>> p.with_name('setup.py')
+      PureWindowsPath('c:/Downloads/setup.py')
+      >>> p = PureWindowsPath('c:/')
+      >>> p.with_name('setup.py')
+      Traceback (most recent call last):
+        File "<stdin>", line 1, in <module>
+        File "/home/antoine/cpython/default/Lib/pathlib.py", line 751, in with_name
+          raise ValueError("%r has an empty name" % (self,))
+      ValueError: PureWindowsPath('c:/') has an empty name
+
+
+.. method:: PurePath.with_suffix(suffix)
+
+   Return a new path with the :attr:`suffix` changed.  If the original path
+   doesn't have a suffix, the new *suffix* is appended instead::
+
+      >>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
+      >>> p.with_suffix('.bz2')
+      PureWindowsPath('c:/Downloads/pathlib.tar.bz2')
+      >>> p = PureWindowsPath('README')
+      >>> p.with_suffix('.txt')
+      PureWindowsPath('README.txt')
+
+
 .. _concrete-paths:
 
 
diff --git a/Doc/library/pkgutil.rst b/Doc/library/pkgutil.rst
index 10b7848..13ea7b9 100644
--- a/Doc/library/pkgutil.rst
+++ b/Doc/library/pkgutil.rst
@@ -147,6 +147,7 @@
    *prefix* is a string to output on the front of every module name on output.
 
    .. note::
+
       Only works for a :term:`finder` which defines an ``iter_modules()``
       method. This interface is non-standard, so the module also provides
       implementations for :class:`importlib.machinery.FileFinder` and
@@ -185,6 +186,7 @@
       walk_packages(ctypes.__path__, ctypes.__name__ + '.')
 
    .. note::
+
       Only works for a :term:`finder` which defines an ``iter_modules()``
       method. This interface is non-standard, so the module also provides
       implementations for :class:`importlib.machinery.FileFinder` and
diff --git a/Doc/library/plistlib.rst b/Doc/library/plistlib.rst
index 7301d49..6a2d6b4 100644
--- a/Doc/library/plistlib.rst
+++ b/Doc/library/plistlib.rst
@@ -32,6 +32,9 @@
 (but only with string keys), :class:`Data`, :class:`bytes`, :class:`bytesarray`
 or :class:`datetime.datetime` objects.
 
+.. versionchanged:: 3.4
+   New API, old API deprecated.  Support for binary format plists added.
+
 .. seealso::
 
    `PList manual page <http://developer.apple.com/documentation/Darwin/Reference/ManPages/man5/plist.5.html>`_
@@ -107,7 +110,7 @@
    An :exc:`OverflowError` will be raised for integer values that cannot
    be represented in (binary) plist files.
 
-   .. versionadded: 3.4
+   .. versionadded:: 3.4
 
 
 .. function:: dumps(value, \*, fmt=FMT_XML, sort_keys=True, skipkeys=False)
@@ -116,7 +119,7 @@
    the documentation for :func:`dump` for an explanation of the keyword
    arguments of this function.
 
-   .. versionadded: 3.4
+   .. versionadded:: 3.4
 
 The following functions are deprecated:
 
@@ -135,7 +138,7 @@
       to ``__getitem_``. This means that you can use attribute access to
       access items of these dictionaries.
 
-   .. deprecated: 3.4 Use :func:`load` instead.
+   .. deprecated:: 3.4 Use :func:`load` instead.
 
 
 .. function:: writePlist(rootObject, pathOrFile)
@@ -143,7 +146,7 @@
    Write *rootObject* to an XML plist file. *pathOrFile* may be either a file name
    or a (writable and binary) file object
 
-   .. deprecated: 3.4 Use :func:`dump` instead.
+   .. deprecated:: 3.4 Use :func:`dump` instead.
 
 
 .. function:: readPlistFromBytes(data)
@@ -194,7 +197,7 @@
    .. deprecated:: 3.4 Use a :class:`bytes` object instead
 
 
-The following constants are avaiable:
+The following constants are available:
 
 .. data:: FMT_XML
 
diff --git a/Doc/library/pydoc.rst b/Doc/library/pydoc.rst
index e100865..3f520e8 100644
--- a/Doc/library/pydoc.rst
+++ b/Doc/library/pydoc.rst
@@ -84,3 +84,8 @@
 
 .. versionchanged:: 3.2
    Added the ``-b`` option, deprecated the ``-g`` option.
+
+.. versionchanged:: 3.4
+   :mod:`pydoc` now uses :func:`inspect.signature` rather than
+   :func:`inspect.getfullargspec` to extract signature information from
+   callables.
diff --git a/Doc/library/site.rst b/Doc/library/site.rst
index d93e938..2fdf303 100644
--- a/Doc/library/site.rst
+++ b/Doc/library/site.rst
@@ -123,9 +123,13 @@
 configure the :mod:`rlcompleter` module, if Python is started in
 :ref:`interactive mode <tut-interactive>` and without the :option:`-S` option.
 The default behavior is enable tab-completion and to use
-:file:`~/.python_history` as the history save file.  To disable it, override
-the :data:`sys.__interactivehook__` attribute in your :mod:`sitecustomize`
-or :mod:`usercustomize` module or your :envvar:`PYTHONSTARTUP` file.
+:file:`~/.python_history` as the history save file.  To disable it, delete (or
+override) the :data:`sys.__interactivehook__` attribute in your
+:mod:`sitecustomize` or :mod:`usercustomize` module or your
+:envvar:`PYTHONSTARTUP` file.
+
+.. versionchanged:: 3.4
+   Activation of rlcompleter and history was made automatic.
 
 
 Module contents
diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst
index eba8ae9..ec8dc9d 100644
--- a/Doc/library/smtplib.rst
+++ b/Doc/library/smtplib.rst
@@ -117,6 +117,9 @@
    Subclass of :exc:`OSError` that is the base exception class for all
    the other exceptions provided by this module.
 
+   .. versionchanged:: 3.4
+      SMTPException became subclass of :exc:`OSError`
+
 
 .. exception:: SMTPServerDisconnected
 
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index c2e9f00..54c6bad 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -6,8 +6,7 @@
 
 
 This module provides access to the BSD *socket* interface. It is available on
-all modern Unix systems, Windows, MacOS, OS/2, and probably additional
-platforms.
+all modern Unix systems, Windows, MacOS, and probably additional platforms.
 
 .. note::
 
@@ -468,7 +467,7 @@
        (10, 1, 6, '', ('2001:888:2000:d::a2', 80, 0, 0))]
 
    .. versionchanged:: 3.2
-      parameters can now be passed as single keyword arguments.
+      parameters can now be passed using keyword arguments.
 
 .. function:: getfqdn([name])
 
@@ -634,6 +633,9 @@
 
    Availability: Unix (maybe not all platforms), Windows.
 
+   .. versionchanged:: 3.4
+      Windows support added
+
 
 .. function:: inet_ntop(address_family, packed_ip)
 
@@ -650,6 +652,9 @@
 
    Availability: Unix (maybe not all platforms), Windows.
 
+   .. versionchanged:: 3.4
+      Windows support added
+
 
 ..
    XXX: Are sendmsg(), recvmsg() and CMSG_*() available on any
@@ -794,6 +799,7 @@
    :keyword:`with` statement around them.
 
    .. note::
+
       :meth:`close()` releases the resource associated with a connection but
       does not necessarily close the connection immediately.  If you want
       to close the connection in a timely fashion, call :meth:`shutdown()`
@@ -1512,4 +1518,3 @@
    details of socket semantics.  For Unix, refer to the manual pages; for Windows,
    see the WinSock (or Winsock 2) specification.  For IPv6-ready APIs, readers may
    want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv6.
-
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index 76bb432..0ed5fb2 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -818,6 +818,7 @@
        'version': 3}
 
    .. note::
+
       To validate a certificate for a particular service, you can use the
       :func:`match_hostname` function.
 
@@ -841,10 +842,8 @@
 
    .. versionchanged:: 3.4
       :exc:`ValueError` is raised when the handshake isn't done.
-
-   .. versionchanged:: 3.4
       The returned dictionary includes additional X509v3 extension items
-      such as ``crlDistributionPoints``, ``caIssuers`` and ``OCSP`` URIs.
+        such as ``crlDistributionPoints``, ``caIssuers`` and ``OCSP`` URIs.
 
 .. method:: SSLSocket.cipher()
 
diff --git a/Doc/library/stringprep.rst b/Doc/library/stringprep.rst
index 47144a6..fc890cb 100644
--- a/Doc/library/stringprep.rst
+++ b/Doc/library/stringprep.rst
@@ -3,7 +3,6 @@
 
 .. module:: stringprep
    :synopsis: String preparation, as per RFC 3453
-   :deprecated:
 .. moduleauthor:: Martin v. Löwis <martin@v.loewis.de>
 .. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
 
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index d2893b6..cdcbe82 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -629,6 +629,12 @@
    :exc:`TimeoutExpired` exception.  It is safe to catch this exception and
    retry the wait.
 
+   .. note::
+
+      The function is implemented using a busy loop (non-blocking call and
+      short sleeps). Use the :mod:`asyncio` module for an asynchronous wait:
+      see :class:`asyncio.create_subprocess_exec`.
+
    .. warning::
 
       This will deadlock when using ``stdout=PIPE`` and/or
@@ -639,6 +645,11 @@
    .. versionchanged:: 3.3
       *timeout* was added.
 
+   .. deprecated:: 3.4
+
+      Do not use the undocumented *endtime* parameter.  It is was
+      unintentionally exposed in 3.3 but was intended to be private
+      for internal use.  Use *timeout* instead.
 
 .. method:: Popen.communicate(input=None, timeout=None)
 
@@ -1080,8 +1091,10 @@
       >>> subprocess.getstatusoutput('/bin/junk')
       (256, 'sh: /bin/junk: not found')
 
-   .. versionchanged:: 3.3
-      Availability: Unix & Windows
+   Availability: Unix & Windows
+
+   .. versionchanged:: 3.3.4
+      Windows support added
 
 
 .. function:: getoutput(cmd)
@@ -1094,8 +1107,10 @@
       >>> subprocess.getoutput('ls /bin/ls')
       '/bin/ls'
 
-   .. versionchanged:: 3.3
-      Availability: Unix & Windows
+   Availability: Unix & Windows
+
+   .. versionchanged:: 3.3.4
+      Windows support added
 
 
 Notes
diff --git a/Doc/library/sunau.rst b/Doc/library/sunau.rst
index 15c06b5..a94ae08 100644
--- a/Doc/library/sunau.rst
+++ b/Doc/library/sunau.rst
@@ -251,7 +251,7 @@
    Write audio frames, without correcting *nframes*.
 
    .. versionchanged:: 3.4
-      Any :term:`bytes-like object`\ s are now accepted.
+      Any :term:`bytes-like object` is now accepted.
 
 
 .. method:: AU_write.writeframes(data)
@@ -259,7 +259,7 @@
    Write audio frames and make sure *nframes* is correct.
 
    .. versionchanged:: 3.4
-      Any :term:`bytes-like object`\ s are now accepted.
+      Any :term:`bytes-like object` is now accepted.
 
 
 .. method:: AU_write.close()
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 5ff7178..e3cc866 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -227,7 +227,9 @@
    installed in :file:`{exec_prefix}/lib/python{X.Y}/lib-dynload`, where *X.Y*
    is the version number of Python, for example ``3.2``.
 
-   .. note:: If a :ref:`virtual environment <venv-def>` is in effect, this
+   .. note::
+
+      If a :ref:`virtual environment <venv-def>` is in effect, this
       value will be changed in ``site.py`` to point to the virtual environment.
       The value for the Python installation will still be available, via
       :data:`base_exec_prefix`.
@@ -692,10 +694,11 @@
 
 .. data:: __interactivehook__
 
-   When present, this function is automatically called (with no arguments)
-   when the interpreter is launched in :ref:`interactive mode <tut-interactive>`.
-   This is done after the :envvar:`PYTHONSTARTUP` file is read, so that you
-   can set this hook there.
+   When this attribute exists, its value is automatically called (with no
+   arguments) when the interpreter is launched in :ref:`interactive mode
+   <tut-interactive>`.  This is done after the :envvar:`PYTHONSTARTUP` file is
+   read, so that you can set this hook there.  The :mod:`site` module
+   :ref:`sets this <rlcompleter-config>`.
 
    .. versionadded:: 3.4
 
diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index 2c51549..83026d8 100644
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -199,6 +199,7 @@
 test suite.
 
 .. note::
+
    :mod:`test.support` is not a public module.  It is documented here to help
    Python developers write tests.  The API of this module is subject to change
    without backwards compatibility concerns between releases.
diff --git a/Doc/library/textwrap.rst b/Doc/library/textwrap.rst
index 1ba42a3..edf1fd6 100644
--- a/Doc/library/textwrap.rst
+++ b/Doc/library/textwrap.rst
@@ -40,13 +40,14 @@
    :func:`wrap`.
 
 
-.. function:: shorten(text, width=70, *, placeholder=" [...]")
+.. function:: shorten(text, width, **kwargs)
 
-   Collapse and truncate the given text to fit in the given width.
+   Collapse and truncate the given *text* to fit in the given *width*.
 
-   The text first has its whitespace collapsed.  If it then fits in
-   the *width*, it is returned unchanged.  Otherwise, as many words
-   as possible are joined and then the *placeholder* is appended::
+   First the whitespace in *text* is collapsed (all whitespace is replaced by
+   single spaces).  If the result fits in the *width*, it is returned.
+   Otherwise, enough words are dropped from the end so that the remaining words
+   plus the :attr:`placeholder` fit within :attr:`width`::
 
       >>> textwrap.shorten("Hello  world!", width=12)
       'Hello world!'
@@ -55,6 +56,12 @@
       >>> textwrap.shorten("Hello world", width=10, placeholder="...")
       'Hello...'
 
+   Optional keyword arguments correspond to the instance attributes of
+   :class:`TextWrapper`, documented below.  Note that the whitespace is
+   collapsed before the text is passed to the :class:`TextWrapper` :meth:`fill`
+   function, so changing the value of :attr:`.tabsize`, :attr:`.expand_tabs`,
+   :attr:`.drop_whitespace`, and :attr:`.replace_whitespace` will have no effect.
+
    .. versionadded:: 3.4
 
 
@@ -110,8 +117,8 @@
 :func:`wrap`, :func:`fill` and :func:`shorten` work by creating a
 :class:`TextWrapper` instance and calling a single method on it.  That
 instance is not reused, so for applications that process many text
-strings, it may be more efficient to create your own
-:class:`TextWrapper` object.
+strings using :func:`wrap` and/or :func:`fill`, it may be more efficient to
+create your own :class:`TextWrapper` object.
 
 Text is preferably wrapped on whitespaces and right after the hyphens in
 hyphenated words; only then will long words be broken if necessary, unless
@@ -252,16 +259,16 @@
 
    .. attribute:: max_lines
 
-      (default: ``None``) If not ``None``, then the text be will truncated to
-      *max_lines* lines.
+      (default: ``None``) If not ``None``, then the output will contain at most
+      *max_lines* lines, with *placeholder* appearing at the end of the output.
 
       .. versionadded:: 3.4
 
 
    .. attribute:: placeholder
 
-      (default: ``' [...]'``) String that will be appended to the last line of
-      text if it will be truncated.
+      (default: ``' [...]'``) String that will appear at the end of the output
+      text if it has been truncated.
 
       .. versionadded:: 3.4
 
diff --git a/Doc/library/tracemalloc.rst b/Doc/library/tracemalloc.rst
index c12ef87..3405518 100644
--- a/Doc/library/tracemalloc.rst
+++ b/Doc/library/tracemalloc.rst
@@ -184,6 +184,7 @@
 Code to display the 10 lines allocating the most memory with a pretty output,
 ignoring ``<frozen importlib._bootstrap>`` and ``<unknown>`` files::
 
+    import linecache
     import os
     import tracemalloc
 
@@ -201,6 +202,9 @@
             filename = os.sep.join(frame.filename.split(os.sep)[-2:])
             print("#%s: %s:%s: %.1f KiB"
                   % (index, filename, frame.lineno, stat.size / 1024))
+            line = linecache.getline(frame.filename, frame.lineno).strip()
+            if line:
+                print('    %s' % line)
 
         other = top_stats[limit:]
         if other:
@@ -218,19 +222,28 @@
 
 Example of output of the Python test suite::
 
-    2013-11-08 14:16:58.149320: Top 10 lines
-    #1: collections/__init__.py:368: 291.9 KiB
-    #2: Lib/doctest.py:1291: 200.2 KiB
-    #3: unittest/case.py:571: 160.3 KiB
-    #4: Lib/abc.py:133: 99.8 KiB
-    #5: urllib/parse.py:476: 71.8 KiB
-    #6: <string>:5: 62.7 KiB
-    #7: Lib/base64.py:140: 59.8 KiB
-    #8: Lib/_weakrefset.py:37: 51.8 KiB
-    #9: collections/__init__.py:362: 50.6 KiB
-    #10: test/test_site.py:56: 48.0 KiB
-    7496 other: 4161.9 KiB
-    Total allocated size: 5258.8 KiB
+    Top 10 lines
+    #1: Lib/base64.py:414: 419.8 KiB
+        _b85chars2 = [(a + b) for a in _b85chars for b in _b85chars]
+    #2: Lib/base64.py:306: 419.8 KiB
+        _a85chars2 = [(a + b) for a in _a85chars for b in _a85chars]
+    #3: collections/__init__.py:368: 293.6 KiB
+        exec(class_definition, namespace)
+    #4: Lib/abc.py:133: 115.2 KiB
+        cls = super().__new__(mcls, name, bases, namespace)
+    #5: unittest/case.py:574: 103.1 KiB
+        testMethod()
+    #6: Lib/linecache.py:127: 95.4 KiB
+        lines = fp.readlines()
+    #7: urllib/parse.py:476: 71.8 KiB
+        for a in _hexdig for b in _hexdig}
+    #8: <string>:5: 62.0 KiB
+    #9: Lib/_weakrefset.py:37: 60.0 KiB
+        self.data = set()
+    #10: Lib/base64.py:142: 59.8 KiB
+        _b32tab2 = [a + b for a in _b32tab for b in _b32tab]
+    6220 other: 3602.8 KiB
+    Total allocated size: 5303.1 KiB
 
 See :meth:`Snapshot.statistics` for more options.
 
diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index c4f57e4..abdb939 100644
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -15,6 +15,9 @@
 Python interpreter, but not exposed as builtins like :class:`int` or
 :class:`str` are.
 
+Finally, it provides some additional type-related utility classes and functions
+that are not fundamental enough to be builtins.
+
 
 Dynamic Type Creation
 ---------------------
@@ -220,6 +223,9 @@
       Return a new view of the underlying mapping's values.
 
 
+Additional Utility Classes and Functions
+----------------------------------------
+
 .. class:: SimpleNamespace
 
    A simple :class:`object` subclass that provides attribute access to its
@@ -246,3 +252,18 @@
    instead.
 
    .. versionadded:: 3.3
+
+
+.. function:: DynamicClassAttribute(fget=None, fset=None, fdel=None, doc=None)
+
+   Route attribute access on a class to __getattr__.
+
+   This is a descriptor, used to define attributes that act differently when
+   accessed through an instance and through a class.  Instance access remains
+   normal, but access to an attribute through a class will be routed to the
+   class's __getattr__ method; this is done by raising AttributeError.
+
+   This allows one to have properties active on an instance, and have virtual
+   attributes on the class with the same name (see Enum for an example).
+
+   .. versionadded:: 3.4
diff --git a/Doc/library/undoc.rst b/Doc/library/undoc.rst
index 80386d2..20830e2 100644
--- a/Doc/library/undoc.rst
+++ b/Doc/library/undoc.rst
@@ -20,7 +20,7 @@
 documented beyond this mention.  There's little need to document these.
 
 :mod:`ntpath`
-   --- Implementation of :mod:`os.path` on Win32, Win64, WinCE, and OS/2 platforms.
+   --- Implementation of :mod:`os.path` on Win32, Win64, and WinCE platforms.
 
 :mod:`posixpath`
    --- Implementation of :mod:`os.path` on POSIX.
diff --git a/Doc/library/unittest.mock-examples.rst b/Doc/library/unittest.mock-examples.rst
index 98bfcc5..c5fa365 100644
--- a/Doc/library/unittest.mock-examples.rst
+++ b/Doc/library/unittest.mock-examples.rst
@@ -426,7 +426,7 @@
 
 As an alternative `patch`, `patch.object` and `patch.dict` can be used as
 class decorators. When used in this way it is the same as applying the
-decorator indvidually to every method whose name starts with "test".
+decorator individually to every method whose name starts with "test".
 
 
 .. _further-examples:
diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index b5cf7b5..cb72a68 100644
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -958,7 +958,7 @@
 
 .. [#] The only exceptions are magic methods and attributes (those that have
        leading and trailing double underscores). Mock doesn't create these but
-       instead of raises an ``AttributeError``. This is because the interpreter
+       instead raises an ``AttributeError``. This is because the interpreter
        will often implicitly request these methods, and gets *very* confused to
        get a new Mock object when it expects a magic method. If you need magic
        method support see :ref:`magic methods <magic-methods>`.
@@ -1509,7 +1509,7 @@
 Both patch_ and patch.object_ correctly patch and restore descriptors: class
 methods, static methods and properties. You should patch these on the *class*
 rather than an instance. They also work with *some* objects
-that proxy attribute access, like the `django setttings object
+that proxy attribute access, like the `django settings object
 <http://www.voidspace.org.uk/python/weblog/arch_d7_2010_12_04.shtml#e1198>`_.
 
 
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index 6ec3609..690c98b 100644
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -239,9 +239,10 @@
 
 Unittest supports simple test discovery. In order to be compatible with test
 discovery, all of the test files must be :ref:`modules <tut-modules>` or
-:ref:`packages <tut-packages>` importable from the top-level directory of
-the project (this means that their filenames must be valid
-:ref:`identifiers <identifiers>`).
+:ref:`packages <tut-packages>` (including :term:`namespace packages
+<namespace package>`) importable from the top-level directory of
+the project (this means that their filenames must be valid :ref:`identifiers
+<identifiers>`).
 
 Test discovery is implemented in :meth:`TestLoader.discover`, but can also be
 used from the command line. The basic command-line usage is::
@@ -306,6 +307,9 @@
 Test modules and packages can customize test loading and discovery by through
 the `load_tests protocol`_.
 
+.. versionchanged:: 3.4
+   Test discovery supports :term:`namespace packages <namespace package>`.
+
 
 .. _organizing-tests:
 
@@ -1620,11 +1624,11 @@
 
    .. method:: discover(start_dir, pattern='test*.py', top_level_dir=None)
 
-      Find and return all test modules from the specified start directory,
-      recursing into subdirectories to find them. Only test files that match
-      *pattern* will be loaded. (Using shell style pattern matching.) Only
-      module names that are importable (i.e. are valid Python identifiers) will
-      be loaded.
+      Find all the test modules by recursing into subdirectories from the
+      specified start directory, and return a TestSuite object containing them.
+      Only test files that match *pattern* will be loaded. (Using shell style
+      pattern matching.) Only module names that are importable (i.e. are valid
+      Python identifiers) will be loaded.
 
       All test modules must be importable from the top level of the project. If
       the start directory is not the top level directory then the top level
@@ -1654,12 +1658,11 @@
 
       .. versionchanged:: 3.4
          Modules that raise :exc:`SkipTest` on import are recorded as skips,
-         not errors.
-
-      .. versionchanged:: 3.4
-         Paths are sorted before being imported to ensure execution order for a
-         given test suite is the same even if the underlying file system's ordering
-         is not dependent on file name like in ext3/4.
+           not errors.
+         Discovery works for :term:`namespace packages <namespace package>`.
+         Paths are sorted before being imported so that execution order is
+           the same even if the underlying file system's ordering is not
+           dependent on file name.
 
 
    The following attributes of a :class:`TestLoader` can be configured either by
diff --git a/Doc/library/urllib.error.rst b/Doc/library/urllib.error.rst
index 9fb58f5..f7f0c97 100644
--- a/Doc/library/urllib.error.rst
+++ b/Doc/library/urllib.error.rst
@@ -48,7 +48,7 @@
 
    .. attribute:: headers
 
-      The HTTP response headers for the HTTP request that cause the
+      The HTTP response headers for the HTTP request that caused the
       :exc:`HTTPError`.
 
       .. versionadded:: 3.4
diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
index 20449d9..6ac9081 100644
--- a/Doc/library/urllib.request.rst
+++ b/Doc/library/urllib.request.rst
@@ -218,7 +218,7 @@
    fetching of the image, this should be true.
 
    *method* should be a string that indicates the HTTP request method that
-   will be used (e.g. ``'HEAD'``).  Its value is stored in the
+   will be used (e.g. ``'HEAD'``).  If provided, its value is stored in the
    :attr:`~Request.method` attribute and is used by :meth:`get_method()`.
    Subclasses may indicate a default method by setting the
    :attr:`~Request.method` attribute in the class itself.
@@ -440,13 +440,20 @@
 
 .. attribute:: Request.method
 
-   The HTTP request method to use.  This value is used by
-   :meth:`~Request.get_method` to override the computed HTTP request
-   method that would otherwise be returned.  This attribute is initialized with
-   the value of the *method* argument passed to the constructor.
+   The HTTP request method to use.  By default its value is :const:`None`,
+   which means that :meth:`~Request.get_method` will do its normal computation
+   of the method to be used.  Its value can be set (thus overriding the default
+   computation in :meth:`~Request.get_method`) either by providing a default
+   value by setting it at the class level in a :class:`Request` subclass, or by
+   passing a value in to the :class:`Request` constructor via the *method*
+   argument.
 
    .. versionadded:: 3.3
 
+   .. versionchanged:: 3.4
+      A default value can now be set in subclasses; previously it could only
+      be set via the constructor argument.
+
 
 .. method:: Request.get_method()
 
diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst
index d29a957..e93f48e 100644
--- a/Doc/library/venv.rst
+++ b/Doc/library/venv.rst
@@ -76,6 +76,8 @@
    without there needing to be any reference to its venv in ``PATH``.
 
 
+.. _venv-api:
+
 API
 ---
 
diff --git a/Doc/library/wave.rst b/Doc/library/wave.rst
index c32e1fc..ab64978 100644
--- a/Doc/library/wave.rst
+++ b/Doc/library/wave.rst
@@ -150,14 +150,30 @@
 Wave_write Objects
 ------------------
 
+For seekable output streams, the ``wave`` header will automatically be updated
+to reflect the number of frames actually written.  For unseekable streams, the
+*nframes* value must be accurate when the first frame data is written.  An
+accurate *nframes* value can be achieved either by calling
+:meth:`~Wave_write.setnframes` or :meth:`~Wave_write.setparams` with the number
+of frames that will be written before :meth:`~Wave_write.close` is called and
+then using :meth:`~Wave_write.writeframesraw` to write the frame data, or by
+calling :meth:`~Wave_write.writeframes` with all of the frame data to be
+written.  In the latter case :meth:`~Wave_write.writeframes` will calculate
+the number of frames in the data and set *nframes* accordingly before writing
+the frame data.
+
 Wave_write objects, as returned by :func:`.open`, have the following methods:
 
+.. versionchanged:: 3.4
+   Added support for unseekable files.
+
 
 .. method:: Wave_write.close()
 
    Make sure *nframes* is correct, and close the file if it was opened by
-   :mod:`wave`.  This method is called upon object collection. Can raise an
-   exception if *nframes* is not correct and a file is not seekable.
+   :mod:`wave`.  This method is called upon object collection.  It will raise
+   an exception if the output stream is not seekable and *nframes* does not
+   match the number of frames actually written.
 
 
 .. method:: Wave_write.setnchannels(n)
@@ -181,8 +197,9 @@
 
 .. method:: Wave_write.setnframes(n)
 
-   Set the number of frames to *n*. This will be changed later if more frames are
-   written.
+   Set the number of frames to *n*.  This will be changed later if the number
+   of frames actually written is different (this update attempt will
+   raise an error if the output stream is not seekable).
 
 
 .. method:: Wave_write.setcomptype(type, name)
@@ -209,16 +226,18 @@
    Write audio frames, without correcting *nframes*.
 
    .. versionchanged:: 3.4
-      Any :term:`bytes-like object`\ s are now accepted.
+      Any :term:`bytes-like object` is now accepted.
 
 
 .. method:: Wave_write.writeframes(data)
 
-   Write audio frames and make sure *nframes* is correct. Can raise an
-   exception if a file is not seekable.
+   Write audio frames and make sure *nframes* is correct.  It will raise an
+   error if the output stream is not seekable and the total number of frames
+   that have been written after *data* has been written does not match the
+   previously set value for *nframes*.
 
    .. versionchanged:: 3.4
-      Any :term:`bytes-like object`\ s are now accepted.
+      Any :term:`bytes-like object` is now accepted.
 
 
 Note that it is invalid to set any parameters after calling :meth:`writeframes`
diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
index dfa2b71..c6dbce0 100644
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -952,7 +952,8 @@
    specified in the XML file.
 
    .. deprecated:: 3.4
-      The *html* argument.
+      The *html* argument.  The remaining arguments should be passed via
+      keywword to prepare for the removal of the *html* argument.
 
    .. method:: close()
 
diff --git a/Doc/library/xml.rst b/Doc/library/xml.rst
index f793bae..0188219 100644
--- a/Doc/library/xml.rst
+++ b/Doc/library/xml.rst
@@ -14,9 +14,9 @@
 .. warning::
 
    The XML modules are not secure against erroneous or maliciously
-   constructed data.  If you need to parse untrusted or unauthenticated data see
-   :ref:`xml-vulnerabilities`.
-
+   constructed data.  If you need to parse untrusted or
+   unauthenticated data see the :ref:`xml-vulnerabilities` and
+   :ref:`defused-packages` sections.
 
 It is important to note that modules in the :mod:`xml` package require that
 there be at least one SAX-compliant XML parser available. The Expat parser is
@@ -46,16 +46,15 @@
 .. _xml-vulnerabilities:
 
 XML vulnerabilities
-===================
+-------------------
 
 The XML processing modules are not secure against maliciously constructed data.
-An attacker can abuse vulnerabilities for e.g. denial of service attacks, to
-access local files, to generate network connections to other machines, or
-to or circumvent firewalls. The attacks on XML abuse unfamiliar features
-like inline `DTD`_ (document type definition) with entities.
+An attacker can abuse XML features to carry out denial of service attacks,
+access local files, generate network connections to other machines, or
+circumvent firewalls.
 
-The following table gives an overview of the known attacks and if the various
-modules are vulnerable to them.
+The following table gives an overview of the known attacks and whether
+the various modules are vulnerable to them.
 
 =========================  ========  =========  =========  ========  =========
 kind                       sax       etree      minidom    pulldom   xmlrpc
@@ -68,7 +67,7 @@
 =========================  ========  =========  =========  ========  =========
 
 1. :mod:`xml.etree.ElementTree` doesn't expand external entities and raises a
-   ParserError when an entity occurs.
+   :exc:`ParserError` when an entity occurs.
 2. :mod:`xml.dom.minidom` doesn't expand external entities and simply returns
    the unexpanded entity verbatim.
 3. :mod:`xmlrpclib` doesn't expand external entities and omits them.
@@ -77,23 +76,21 @@
 billion laughs / exponential entity expansion
   The `Billion Laughs`_ attack -- also known as exponential entity expansion --
   uses multiple levels of nested entities. Each entity refers to another entity
-  several times, the final entity definition contains a small string. Eventually
-  the small string is expanded to several gigabytes. The exponential expansion
-  consumes lots of CPU time, too.
+  several times, and the final entity definition contains a small string.
+  The exponential expansion results in several gigabytes of text and
+  consumes lots of memory and CPU time.
 
 quadratic blowup entity expansion
   A quadratic blowup attack is similar to a `Billion Laughs`_ attack; it abuses
   entity expansion, too. Instead of nested entities it repeats one large entity
   with a couple of thousand chars over and over again. The attack isn't as
-  efficient as the exponential case but it avoids triggering countermeasures of
-  parsers against heavily nested entities.
+  efficient as the exponential case but it avoids triggering parser countermeasures
+  that forbid deeply-nested entities.
 
 external entity expansion
   Entity declarations can contain more than just text for replacement. They can
-  also point to external resources by public identifiers or system identifiers.
-  System identifiers are standard URIs or can refer to local files. The XML
-  parser retrieves the resource with e.g. HTTP or FTP requests and embeds the
-  content into the XML document.
+  also point to external resources or local files. The XML
+  parser accesses the resource and embeds the content into the XML document.
 
 DTD retrieval
   Some XML libraries like Python's :mod:`xml.dom.pulldom` retrieve document type
@@ -101,31 +98,32 @@
   implications as the external entity expansion issue.
 
 decompression bomb
-  The issue of decompression bombs (aka `ZIP bomb`_) apply to all XML libraries
-  that can parse compressed XML stream like gzipped HTTP streams or LZMA-ed
+  Decompression bombs (aka `ZIP bomb`_) apply to all XML libraries
+  that can parse compressed XML streams such as gzipped HTTP streams or
+  LZMA-compressed
   files. For an attacker it can reduce the amount of transmitted data by three
   magnitudes or more.
 
-The documentation of `defusedxml`_ on PyPI has further information about
+The documentation for `defusedxml`_ on PyPI has further information about
 all known attack vectors with examples and references.
 
-defused packages
-----------------
+.. _defused-packages:
+
+The :mod:`defusedxml` and :mod:`defusedexpat` Packages
+------------------------------------------------------
 
 `defusedxml`_ is a pure Python package with modified subclasses of all stdlib
-XML parsers that prevent any potentially malicious operation. The courses of
-action are recommended for any server code that parses untrusted XML data. The
-package also ships with example exploits and an extended documentation on more
-XML exploits like xpath injection.
+XML parsers that prevent any potentially malicious operation. Use of this
+package is recommended for any server code that parses untrusted XML data. The
+package also ships with example exploits and extended documentation on more
+XML exploits such as XPath injection.
 
-`defusedexpat`_ provides a modified libexpat and patched replacment
-:mod:`pyexpat` extension module with countermeasures against entity expansion
-DoS attacks. Defusedexpat still allows a sane and configurable amount of entity
-expansions. The modifications will be merged into future releases of Python.
-
-The workarounds and modifications are not included in patch releases as they
-break backward compatibility. After all inline DTD and entity expansion are
-well-definied XML features.
+`defusedexpat`_ provides a modified libexpat and a patched
+:mod:`pyexpat` module that have countermeasures against entity expansion
+DoS attacks. The :mod:`defusedexpat` module still allows a sane and configurable amount of entity
+expansions. The modifications may be included in some future release of Python,
+but will not be included in any bugfix releases of
+Python because they break backward compatibility.
 
 
 .. _defusedxml: https://pypi.python.org/pypi/defusedxml/
@@ -133,4 +131,3 @@
 .. _Billion Laughs: http://en.wikipedia.org/wiki/Billion_laughs
 .. _ZIP bomb: http://en.wikipedia.org/wiki/Zip_bomb
 .. _DTD: http://en.wikipedia.org/wiki/Document_Type_Definition
-
diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index 969a536..1d23a7c 100644
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@@ -401,18 +401,32 @@
       ``2``, only files with that optimization level (see :func:`compile`) are
       added to the archive, compiling if necessary.
 
-      If the pathname is a file, the filename must end with :file:`.py`, and
+      If *pathname* is a file, the filename must end with :file:`.py`, and
       just the (corresponding :file:`\*.py[co]`) file is added at the top level
-      (no path information).  If the pathname is a file that does not end with
+      (no path information).  If *pathname* is a file that does not end with
       :file:`.py`, a :exc:`RuntimeError` will be raised.  If it is a directory,
       and the directory is not a package directory, then all the files
       :file:`\*.py[co]` are added at the top level.  If the directory is a
       package directory, then all :file:`\*.py[co]` are added under the package
       name as a file path, and if any subdirectories are package directories,
-      all of these are added recursively.  *basename* is intended for internal
-      use only.  When *filterfunc(pathname)* is given, it will be called for every
-      invocation. When it returns a false value, that path and its subpaths will
-      be ignored.
+      all of these are added recursively.
+
+      *basename* is intended for internal use only.
+
+      *filterfunc*, if given, must be a function taking a single string
+      argument.  It will be passed each path (including each individual full
+      file path) before it is added to the archive.  If *filterfunc* returns a
+      false value, the path will not be added, and if it is a directory its
+      contents will be ignored.  For example, if our test files are all either
+      in ``test`` directories or start with the string ``test_``, we can use a
+      *filterfunc* to exclude them::
+
+          >>> zf = PyZipFile('myprog.zip')
+          >>> def notests(s):
+          ...     fn = os.path.basename(s)
+          ...     return (not (fn == 'test' or fn.startswith('test_')))
+          >>> zf.writepy('myprog', filterfunc=notests)
+
       The :meth:`writepy` method makes archives with file names like
       this::