python · twisteroidambassador · May 24, 2018 · May 24, 2018 · May 24, 2018 · May 25, 2018
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
@@ -40,16 +40,18 @@ Glossary
       ABCs with the :mod:`abc` module.
 
    annotation
-      A metadata value associated with a global variable, a class attribute or a
-      function or method parameter or return value, that stores a
-      :term:`type hint`.
+      A label associated with a variable, a class
+      attribute or a function parameter or return value,
+      used by convention as a :term:`type hint`.
 
-      Annotations are stored in the :attr:`__annotations__` special attribute
-      of a module (when annotating a global variable), class (when annotating
-      one of its attributes) or function or method (when annotating a parameter or a
-      return value) and can be accessed using :func:`typing.get_type_hints`.
+      Annotations of local variables cannot be accessed at runtime, but
+      annotations of global variables, class attributes, and functions
+      are stored in the :attr:`__annotations__`
+      special attribute of modules, classes, and functions,
+      respectively.
 
-      See :pep:`484` and :pep:`526` which describe this functionality.
+      See :term:`variable annotation`, :term:`function annotation`, :pep:`484`
+      and :pep:`526`, which describe this functionality.
 
    argument
       A value passed to a :term:`function` (or :term:`method`) when calling the
@@ -191,11 +193,6 @@ Glossary
       A variable defined in a class and intended to be modified only at
       class level (i.e., not in an instance of the class).
 
-      Class variables can be specified as such through
-      :term:`type hints <type hint>`.
-
-      See :pep:`526` which describes class variable annotations.
-
    coercion
       The implicit conversion of an instance of one type to another during an
       operation which involves two arguments of the same type.  For example,
@@ -388,19 +385,20 @@ Glossary
       and the :ref:`function` section.
 
    function annotation
-      An :term:`annotation` of a function, or a method.
+      An :term:`annotation` of a function parameter or return value.
 
-      For example, this function has its parameters annotated as taking
-      :class:`int` arguments and its return value annotated as being an
-      :class:`int` as well::
+      Function annotations are usually used for
+      :term:`type hints <type hint>`: for example this function is expected to take two
+      :class:`int` arguments and is also expected to have an :class:`int`
+      return value::
 
          def sum_two_numbers(a: int, b: int) -> int:
             return a + b
 
-      Its syntax is explained in section :ref:`function`.
+      Function annotation syntax is explained in section :ref:`function`.
 
-      See also the :term:`variable annotation` glossary entry, and :pep:`484`,
-      which describes this functionality.
+      See :term:`variable annotation` and :pep:`484`,
+      which describe this functionality.
 
    __future__
       A pseudo-module which programmers can use to enable new language features
@@ -1048,17 +1046,42 @@ Glossary
       :attr:`~instance.__class__` attribute or can be retrieved with
       ``type(obj)``.
 
+   type alias
+      A synonym for a type, created by assigning the type to an identifier.
+
+      Type aliases are useful for simplifying :term:`type hints <type hint>`.
+      For example::
+
+         from typing import List, Tuple
+
+         def remove_gray_shades(
+                 colors: List[Tuple[int, int, int]]) -> List[Tuple[int, int, int]]:
+             pass
+
+      could be made more readable like this::
+
+         from typing import List, Tuple
+
+         Color = Tuple[int, int, int]
+
+         def remove_gray_shades(colors: List[Color]) -> List[Color]:
+             pass
+
+      See :mod:`typing` and :pep:`484`, which describe this functionality.
+
    type hint
-      A specification about the expected type for a global variable, class
-      variable, function or method parameter or return value.
+      An :term:`annotation` that specifies the expected type for a variable, a class
+      attribute, or a function parameter or return value.
 
-      While type hints are optional and are not enforced by Python when used,
-      they are useful for static type analysis tools, and aid IDEs on code
+      Type hints are optional and are not enforced by Python but
+      they are useful to static type analysis tools, and aid IDEs with code
       completion and refactoring.
 
-      Type hints are stored in :term:`annotations <annotation>`.
+      Type hints of global variables, class attributes, and functions,
+      but not local variables, can be accessed using
+      :func:`typing.get_type_hints`.
 
-      See also :pep:`483` which describe this functionality.
+      See :mod:`typing` and :pep:`484`, which describe this functionality.
 
    universal newlines
       A manner of interpreting text streams in which all of the following are
@@ -1068,21 +1091,23 @@ Glossary
       :func:`bytes.splitlines` for an additional use.
 
    variable annotation
-      An :term:`annotation` of a global variable, or a class attribute.
+      An :term:`annotation` of a variable or a class attribute.
 
-      For example, this variable is annotated as taking :class:`int` values::
+      When annotating a variable or a class attribute, assignment is optional::
 
-         count: int = 0
+         class C:
+             field: 'annotation'
 
