merge branch 3.5 just after tagging v3.5.1

Author: Anselm Kruis

.hgtags

@@ -178,3 +178,5 @@ cc15d736d860303b9da90d43cd32db39bab048df v3.5.0rc2
 66ed52375df802f9d0a34480daaa8ce79fc41313 v3.5.0rc3
 2d033fedfa7f1e325fd14ccdaa9cb42155da206f v3.5.0rc4
 374f501f4567b7595f2ad7798aa09afa2456bb28 v3.5.0
+948ef16a69513ba1ff15c9d7d0b012b949df4c80 v3.5.1rc1
+37a07cee5969e6d3672583187a73cf636ff28e1b v3.5.1

Doc/howto/clinic.rst

@@ -1249,18 +1249,18 @@ Here's the simplest example of a custom converter, from ``Modules/zlibmodule.c``
 
     /*[python input]
 
-    class uint_converter(CConverter):
+    class capped_uint_converter(CConverter):
         type = 'unsigned int'
-        converter = 'uint_converter'
+        converter = 'capped_uint_converter'
 
     [python start generated code]*/
-    /*[python end generated code: checksum=da39a3ee5e6b4b0d3255bfef95601890afd80709]*/
+    /*[python end generated code: output=da39a3ee5e6b4b0d input=35521e4e733823c7]*/
 
-This block adds a converter to Argument Clinic named ``uint``.  Parameters
-declared as ``uint`` will be declared as type ``unsigned int``, and will
-be parsed by the ``'O&'`` format unit, which will call the ``uint_converter``
-converter function.
-``uint`` variables automatically support default values.
+This block adds a converter to Argument Clinic named ``capped_uint``.  Parameters
+declared as ``capped_uint`` will be declared as type ``unsigned int``, and will
+be parsed by the ``'O&'`` format unit, which will call the
+``capped_uint_converter`` converter function.  ``capped_uint`` variables
+automatically support default values.
 
 More sophisticated custom converters can insert custom C code to
 handle initialization and cleanup.

Doc/library/ast.rst

@@ -104,7 +104,7 @@ The abstract grammar is currently defined as follows:
 :mod:`ast` Helpers
 ------------------
 
-Apart from the node classes, :mod:`ast` module defines these utility functions
+Apart from the node classes, the :mod:`ast` module defines these utility functions
 and classes for traversing abstract syntax trees:
 
 .. function:: parse(source, filename='<unknown>', mode='exec')

Doc/library/asyncio-eventloop.rst

@@ -29,7 +29,16 @@ Run an event loop
 
 .. method:: BaseEventLoop.run_forever()
 
-   Run until :meth:`stop` is called.
+   Run until :meth:`stop` is called.  If :meth:`stop` is called before
+   :meth:`run_forever()` is called, this polls the I/O selector once
+   with a timeout of zero, runs all callbacks scheduled in response to
+   I/O events (and those that were already scheduled), and then exits.
+   If :meth:`stop` is called while :meth:`run_forever` is running,
+   this will run the current batch of callbacks and then exit.  Note
+   that callbacks scheduled by callbacks will not run in that case;
+   they will run the next time :meth:`run_forever` is called.
+
+   .. versionchanged:: 3.5.1
 
 .. method:: BaseEventLoop.run_until_complete(future)
 
@@ -48,10 +57,10 @@ Run an event loop
 
    Stop running the event loop.
 
-   Every callback scheduled before :meth:`stop` is called will run.
-   Callbacks scheduled after :meth:`stop` is called will not run.
-   However, those callbacks will run if :meth:`run_forever` is called
-   again later.
+   This causes :meth:`run_forever` to exit at the next suitable
+   opportunity (see there for more details).
+
+   .. versionchanged:: 3.5.1
 
 .. method:: BaseEventLoop.is_closed()
 
@@ -61,7 +70,8 @@ Run an event loop
 
 .. method:: BaseEventLoop.close()
 
-   Close the event loop. The loop must not be running.
+   Close the event loop. The loop must not be running.  Pending
+   callbacks will be lost.
 
    This clears the queues and shuts down the executor, but does not wait for
    the executor to finish.

Doc/library/asyncio-protocol.rst

