From: Yury Selivanov Date: Wed, 23 May 2018 17:35:04 +0000 (-0400) Subject: bpo-32436: Document PEP 567 changes to asyncio. (GH-7073) X-Git-Tag: v3.8.0a1~1773 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=28b9178023a445b1da2694774c265cd4b7a244ec;p=python bpo-32436: Document PEP 567 changes to asyncio. (GH-7073) --- diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 2770fa6f8a..9d7f2362b3 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/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 `. -.. 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 ` 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 `. -.. 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 `. + .. 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 diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 2488a909ec..4892333d8c 100644 --- a/Doc/library/asyncio-task.rst +++ b/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 `. 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 `. + .. 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. diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst index ac697191b5..af2aad9e81 100644 --- a/Doc/whatsnew/3.7.rst +++ b/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() `, + :meth:`loop.call_soon_threadsafe() `, + :meth:`loop.call_later() `, + :meth:`loop.call_at() `, and + :meth:`Future.add_done_callback() ` + have a new optional keyword-only *context* parameter. + :class:`Tasks ` 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`.) diff --git a/Misc/NEWS.d/next/Documentation/2018-05-23-11-59-51.bpo-32436.S1LGPa.rst b/Misc/NEWS.d/next/Documentation/2018-05-23-11-59-51.bpo-32436.S1LGPa.rst new file mode 100644 index 0000000000..8eeb561921 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2018-05-23-11-59-51.bpo-32436.S1LGPa.rst @@ -0,0 +1 @@ +Document PEP 567 changes to asyncio.