-      When annotating variables, assignment is optional::
+      Variable annotations are usually used for
+      :term:`type hints <type hint>`: for example this variable is expected to take
+      :class:`int` values::
 
-         class C:
-             field: int
+         count: int = 0
 
-      Its syntax is explained in section :ref:`annassign`.
+      Variable annotation syntax is explained in section :ref:`annassign`.
 
-      See also the :term:`function annotation` glossary entry, and :pep:`484`
-      and :pep:`526` which describe this functionality.
+      See :term:`function annotation`, :pep:`484`
+      and :pep:`526`, which describe this functionality.
 
    virtual environment
       A cooperatively isolated runtime environment that allows Python users

diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst
@@ -151,10 +151,6 @@ and classes for traversing abstract syntax trees:
    .. versionchanged:: 3.5
       :class:`AsyncFunctionDef` is now supported.
 
-   .. versionchanged:: 3.7
-      The docstring is now exported from the node docstring field, instead of
-      the first body statement.
-
 
 .. function:: fix_missing_locations(node)
 

diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
@@ -340,9 +340,23 @@ Creating connections
      If given, these should all be integers from the corresponding
      :mod:`socket` module constants.
 
+   * *delay*, if given, enables Happy Eyeballs for this connection. It should
+     be a floating-point number representing the amount of time in seconds
+     to wait for a connection attempt to complete, before starting the next
+     attempt in parallel. This is the "Connection Attempt Delay" as defined
+     in RFC 8305.
+
+   * *interleave*, only for use together with *delay*, controls address
+     reordering. If ``0`` is specified, no reordering is done, and addresses are
+     tried in the order returned by :meth:`getaddrinfo`. If a positive integer
+     is specified, the addresses are interleaved by address family, and the
+     given integer is interpreted as "First Address Family Count" as defined
+     in RFC 8305. The default is ``1``.
+
    * *sock*, if given, should be an existing, already connected
      :class:`socket.socket` object to be used by the transport.
-     If *sock* is given, none of *host*, *port*, *family*, *proto*, *flags*
+     If *sock* is given, none of *host*, *port*, *family*, *proto*, *flags*,
+     *delay*, *interleave*
      and *local_addr* should be specified.
 
    * *local_addr*, if given, is a ``(local_host, local_port)`` tuple used
@@ -353,6 +367,10 @@ Creating connections
      to wait for the SSL handshake to complete before aborting the connection.
      ``10.0`` seconds if ``None`` (default).
 
+   .. versionadded:: 3.8
+
+      The *delay* and *interleave* parameters.
+
    .. versionadded:: 3.7
 
       The *ssl_handshake_timeout* parameter.

diff --git a/Doc/library/asyncio-eventloops.rst b/Doc/library/asyncio-eventloops.rst
@@ -176,12 +176,15 @@ An event loop policy must implement the following interface:
       Get the event loop for the current context.
 
       Returns an event loop object implementing the :class:`AbstractEventLoop`
-      interface.
+      interface. In case called from coroutine, it returns the currently
+      running event loop.
 
       Raises an exception in case no event loop has been set for the current
       context and the current policy does not specify to create one. It must
       never return ``None``.
 
+      .. versionchanged:: 3.6
+
    .. method:: set_event_loop(loop)
 
       Set the event loop for the current context to *loop*.

diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst
@@ -463,16 +463,23 @@ The idea of BufferedProtocol is that it allows to manually allocate
 and control the receive buffer.  Event loops can then use the buffer
 provided by the protocol to avoid unnecessary data copies.  This
 can result in noticeable performance improvement for protocols that
-receive big amounts of data.  Sophisticated protocols can allocate
-the buffer only once at creation time.
+receive big amounts of data.  Sophisticated protocols implementations
+can allocate the buffer only once at creation time.
 
 The following callbacks are called on :class:`BufferedProtocol`
 instances:
 
-.. method:: BufferedProtocol.get_buffer()
+.. method:: BufferedProtocol.get_buffer(sizehint)
 
-   Called to allocate a new receive buffer.  Must return an object
-   that implements the :ref:`buffer protocol <bufferobjects>`.
+   Called to allocate a new receive buffer.
+
+   *sizehint* is a recommended minimal size for the returned
+   buffer.  It is acceptable to return smaller or bigger buffers
+   than what *sizehint* suggests.  When set to -1, the buffer size
+   can be arbitrary. It is an error to return a zero-sized buffer.
+
+   Must return an object that implements the
+   :ref:`buffer protocol <bufferobjects>`.
 
 .. method:: BufferedProtocol.buffer_updated(nbytes)
 

diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
@@ -443,6 +443,8 @@ Task
       Return a set of all tasks for an event loop.
 
       By default all tasks for the current event loop are returned.
+      If *loop* is ``None``, :func:`get_event_loop` function
+      is used to get the current loop.
 
    .. classmethod:: current_task(loop=None)
 