@@ -41,6 +41,11 @@ BaseTransport
       protocol's :meth:`connection_lost` method will be called with
       :const:`None` as its argument.
 
+   .. method:: is_closing(self)
+
+      Return ``True`` if the transport is closing or is closed.
+
+      .. versionadded:: 3.5.1
 
    .. method:: get_extra_info(name, default=None)
 
@@ -489,7 +494,7 @@ data and wait until the connection is closed::
 
         def connection_lost(self, exc):
             print('The server closed the connection')
-            print('Stop the event lop')
+            print('Stop the event loop')
             self.loop.stop()
 
     loop = asyncio.get_event_loop()

Doc/library/asyncio-task.rst

@@ -721,4 +721,4 @@ Task functions
       Unlike the functions above, :func:`run_coroutine_threadsafe` requires the
       *loop* argument to be passed explicitely.
 
-   .. versionadded:: 3.4.4
+   .. versionadded:: 3.4.4, 3.5.1

Doc/library/collections.rst

@@ -905,15 +905,15 @@ functionality with a subclass.  Here is how to add a calculated field and
 a fixed-width print format:
 
     >>> class Point(namedtuple('Point', 'x y')):
-        __slots__ = ()
-        @property
-        def hypot(self):
-            return (self.x ** 2 + self.y ** 2) ** 0.5
-        def __str__(self):
-            return 'Point: x=%6.3f  y=%6.3f  hypot=%6.3f' % (self.x, self.y, self.hypot)
+            __slots__ = ()
+            @property
+            def hypot(self):
+                return (self.x ** 2 + self.y ** 2) ** 0.5
+            def __str__(self):
+                return 'Point: x=%6.3f  y=%6.3f  hypot=%6.3f' % (self.x, self.y, self.hypot)
 
     >>> for p in Point(3, 4), Point(14, 5/7):
-        print(p)
+            print(p)
     Point: x= 3.000  y= 4.000  hypot= 5.000
     Point: x=14.000  y= 0.714  hypot=14.018
 
@@ -929,10 +929,10 @@ Docstrings can be customized by making direct assignments to the ``__doc__``
 fields:
 
    >>> Book = namedtuple('Book', ['id', 'title', 'authors'])
-   >>> Book.__doc__ = 'Hardcover book in active collection'
+   >>> Book.__doc__ += ': Hardcover book in active collection'
    >>> Book.id.__doc__ = '13-digit ISBN'
    >>> Book.title.__doc__ = 'Title of first printing'
-   >>> Book.author.__doc__ = 'List of authors sorted by last name'
+   >>> Book.authors.__doc__ = 'List of authors sorted by last name'
 
 Default values can be implemented by using :meth:`_replace` to
 customize a prototype instance:
@@ -942,16 +942,6 @@ customize a prototype instance:
     >>> johns_account = default_account._replace(owner='John')
     >>> janes_account = default_account._replace(owner='Jane')
 
-Enumerated constants can be implemented with named tuples, but it is simpler
-and more efficient to use a simple :class:`~enum.Enum`:
-
-    >>> Status = namedtuple('Status', 'open pending closed')._make(range(3))
-    >>> Status.open, Status.pending, Status.closed
-    (0, 1, 2)
-    >>> from enum import Enum
-    >>> class Status(Enum):
-    ...     open, pending, closed = range(3)
-
 
 .. seealso::
 

Doc/library/copy.rst

@@ -67,8 +67,8 @@ of lists by assigning a slice of the entire list, for example,
 
 Classes can use the same interfaces to control copying that they use to control
 pickling.  See the description of module :mod:`pickle` for information on these
-methods.  In fact, :mod:`copy` module uses the registered pickle functions from
-:mod:`copyreg` module.
+methods.  In fact, the :mod:`copy` module uses the registered
+pickle functions from the :mod:`copyreg` module.
 
 .. index::
    single: __copy__() (copy protocol)

Doc/library/enum.rst

@@ -730,18 +730,24 @@ member instances.
 Finer Points
 ^^^^^^^^^^^^
 
-Enum members are instances of an Enum class, and even though they are
-accessible as `EnumClass.member`, they are not accessible directly from
-the member::
-
-    >>> Color.red
-    <Color.red: 1>
-    >>> Color.red.blue
-    Traceback (most recent call last):
+:class:`Enum` members are instances of an :class:`Enum` class, and even
+though they are accessible as `EnumClass.member`, they should not be accessed
+directly from the member as that lookup may fail or, worse, return something
+besides the :class:`Enum` member you looking for::
+
+    >>> class FieldTypes(Enum):
+    ...     name = 0
+    ...     value = 1
+    ...     size = 2
     ...
-    AttributeError: 'Color' object has no attribute 'blue'
+    >>> FieldTypes.value.size
+    <FieldTypes.size: 2>
+    >>> FieldTypes.size.value
+    2
+
+.. versionchanged:: 3.5
 
-Likewise, the :attr:`__members__` is only available on the class.
+The :attr:`__members__` attribute is only available on the class.
 
 If you give your :class:`Enum` subclass extra methods, like the `Planet`_
 class above, those methods will show up in a :func:`dir` of the member,

Doc/library/fcntl.rst

@@ -83,6 +83,8 @@ The module defines the following functions:
    buffer 1024 bytes long which is then passed to :func:`ioctl` and copied back
    into the supplied buffer.
 
+   If the :c:func:`ioctl` fails, an :exc:`IOError` exception is raised.
+
    An example::
 
       >>> import array, fcntl, struct, termios, os
@@ -104,6 +106,8 @@ The module defines the following functions:
    :manpage:`flock(2)` for details.  (On some systems, this function is emulated
    using :c:func:`fcntl`.)
 
+   If the :c:func:`flock` fails, an :exc:`IOError` exception is raised.
+
 
 .. function:: lockf(fd, cmd, len=0, start=0, whence=0)
 

Doc/library/ftplib.rst

@@ -52,8 +52,7 @@ The module defines the following items:
    will be used). *source_address* is a 2-tuple ``(host, port)`` for the socket
    to bind to as its source address before connecting.
 
-   :class:`FTP` class supports the :keyword:`with` statement. Here is a sample
-   on how using it:
+   The :class:`FTP` class supports the :keyword:`with` statement, e.g.:
 
     >>> from ftplib import FTP
     >>> with FTP("ftp1.at.proftpd.org") as ftp:
@@ -418,8 +417,8 @@ FTP_TLS Objects
 
 .. method:: FTP_TLS.auth()
 
-   Set up secure control connection by using TLS or SSL, depending on what
-   specified in :meth:`ssl_version` attribute.
+   Set up a secure control connection by using TLS or SSL, depending on what
+   is specified in the :attr:`ssl_version` attribute.
 
    .. versionchanged:: 3.4
       The method now supports hostname check with

Doc/library/glob.rst

@@ -12,13 +12,13 @@
 --------------
 
 The :mod:`glob` module finds all the pathnames matching a specified pattern
