whatsnew/3.5: Another editing pass

Patch by Elvis Pranskevichus.

2 files changed, 106 insertions, 92 deletions

diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index ff75de1..eb27846 100644
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -86,14 +86,14 @@ Standard names are defined for the following types:
 
 .. data:: GeneratorType
 
-   The type of :term:`generator`-iterator objects, produced by calling a
-   generator function.
+   The type of :term:`generator`-iterator objects, created by
+   generator functions.
 
 
 .. data:: CoroutineType
 
-   The type of :term:`coroutine` objects, produced by calling a
-   function defined with an :keyword:`async def` statement.
+   The type of :term:`coroutine` objects, created by
+   :keyword:`async def` functions.
 
    .. versionadded:: 3.5
 
diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst
index e293ae2..bf2940c 100644
--- a/Doc/whatsnew/3.5.rst
+++ b/Doc/whatsnew/3.5.rst
@@ -178,7 +178,7 @@ Coroutine functions are declared using the new :keyword:`async def` syntax::
     >>> async def coro():
     ...     return 'spam'
 
-Inside a coroutine function, a new :keyword:`await` expression can be used
+Inside a coroutine function, the new :keyword:`await` expression can be used
 to suspend coroutine execution until the result is available.  Any object
 can be *awaited*, as long as it implements the :term:`awaitable` protocol by
 defining the :meth:`__await__` method.
@@ -245,7 +245,7 @@ context managers::
 Note that both :keyword:`async for` and :keyword:`async with` can only
 be used inside a coroutine function declared with :keyword:`async def`.
 
-Coroutine functions are intended to be ran inside a compatible event loop,
+Coroutine functions are intended to be run inside a compatible event loop,
 such as :class:`asyncio.Loop`.
 
 .. seealso::
@@ -627,7 +627,7 @@ argparse
 
 The :class:`~argparse.ArgumentParser` class now allows to disable
 :ref:`abbreviated usage <prefix-matching>` of long options by setting