@@ -567,8 +569,9 @@ Task functions
 
    Return a set of :class:`Task` objects created for the loop.
 
-   If *loop* is ``None`` :func:`get_event_loop` is used for getting
-   current loop.
+   If *loop* is ``None``, :func:`get_running_loop` is used for getting
+   current loop (contrary to the deprecated :meth:`Task.all_tasks` method
+   that uses :func:`get_event_loop`.)
 
    .. versionadded:: 3.7
 
@@ -637,6 +640,10 @@ Task functions
    outer Future is *not* cancelled in this case.  (This is to prevent the
    cancellation of one child to cause other children to be cancelled.)
 
+   .. versionchanged:: 3.7.0
+      If the *gather* itself is cancelled, the cancellation is propagated
+      regardless of *return_exceptions*.
+
 .. function:: iscoroutine(obj)
 
    Return ``True`` if *obj* is a :ref:`coroutine object <coroutine>`,
@@ -761,6 +768,9 @@ Task functions
    |                             | futures finish or are cancelled.       |
    +-----------------------------+----------------------------------------+
 
+   Unlike :func:`~asyncio.wait_for`, ``wait()`` will not cancel the futures
+   when a timeout occurs.
+
    This function is a :ref:`coroutine <coroutine>`.
 
    Usage::
@@ -783,7 +793,9 @@ Task functions
 
    Returns result of the Future or coroutine.  When a timeout occurs, it
    cancels the task and raises :exc:`asyncio.TimeoutError`. To avoid the task
-   cancellation, wrap it in :func:`shield`.
+   cancellation, wrap it in :func:`shield`.  The function will wait until
+   the future is actually cancelled, so the total wait time may exceed
+   the *timeout*.
 
    If the wait is cancelled, the future *fut* is also cancelled.
 
@@ -793,3 +805,8 @@ Task functions
 
    .. versionchanged:: 3.4.3
       If the wait is cancelled, the future *fut* is now also cancelled.
+
+   .. versionchanged:: 3.7
+      When *fut* is cancelled due to a timeout, ``wait_for`` now waits
+      for *fut* to be cancelled.  Previously,
+      it raised :exc:`~asyncio.TimeoutError` immediately.
diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
@@ -383,6 +383,52 @@ The :mod:`functools` module defines the following functions:
       The :func:`register` attribute supports using type annotations.
 
 
+.. class:: singledispatchmethod(func)
+
+   Transform a method into a :term:`single-dispatch <single
+   dispatch>` :term:`generic function`.
+
+   To define a generic method, decorate it with the ``@singledispatchmethod``
+   decorator. Note that the dispatch happens on the type of the first non-self
+   or non-cls argument, create your function accordingly::
+
+    class Negator:
+        @singledispatchmethod
+        def neg(self, arg):
+            raise NotImplementedError("Cannot negate a")
+
+        @neg.register
+        def _(self, arg: int):
+            return -arg
+
+        @neg.register
+        def _(self, arg: bool):
+            return not arg
+
+   ``@singledispatchmethod`` supports nesting with other decorators such as
+   ``@classmethod``. Note that to allow for ``dispatcher.register``,
+   ``singledispatchmethod`` must be the *outer most* decorator. Here is the
+   ``Negator`` class with the ``neg`` methods being class bound::
+
+    class Negator:
+        @singledispatchmethod
+        @classmethod
+        def neg(cls, arg):
+            raise NotImplementedError("Cannot negate a")
+
+        @neg.register
+        @classmethod
+        def _(cls, arg: int):
+            return -arg
+
+        @neg.register
+        @classmethod
+        def _(cls, arg: bool):
+            return not arg
+
+   The same pattern can be used for other similar decorators: ``staticmethod``,
+   ``abstractmethod``, and others.
+
 .. function:: update_wrapper(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)
 
    Update a *wrapper* function to look like the *wrapped* function. The optional

diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst
@@ -33,7 +33,7 @@ handler.  Code to create and run the server looks like this::
    :attr:`server_port`. The server is accessible by the handler, typically
    through the handler's :attr:`server` instance variable.
 
-.. class:: ThreadedHTTPServer(server_address, RequestHandlerClass)
+.. class:: ThreadingHTTPServer(server_address, RequestHandlerClass)
 
    This class is identical to HTTPServer but uses threads to handle
    requests by using the :class:`~socketserver.ThreadingMixIn`. This
@@ -43,7 +43,7 @@ handler.  Code to create and run the server looks like this::
    .. versionadded:: 3.7
 
 
-The :class:`HTTPServer` and :class:`ThreadedHTTPServer` must be given
+The :class:`HTTPServer` and :class:`ThreadingHTTPServer` must be given
 a *RequestHandlerClass* on instantiation, of which this module
 provides three different variants: