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)