-according to the rules used by the Unix shell.  No tilde expansion is done, but
-``*``, ``?``, and character ranges expressed with ``[]`` will be correctly
-matched.  This is done by using the :func:`os.listdir` and
-:func:`fnmatch.fnmatch` functions in concert, and not by actually invoking a
-subshell.  Note that unlike :func:`fnmatch.fnmatch`, :mod:`glob` treats
-filenames beginning with a dot (``.``) as special cases.  (For tilde and shell
-variable expansion, use :func:`os.path.expanduser` and
+according to the rules used by the Unix shell, although results are returned in
+arbitrary order.  No tilde expansion is done, but ``*``, ``?``, and character
+ranges expressed with ``[]`` will be correctly matched.  This is done by using
+the :func:`os.listdir` and :func:`fnmatch.fnmatch` functions in concert, and
+not by actually invoking a subshell.  Note that unlike :func:`fnmatch.fnmatch`,
+:mod:`glob` treats filenames beginning with a dot (``.``) as special cases.
+(For tilde and shell variable expansion, use :func:`os.path.expanduser` and
 :func:`os.path.expandvars`.)
 
 For a literal match, wrap the meta-characters in brackets.

Doc/library/linecache.rst

@@ -49,7 +49,7 @@ The :mod:`linecache` module defines the following functions:
 
 .. function:: lazycache(filename, module_globals)
 
-   Capture enough detail about a non-file based module to permit getting its
+   Capture enough detail about a non-file-based module to permit getting its
    lines later via :func:`getline` even if *module_globals* is None in the later
    call. This avoids doing I/O until a line is actually needed, without having
    to carry the module globals around indefinitely.

Doc/library/nntplib.rst

@@ -69,9 +69,9 @@ The module itself defines the following classes:
    connecting to an NNTP server on the local machine and intend to call
    reader-specific commands, such as ``group``.  If you get unexpected
    :exc:`NNTPPermanentError`\ s, you might need to set *readermode*.
-   :class:`NNTP` class supports the :keyword:`with` statement to
+   The :class:`NNTP` class supports the :keyword:`with` statement to
    unconditionally consume :exc:`OSError` exceptions and to close the NNTP
-   connection when done. Here is a sample on how using it:
+   connection when done, e.g.:
 
     >>> from nntplib import NNTP
     >>> with NNTP('news.gmane.org') as n:

Doc/library/re.rst

@@ -556,13 +556,15 @@ form.
 .. data:: X
           VERBOSE
 
-   This flag allows you to write regular expressions that look nicer. Whitespace
-   within the pattern is ignored, except when in a character class or preceded by
-   an unescaped backslash, and, when a line contains a ``'#'`` neither in a
-   character class or preceded by an unescaped backslash, all characters from the
-   leftmost such ``'#'`` through the end of the line are ignored.
-
-   That means that the two following regular expression objects that match a
+   This flag allows you to write regular expressions that look nicer and are
+   more readable by allowing you to visually separate logical sections of the
+   pattern and add comments. Whitespace within the pattern is ignored, except
+   when in a character class or when preceded by an unescaped backslash.
+   When a line contains a ``#`` that is not in a character class and is not
+   preceded by an unescaped backslash, all characters from the leftmost such
+   ``#`` through the end of the line are ignored.
+
+   This means that the two following regular expression objects that match a
    decimal number are functionally equal::
 
       a = re.compile(r"""\d +  # the integral part

Doc/library/resource.rst

@@ -316,10 +316,7 @@ These functions are used to retrieve resource usage information:
 .. function:: getpagesize()
 
    Returns the number of bytes in a system page. (This need not be the same as the
-   hardware page size.) This function is useful for determining the number of bytes
-   of memory a process is using. The third element of the tuple returned by
-   :func:`getrusage` describes memory usage in pages; multiplying by page size
-   produces number of bytes.
+   hardware page size.)
 
 The following :const:`RUSAGE_\*` symbols are passed to the :func:`getrusage`
 function to specify which processes information should be provided for.

Doc/library/typing.rst

@@ -478,7 +478,7 @@ The module defines the following classes, functions and decorators:
 
    Usage::
 
-       Employee = typing.NamedTuple('Employee', [('name', str), 'id', int)])
+       Employee = typing.NamedTuple('Employee', [('name', str), ('id', int)])
 
    This is equivalent to::
 

Doc/library/urllib.request.rst

@@ -1168,7 +1168,7 @@ The code for the sample CGI used in the above example is::
    #!/usr/bin/env python
    import sys
    data = sys.stdin.read()
-   print('Content-type: text-plain\n\nGot Data: "%s"' % data)
+   print('Content-type: text/plain\n\nGot Data: "%s"' % data)
 
 Here is an example of doing a ``PUT`` request using :class:`Request`::
 

Doc/library/zlib.rst

@@ -230,7 +230,7 @@ Decompression objects support the following methods and attributes:
    :meth:`decompress` method.  Some of the input data may be preserved in internal
    buffers for later processing.
 
-   If the optional parameter *max_length* is supplied then the return value will be
+   If the optional parameter *max_length* is non-zero then the return value will be
    no longer than *max_length*. This may mean that not all of the compressed input
    can be processed; and unconsumed data will be stored in the attribute
    :attr:`unconsumed_tail`. This bytestring must be passed to a subsequent call to

Doc/reference/executionmodel.rst

@@ -11,8 +11,8 @@ Execution model
 
 .. _prog_structure:
 
-Structure of a programm
-=======================
+Structure of a program
+======================
 
 .. index:: block
 
@@ -270,4 +270,3 @@ and :keyword:`raise` statement in section :ref:`raise`.
 
 .. [#] This limitation occurs because the code that is executed by these operations
        is not available at the time the module is compiled.
-