-:ref:`allow_abbrev` to ``False``. (Contributed by Jonathan Paugh,
+:ref:`allow_abbrev` to ``False``.  (Contributed by Jonathan Paugh,
 Steven Bethard, paul j3 and Daniel Eriksson in :issue:`14910`.)
 
 
@@ -649,7 +649,7 @@ protocol.  (Contributed by Berker Peksag in :issue:`20289`.)
 cmath
 -----
 
-A new function :func:`cmath.isclose` provides a way to test for approximate
+A new function :func:`~cmath.isclose` provides a way to test for approximate
 equality. (Contributed by Chris Barker and Tal Einat in :issue:`24270`.)
 
 
@@ -695,7 +695,7 @@ collections.abc
 A new :class:`~collections.abc.Generator` abstract base class. (Contributed
 by Stefan Behnel in :issue:`24018`.)
 
-A new :class:`~collections.abc.Coroutine`,
+New :class:`~collections.abc.Coroutine`,
 :class:`~collections.abc.AsyncIterator`, and
 :class:`~collections.abc.AsyncIterable` abstract base classes.
 (Contributed by Yury Selivanov in :issue:`24184`.)
@@ -721,8 +721,8 @@ concurrent.futures
 ------------------
 
 The :meth:`Executor.map <concurrent.futures.Executor.map>` method now accepts a
-*chunksize* argument to allow batching of tasks in child processes and improve
-performance of :meth:`~concurrent.futures.ProcessPoolExecutor`.
+*chunksize* argument to allow batching of tasks to improve performance when
+:meth:`~concurrent.futures.ProcessPoolExecutor` is used.
 (Contributed by Dan O'Reilly in :issue:`11271`.)
 
 
@@ -739,28 +739,30 @@ don't provide any options to redirect it.  (Contributed by Berker Peksag in
 curses
 ------
 
-The new :func:`~curses.update_lines_cols` function updates the variables
-:data:`curses.LINES` and :data:`curses.COLS`.
+The new :func:`~curses.update_lines_cols` function updates :envvar:`LINES`
+and :envvar:`COLS` environment variables.  This is useful for detecting
+manual screen resize.  (Contributed by Arnon Yaari in :issue:`4254`.)
 
 
 difflib
 -------
 
-The charset of the HTML document generated by
+The charset of HTML documents generated by
 :meth:`HtmlDiff.make_file <difflib.HtmlDiff.make_file>`
-can now be customized by using *charset* keyword-only parameter.  The default
-charset of HTML document changed from ``"ISO-8859-1"`` to ``"utf-8"``.
+can now be customized by using a new *charset* keyword-only argument.
+The default charset of HTML document changed from ``"ISO-8859-1"``
+to ``"utf-8"``.
 (Contributed by Berker Peksag in :issue:`2052`.)
 
-It is now possible to compare lists of byte strings with the
-:func:`~difflib.diff_bytes` function.  This fixes a regression from Python 2.
+The :func:`~difflib.diff_bytes` function can now compare lists of byte
+strings.  This fixes a regression from Python 2.
 (Contributed by Terry J. Reedy and Greg Ward in :issue:`17445`.)
 
 
 distutils
 ---------
 
-The ``build`` and ``build_ext`` commands now accept a ``-j`` option to
+Both ``build`` and ``build_ext`` commands now accept a ``-j`` option to
 enable parallel building of extension modules.
 (Contributed by Antoine Pitrou in :issue:`5309`.)
 
@@ -792,17 +794,18 @@ method provides easy access to a canonical value for the
 :mailheader:`Content-Disposition` header.
 (Contributed by Abhilash Raj in :issue:`21083`.)
 
-A new policy option :attr:`~email.policy.EmailPolicy.utf8` can be set
-to ``True`` to encode email headers using the UTF-8 charset instead of using
-encoded words.  This allows ``Messages`` to be formatted according to
+A new policy option :attr:`EmailPolicy.utf8 <email.policy.EmailPolicy.utf8>`
+can be set to ``True`` to encode email headers using the UTF-8 charset instead
+of using encoded words.  This allows ``Messages`` to be formatted according to
 :rfc:`6532` and used with an SMTP server that supports the :rfc:`6531`
-``SMTPUTF8`` extension.  (Contributed by R. David Murray in :issue:`24211`.)
+``SMTPUTF8`` extension.  (Contributed by R. David Murray in
+:issue:`24211`.)
 
 
 faulthandler
 ------------
 
-The :func:`~faulthandler.enable`, :func:`~faulthandler.register`,
+:func:`~faulthandler.enable`, :func:`~faulthandler.register`,
 :func:`~faulthandler.dump_traceback` and
 :func:`~faulthandler.dump_traceback_later` functions now accept file
 descriptors in addition to file-like objects.
@@ -813,14 +816,14 @@ functools
 ---------
 
 Most of :func:`~functools.lru_cache` machinery is now implemented in C, making
-it significantly faster. (Contributed by Matt Joiner, Alexey Kachayev, and
+it significantly faster.  (Contributed by Matt Joiner, Alexey Kachayev, and
 Serhiy Storchaka in :issue:`14373`.)
 
 
 glob
 ----
 
-The :func:`~glob.iglob` and :func:`~glob.glob` functions now support recursive
+:func:`~glob.iglob` and :func:`~glob.glob` functions now support recursive
 search in subdirectories using the ``"**"`` pattern.
 (Contributed by Serhiy Storchaka in :issue:`13968`.)
 
@@ -838,7 +841,7 @@ idlelib and IDLE
 ----------------
 
 Since idlelib implements the IDLE shell and editor and is not intended for
-import by other programs, it gets improvements with every release. See
+import by other programs, it gets improvements with every release.  See
 :file:`Lib/idlelib/NEWS.txt` for a cumulative list of changes since 3.4.0,
 as well as changes made in future 3.5.x releases. This file is also available
 from the IDLE Help -> About Idle dialog.
@@ -888,17 +891,17 @@ object with code compiled from a string by running
 (Contributed by Brett Cannon in :issue:`21156`.)
 
 The new :func:`util.module_from_spec <importlib.util.module_from_spec>`
-function is now the preferred way to create a new module.  Compared to the
-:class:`types.ModuleType` class, this new function will set the various
-import-controlled attributes based on the passed-in spec object.
-(Contributed by Brett Cannon in :issue:`20383`.)
+function is now the preferred way to create a new module.  As opposed to
+creating a :class:`types.ModuleType` instance directly, this new function
+will set the various import-controlled attributes based on the passed-in
+spec object.  (Contributed by Brett Cannon in :issue:`20383`.)
 
 
 inspect
 -------
 
-The :class:`~inspect.Signature` and :class:`~inspect.Parameter` classes are now
-picklable and hashable.  (Contributed by Yury Selivanov in :issue:`20726`
+Both :class:`~inspect.Signature` and :class:`~inspect.Parameter` classes are
+now picklable and hashable.  (Contributed by Yury Selivanov in :issue:`20726`
 and :issue:`20334`.)
 
 A new
@@ -918,13 +921,13 @@ following of ``__wrapped__`` links.
 
 A set of new functions to inspect
 :term:`coroutine functions <coroutine function>` and
-``coroutine objects`` has been added:
+:term:`coroutine objects <coroutine>` has been added:
 :func:`~inspect.iscoroutine`, :func:`~inspect.iscoroutinefunction`,
 :func:`~inspect.isawaitable`, :func:`~inspect.getcoroutinelocals`,
 and :func:`~inspect.getcoroutinestate`.
 (Contributed by Yury Selivanov in :issue:`24017` and :issue:`24400`.)
 
-The :func:`~inspect.stack`, :func:`~inspect.trace`,
+:func:`~inspect.stack`, :func:`~inspect.trace`,
 :func:`~inspect.getouterframes`, and :func:`~inspect.getinnerframes`
 functions now return a list of named tuples.
 (Contributed by Daniel Shahaf in :issue:`16808`.)
@@ -933,7 +936,7 @@ functions now return a list of named tuples.
 ipaddress
 ---------
 
-The :class:`~ipaddress.IPv4Network` and :class:`~ipaddress.IPv6Network` classes
+Both :class:`~ipaddress.IPv4Network` and :class:`~ipaddress.IPv6Network` classes
 now accept an ``(address, netmask)`` tuple argument, so as to easily construct
 network objects from existing addresses.  (Contributed by Peter Moody
 and Antoine Pitrou in :issue:`16531`.)
@@ -965,11 +968,11 @@ logging
 All logging methods (:class:`~logging.Logger` :meth:`~logging.Logger.log`,
 :meth:`~logging.Logger.exception`, :meth:`~logging.Logger.critical`,
 :meth:`~logging.Logger.debug`, etc.), now accept exception instances
-in ``exc_info`` argument, in addition to boolean values and exception
+as an ``exc_info`` argument, in addition to boolean values and exception
 tuples.  (Contributed by Yury Selivanov in :issue:`20537`.)
 
-The :class:`handlers.HTTPHandler <logging.handlers.HTTPHandler>` classes now
-accepts an optional :class:`ssl.SSLContext` instance to configure the SSL
+The :class:`handlers.HTTPHandler <logging.handlers.HTTPHandler>` class now
+accepts an optional :class:`ssl.SSLContext` instance to configure SSL
 settings used in an HTTP connection.
 (Contributed by Alex Gaynor in :issue:`22788`.)
 
@@ -983,7 +986,7 @@ lzma
 ----
 
 The :meth:`LZMADecompressor.decompress <lzma.LZMADecompressor.decompress>`
-method  now accepts an optional *max_length* argument to limit the maximum
+method now accepts an optional *max_length* argument to limit the maximum
 size of decompressed data.
 (Contributed by Martin Panter in :issue:`15955`.)
 
@@ -1005,7 +1008,7 @@ Storchaka in :issue:`22486`.)
 operator
 --------
 
-The :mod:`operator` :func:`~operator.attrgetter`, :func:`~operator.itemgetter`,
+:func:`~operator.attrgetter`, :func:`~operator.itemgetter`,
 and :func:`~operator.methodcaller` objects now support pickling.
 (Contributed by Josh Rosenberg and Serhiy Storchaka in :issue:`22955`.)
 
@@ -1032,15 +1035,15 @@ use ``/dev/urandom`` and avoiding failures due to potential file descriptor
 exhaustion.  (Contributed by Victor Stinner in :issue:`22181`.)
 
 New :func:`~os.get_blocking` and :func:`~os.set_blocking` functions allow to
-get and set the file descriptor blocking mode (:data:`~os.O_NONBLOCK`.)
+get and set a file descriptor blocking mode (:data:`~os.O_NONBLOCK`.)
 (Contributed by Victor Stinner in :issue:`22054`.)
 
 The :func:`~os.truncate` and :func:`~os.ftruncate` functions are now supported
 on Windows.  (Contributed by Steve Dower in :issue:`23668`.)
 
-There is a new :func:`~os.path.commonpath` function returning the longest
+There is a new :func:`os.path.commonpath` function returning the longest
 common sub-path of each passed pathname.  Unlike the
-:func:`~os.path.commonprefix` function, it always returns a valid
+:func:`os.path.commonprefix` function, it always returns a valid
 path.  (Contributed by Rafik Draoui and Serhiy Storchaka in :issue:`10395`.)
 
 
@@ -1048,8 +1051,8 @@ pathlib
 -------
 
 The new :meth:`Path.samefile <pathlib.Path.samefile>` method can be used
-to check if the passed :class:`~pathlib.Path` object or a :class:`str` path,
-point to the same file.
+to check whether the path points to the same file as other path, which can be
+either an another :class:`~pathlib.Path` object, or a string.
 (Contributed by Vajrasky Kok and Antoine Pitrou in :issue:`19775`.)
 
 The :meth:`Path.mkdir <pathlib.Path.mkdir>` method how accepts a new optional
@@ -1070,16 +1073,16 @@ pickle
 ------
 
 Nested objects, such as unbound methods or nested classes, can now be pickled
-using :ref:`pickle protocols <pickle-protocols>` older than protocol version 4,
-which already supported these cases.  (Contributed by Serhiy Storchaka in
-:issue:`23611`.)
+using :ref:`pickle protocols <pickle-protocols>` older than protocol version 4.
+Protocol version 4 already supports these cases.  (Contributed by Serhiy
+Storchaka in :issue:`23611`.)
 
 
 poplib
 ------
 
-A new command :meth:`POP3.utf8 <poplib.POP3.utf8>` enables :rfc:`6856`
-(internationalized email) support, if the POP server supports it.
+A new :meth:`POP3.utf8 <poplib.POP3.utf8>` command enables :rfc:`6856`
+(Internationalized Email) support, if a POP server supports it.
 (Contributed by Milan OberKirch in :issue:`21804`.)
 
 
@@ -1090,15 +1093,15 @@ The number of capturing groups in regular expression is no longer limited by
 100.  (Contributed by Serhiy Storchaka in :issue:`22437`.)
 
 The :func:`~re.sub` and :func:`~re.subn` functions now replace unmatched
-groups with empty strings instead of rising an exception.
+groups with empty strings instead of raising an exception.
 (Contributed by Serhiy Storchaka in :issue:`1519638`.)
 
 
 readline
 --------
 
-The new :func:`~readline.append_history_file` function can be used to append
-the specified number of trailing elements in history to a given file.
+A new :func:`~readline.append_history_file` function can be used to append
+the specified number of trailing elements in history to the given file.
 (Contributed by Bruno Cauet in :issue:`22940`.)
 
 
@@ -1111,7 +1114,7 @@ the default :func:`~shutil.copy2` if there is a need to ignore file metadata
 when moving.
 (Contributed by Claudiu Popa in :issue:`19840`.)
 
-The :func:`~shutil.make_archive` function now supports *xztar* format.
+The :func:`~shutil.make_archive` function now supports the *xztar* format.
 (Contributed by Serhiy Storchaka in :issue:`5411`.)
 
 
@@ -1121,7 +1124,7 @@ signal
 On Windows, the :func:`~signal.set_wakeup_fd` function now also supports
 socket handles.  (Contributed by Victor Stinner in :issue:`22018`.)
 
-Various ``SIG*`` constants in :mod:`signal` module have been converted into
+Various ``SIG*`` constants in the :mod:`signal` module have been converted into
 :mod:`Enums <enum>`.  This allows meaningful names to be printed
 during debugging, instead of integer "magic numbers".
 (Contributed by Giampaolo Rodola' in :issue:`21076`.)
@@ -1133,7 +1136,8 @@ smtpd
 Both :class:`~smtpd.SMTPServer` and :class:`~smtpd.SMTPChannel` classes now
 accept a *decode_data* keyword argument to determine if the ``DATA`` portion of
 the SMTP transaction is decoded using the ``"utf-8"`` codec or is instead
-provided to :meth:`SMTPServer.process_message <smtpd.SMTPServer.process_message>`
+provided to the
+:meth:`SMTPServer.process_message <smtpd.SMTPServer.process_message>`
 method as a byte string.  The default is ``True`` for backward compatibility
 reasons, but will change to ``False`` in Python 3.6.  If *decode_data* is set
 to ``False``, the :meth:`~smtpd.SMTPServer.process_message` method must
@@ -1167,9 +1171,9 @@ A new :meth:`SMTP.auth <smtplib.SMTP.auth>` method provides a convenient way to
 implement custom authentication mechanisms. (Contributed by Milan
 Oberkirch in :issue:`15014`.)
 
-Additional debuglevel (2) shows timestamps for debug messages in
-:class:`smtplib.SMTP`.  (Contributed by Gavin Chappell and Maciej Szulik in
-:issue:`16914`.)
+The :meth:`SMTP.set_debuglevel <smtplib.SMTP.set_debuglevel>` method now
+accepts an additional debuglevel (2), which enables timestamps in debug
+messages. (Contributed by Gavin Chappell and Maciej Szulik in :issue:`16914`.)
 
 Both :meth:`SMTP.sendmail <smtplib.SMTP.sendmail>` and
 :meth:`SMTP.send_message <smtplib.SMTP.send_message>` methods now
@@ -1180,8 +1184,8 @@ support support :rfc:`6531` (SMTPUTF8).
 sndhdr
 ------
 
-The :func:`~sndhdr.what` and :func:`~sndhdr.whathdr` functions  now return
-a :func:`~collections.namedtuple`. (Contributed by Claudiu Popa in
+:func:`~sndhdr.what` and :func:`~sndhdr.whathdr` functions  now return
+a :func:`~collections.namedtuple`.  (Contributed by Claudiu Popa in
 :issue:`18615`.)
 
 
@@ -1194,14 +1198,14 @@ Memory BIO Support
 (Contributed by Geert Jansen in :issue:`21965`.)
 
 The new :class:`~ssl.SSLObject` class has been added to provide SSL protocol
-support for cases when the network IO capabilities of :class:`~ssl.SSLSocket`
+support for cases when the network I/O capabilities of :class:`~ssl.SSLSocket`
 are not necessary or suboptimal.  :class:`~ssl.SSLObject` represents
-an SSL protocol instance, but does not implement any network IO methods, and
+an SSL protocol instance, but does not implement any network I/O methods, and
 instead provides a memory buffer interface.  The new :class:`~ssl.MemoryBIO`
 class can be used to pass data between Python and an SSL protocol instance.
 
 The memory BIO SSL support is primarily intended to be used in frameworks
-implementing asynchronous IO for which :class:`~ssl.SSLObject` IO readiness
+implementing asynchronous I/O for which :class:`~ssl.SSLSocket`'s readiness
 model ("select/poll") is inefficient.
 
 A new :meth:`SSLContext.wrap_bio <ssl.SSLContext.wrap_bio>` method can be used
@@ -1213,12 +1217,12 @@ Application-Layer Protocol Negotiation Support
 
 (Contributed by Benjamin Peterson in :issue:`20188`.)
 
-Where OpenSSL support is present, :mod:`ssl` module now implements *
-Application-Layer Protocol Negotiation* TLS extension as described
+Where OpenSSL support is present, :mod:`ssl` module now implements
+*Application-Layer Protocol Negotiation* TLS extension as described
 in :rfc:`7301`.
 
 The new :meth:`SSLContext.set_alpn_protocols <ssl.SSLContext.set_alpn_protocols>`
-can be used to specify which protocols the socket should advertise during
+can be used to specify which protocols a socket should advertise during
 the TLS handshake.
 
 The new
@@ -1271,7 +1275,7 @@ Functions with timeouts now use a monotonic clock, instead of a system clock.
 (Contributed by Victor Stinner in :issue:`22043`.)
 
 A new :meth:`socket.sendfile <socket.socket.sendfile>` method allows to
-send a file over a socket by using high-performance :func:`os.sendfile`
+send a file over a socket by using the high-performance :func:`os.sendfile`
 function on UNIX resulting in uploads being from 2 to 3 times faster than when
 using plain :meth:`socket.send <socket.socket.send>`.
 (Contributed by Giampaolo Rodola' in :issue:`17552`.)
@@ -1285,9 +1289,12 @@ now the maximum total duration to send all data.
 subprocess
 ----------
 
-The new :func:`~subprocess.run` function has been added and is the recommended
-approach to invoking subprocesses.  It runs the specified command and
-and returns a :class:`~subprocess.CompletedProcess` object.
+The new :func:`~subprocess.run` function has been added.
+It runs the specified command and and returns a
+:class:`~subprocess.CompletedProcess` object, which describes a finished
+process.  The new API is more consistent and is the recommended approach
+to invoking subprocesses in Python code that does not need to maintain
+compatibility with earlier Python versions.
 (Contributed by Thomas Kluyver in :issue:`23342`.)
 
 
@@ -1295,13 +1302,13 @@ sys
 ---
 
 A new :func:`~sys.set_coroutine_wrapper` function allows setting a global
-hook that will be called whenever a :ref:`coro object <coro-objects>`
-is created.  Essentially, it works like a global coroutine decorator.  A
-corresponding :func:`~sys.get_coroutine_wrapper` can be used to obtain
-a currently set wrapper.  Both functions are provisional, and are intended
-for debugging purposes only. (Contributed by Yury Selivanov in :issue:`24017`.)
+hook that will be called whenever a :term:`coroutine object <coroutine>`
+is created by an :keyword:`async def` function.  A corresponding
+:func:`~sys.get_coroutine_wrapper` can be used to obtain a currently set
+wrapper.  Both functions are provisional, and are intended for debugging
+purposes only.  (Contributed by Yury Selivanov in :issue:`24017`.)
 
-There is a new :func:`~sys.is_finalizing` function to check if the Python
+A new :func:`~sys.is_finalizing` function can be used to check if the Python
 interpreter is :term:`shutting down <interpreter shutdown>`.
 (Contributed by Antoine Pitrou in :issue:`22696`.)
 
@@ -1320,7 +1327,7 @@ tarfile
 The *mode* argument of the :func:`~tarfile.open` function now accepts ``"x"``
 to request exclusive creation.  (Contributed by Berker Peksag in :issue:`21717`.)
 
-The :meth:`TarFile.extractall <tarfile.TarFile.extractall>` and
+:meth:`TarFile.extractall <tarfile.TarFile.extractall>` and
 :meth:`TarFile.extract <tarfile.TarFile.extract>` methods now take a keyword
 argument *numeric_only*.  If set to ``True``, the extracted files and
 directories will be owned by the numeric ``uid`` and ``gid`` from the tarfile.
@@ -1332,7 +1339,7 @@ they will be owned by the named user and group in the tarfile.
 threading
 ---------
 
-The :meth:`Lock.acquire <threading.Lock.acquire>` and
+Both :meth:`Lock.acquire <threading.Lock.acquire>` and
 :meth:`RLock.acquire <threading.RLock.acquire>` methods
 now use a monotonic clock for timeout management.
 (Contributed by Victor Stinner in :issue:`22043`.)
@@ -1348,9 +1355,9 @@ The :func:`~time.monotonic` function is now always available.
 timeit
 ------
 
-New command line option ``-u`` or ``--unit=U`` to specify a time
-unit for the timer output. Supported options are ``usec``, ``msec``, or ``sec``.
-(Contributed by Julian Gindi in :issue:`18983`.)
+New command line option ``-u`` or ``--unit=U`` can be used to specify the time
+unit for the timer output.  Supported options are ``usec``, ``msec``,
+or ``sec``.  (Contributed by Julian Gindi in :issue:`18983`.)
 
 
 tkinter
@@ -1373,7 +1380,7 @@ New lightweight classes: :class:`~traceback.TracebackException`,
 :class:`~traceback.StackSummary`, and :class:`traceback.FrameSummary`.
 (Contributed by Robert Collins in :issue:`17911`.)
 
-The :func:`~traceback.print_tb` and :func:`~traceback.print_stack` functions
+Both :func:`~traceback.print_tb` and :func:`~traceback.print_stack` functions
 now support negative values for the *limit* argument.
 (Contributed by Dmitry Kazakov in :issue:`22619`.)
 
@@ -1387,8 +1394,8 @@ A new :func:`~types.coroutine` function to transform
 :term:`awaitables <awaitable>`.
 (Contributed by Yury Selivanov in :issue:`24017`.)
 
-A new :class:`~types.CoroutineType` is the type of :term:`coroutine` objects,
-produced by calling a function defined with an :keyword:`async def` statement.
+A new :class:`~types.CoroutineType` is the type of :term:`coroutine` objects
+created by :keyword:`async def` functions.
 (Contributed by Yury Selivanov in :issue:`24400`.)
 
 
@@ -1478,22 +1485,24 @@ Many functions in :mod:`mmap`, :mod:`ossaudiodev`, :mod:`socket`,
 Optimizations
 =============
 
-The :func:`os.walk` function has been sped up by 3-5 times on POSIX systems,
-and by 7-20 times on Windows. This was done using the new :func:`os.scandir`
+The :func:`os.walk` function has been sped up by 3 to 5 times on POSIX systems,
+and by 7 to 20 times on Windows.  This was done using the new :func:`os.scandir`
 function, which exposes file information from the underlying ``readdir`` or
-``FindFirstFile``/``FindNextFile`` system calls. (Contributed by
+``FindFirstFile``/``FindNextFile`` system calls.  (Contributed by
 Ben Hoyt with help from Victor Stinner in :issue:`23605`.)
 
 Construction of ``bytes(int)`` (filled by zero bytes) is faster and uses less
 memory for large objects. ``calloc()`` is used instead of ``malloc()`` to
 allocate memory for these objects.
+(Contributed by Victor Stinner in :issue:`21233`.)
 
 Some operations on :mod:`ipaddress` :class:`~ipaddress.IPv4Network` and
 :class:`~ipaddress.IPv6Network` have been massively sped up, such as
 :meth:`~ipaddress.IPv4Network.subnets`, :meth:`~ipaddress.IPv4Network.supernet`,
 :func:`~ipaddress.summarize_address_range`, :func:`~ipaddress.collapse_addresses`.
 The speed up can range from 3 to 15 times.
-(See :issue:`21486`, :issue:`21487`, :issue:`20826`, :issue:`23266`.)
+(Contributed by Antoine Pitrou, Michel Albert, and Markus in
+:issue:`21486`, :issue:`21487`, :issue:`20826`, :issue:`23266`.)
 
 Pickling of :mod:`ipaddress` objects was optimized to produce significantly
 smaller output.  (Contributed by Serhiy Storchaka in :issue:`23133`.)
@@ -1572,7 +1581,7 @@ loaded):
     ``linux-gnu32`` (and ``<architecture>`` will be ``x86_64``).
 
 * On Windows, extension module filenames end with
-  ``.<debug>.cp<major><minor>-<platform>.pyd``:
+  ``<debug>.cp<major><minor>-<platform>.pyd``:
 
   * ``<major>`` is the major number of the Python version;
     for Python 3.5 this is ``3``.
@@ -1607,7 +1616,8 @@ become proper keywords in Python 3.7.
 Unsupported Operating Systems
 -----------------------------
 
-Per :PEP:`11`, Microsoft support of Windows XP has ended.
+Windows XP is no longer supported by Microsoft, thus, per :PEP:`11`, CPython
+3.5 is no longer officially supported on this OS.
 
 
 Deprecated Python modules, functions and methods
@@ -1782,6 +1792,10 @@ Changes in the Python API
 * The :mod:`socket` module now exports the CAN_RAW_FD_FRAMES constant on linux
   3.6 and greater.
 
+* The :func:`~ssl.cert_time_to_seconds` function now interprets the input time
+  as UTC and not as local time, per :rfc:`5280`.  Additionally, the return
+  value is always an :class:`int`. (Contributed by Akira Li in :issue:`19940`.)
+
 * The ``pygettext.py`` Tool now uses the standard +NNNN format for timezones in
   the POT-Creation-Date header.