bpo-32436: Document PEP 567 changes to asyncio. (GH-7073)

(cherry picked from commit 28b91780)
Co-authored-by: Yury Selivanov <yury@magic.io>

Doc/library/asyncio-eventloop.rst

@@ -124,7 +124,7 @@ keywords to your callback, use :func:`functools.partial`. For example,
    parameters in debug mode, whereas ``lambda`` functions have a poor
    representation.
 
-.. method:: AbstractEventLoop.call_soon(callback, \*args)
+.. method:: AbstractEventLoop.call_soon(callback, *args, context=None)
 
    Arrange for a callback to be called as soon as possible.  The callback is
    called after :meth:`call_soon` returns, when control returns to the event
@@ -137,19 +137,31 @@ keywords to your callback, use :func:`functools.partial`. For example,
    Any positional arguments after the callback will be passed to the
    callback when it is called.
 
+   An optional keyword-only *context* argument allows specifying a custom
+   :class:`contextvars.Context` for the *callback* to run in.  The current
+   context is used when no *context* is provided.
+
    An instance of :class:`asyncio.Handle` is returned, which can be
    used to cancel the callback.
 
    :ref:`Use functools.partial to pass keywords to the callback
    <asyncio-pass-keywords>`.
 
-.. method:: AbstractEventLoop.call_soon_threadsafe(callback, \*args)
+   .. versionchanged:: 3.7
+      The *context* keyword-only parameter was added. See :pep:`567`
+      for more details.
+
+.. method:: AbstractEventLoop.call_soon_threadsafe(callback, *args, context=None)
 
    Like :meth:`call_soon`, but thread safe.
 
    See the :ref:`concurrency and multithreading <asyncio-multithreading>`
    section of the documentation.
 
+   .. versionchanged:: 3.7
+      The *context* keyword-only parameter was added. See :pep:`567`
+      for more details.
+
 
 .. _asyncio-delayed-calls:
 
@@ -166,7 +178,7 @@ a different clock than :func:`time.time`.
    Timeouts (relative *delay* or absolute *when*) should not exceed one day.
 
 
-.. method:: AbstractEventLoop.call_later(delay, callback, *args)
+.. method:: AbstractEventLoop.call_later(delay, callback, *args, context=None)
 
    Arrange for the *callback* to be called after the given *delay*
    seconds (either an int or float).
@@ -182,10 +194,18 @@ a different clock than :func:`time.time`.
    is called. If you want the callback to be called with some named
    arguments, use a closure or :func:`functools.partial`.
 
+   An optional keyword-only *context* argument allows specifying a custom
+   :class:`contextvars.Context` for the *callback* to run in.  The current
+   context is used when no *context* is provided.
+
    :ref:`Use functools.partial to pass keywords to the callback
    <asyncio-pass-keywords>`.
 
-.. method:: AbstractEventLoop.call_at(when, callback, *args)
+   .. versionchanged:: 3.7
+      The *context* keyword-only parameter was added. See :pep:`567`
+      for more details.
+
+.. method:: AbstractEventLoop.call_at(when, callback, *args, context=None)
 
    Arrange for the *callback* to be called at the given absolute timestamp
    *when* (an int or float), using the same time reference as
@@ -199,6 +219,10 @@ a different clock than :func:`time.time`.
    :ref:`Use functools.partial to pass keywords to the callback
    <asyncio-pass-keywords>`.
 
+   .. versionchanged:: 3.7
+      The *context* keyword-only parameter was added. See :pep:`567`
+      for more details.
+
 .. method:: AbstractEventLoop.time()
 
    Return the current time, as a :class:`float` value, according to the

Doc/library/asyncio-task.rst

@@ -275,19 +275,27 @@ Future
       :exc:`CancelledError`. If the future isn't done yet, raises
       :exc:`InvalidStateError`.
 
-   .. method:: add_done_callback(fn)
+   .. method:: add_done_callback(callback, *, context=None)
 
       Add a callback to be run when the future becomes done.
 
-      The callback is called with a single argument - the future object. If the
+      The *callback* is called with a single argument - the future object. If the
       future is already done when this is called, the callback is scheduled
       with :meth:`~AbstractEventLoop.call_soon`.
 
+      An optional keyword-only *context* argument allows specifying a custom
+      :class:`contextvars.Context` for the *callback* to run in.  The current
+      context is used when no *context* is provided.
+
       :ref:`Use functools.partial to pass parameters to the callback
       <asyncio-pass-keywords>`. For example,
       ``fut.add_done_callback(functools.partial(print, "Future:",
       flush=True))`` will call ``print("Future:", fut, flush=True)``.
 
+      .. versionchanged:: 3.7
+         The *context* keyword-only parameter was added. See :pep:`567`
+         for more details.
+
    .. method:: remove_done_callback(fn)
 
       Remove all instances of a callback from the "call when done" list.
@@ -421,8 +429,15 @@ Task
    Don't directly create :class:`Task` instances: use the :func:`create_task`
    function or the :meth:`AbstractEventLoop.create_task` method.
 
+   Tasks support the :mod:`contextvars` module.  When a Task
+   is created it copies the current context and later runs its coroutine
+   in the copied context.  See :pep:`567` for more details.
+
    This class is :ref:`not thread safe <asyncio-multithreading>`.
 
+   .. versionchanged:: 3.7
+      Added support for the :mod:`contextvars` module.
+
    .. classmethod:: all_tasks(loop=None)
 
       Return a set of all tasks for an event loop.

Doc/whatsnew/3.7.rst

@@ -608,6 +608,17 @@ include:
   destroying the event loop.
   (Contributed by Yury Selivanov in :issue:`32314`.)
 
+* asyncio gained support for :mod:`contextvars`.
+  :meth:`loop.call_soon() <asyncio.AbstractEventLoop.call_soon>`,
+  :meth:`loop.call_soon_threadsafe() <asyncio.AbstractEventLoop.call_soon_threadsafe>`,
+  :meth:`loop.call_later() <asyncio.AbstractEventLoop.call_later>`,
+  :meth:`loop.call_at() <asyncio.AbstractEventLoop.call_at>`, and
+  :meth:`Future.add_done_callback() <asyncio.Future.add_done_callback>`
+  have a new optional keyword-only *context* parameter.
+  :class:`Tasks <asyncio.Task>` now track their context automatically.
+  See :pep:`567` for more details.
+  (Contributed by Yury Selivanov in :issue:`32436`.)
+
 * The new :func:`asyncio.create_task` function has been added as a shortcut
   to ``asyncio.get_event_loop().create_task()``.
   (Contributed by Andrew Svetlov in :issue:`32311`.)

Misc/NEWS.d/next/Documentation/2018-05-23-11-59-51.bpo-32436.S1LGPa.rst

+Document PEP 567 changes to asyncio.