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

(cherry picked from commit 28b9178023)

Co-authored-by: Yury Selivanov <yury@magic.io>
This commit is contained in:
Miss Islington (bot) 2018-05-23 10:59:17 -07:00 committed by GitHub
parent 0f9b68a728
commit 2fc443c469
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 57 additions and 6 deletions

View file

@ -124,7 +124,7 @@ keywords to your callback, use :func:`functools.partial`. For example,
parameters in debug mode, whereas ``lambda`` functions have a poor parameters in debug mode, whereas ``lambda`` functions have a poor
representation. 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 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 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 Any positional arguments after the callback will be passed to the
callback when it is called. 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 An instance of :class:`asyncio.Handle` is returned, which can be
used to cancel the callback. used to cancel the callback.
:ref:`Use functools.partial to pass keywords to the callback :ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`. <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. Like :meth:`call_soon`, but thread safe.
See the :ref:`concurrency and multithreading <asyncio-multithreading>` See the :ref:`concurrency and multithreading <asyncio-multithreading>`
section of the documentation. section of the documentation.
.. versionchanged:: 3.7
The *context* keyword-only parameter was added. See :pep:`567`
for more details.
.. _asyncio-delayed-calls: .. _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. 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* Arrange for the *callback* to be called after the given *delay*
seconds (either an int or float). 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 is called. If you want the callback to be called with some named
arguments, use a closure or :func:`functools.partial`. 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 :ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`. <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 Arrange for the *callback* to be called at the given absolute timestamp
*when* (an int or float), using the same time reference as *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 :ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`. <asyncio-pass-keywords>`.
.. versionchanged:: 3.7
The *context* keyword-only parameter was added. See :pep:`567`
for more details.
.. method:: AbstractEventLoop.time() .. method:: AbstractEventLoop.time()
Return the current time, as a :class:`float` value, according to the Return the current time, as a :class:`float` value, according to the

View file

@ -275,19 +275,27 @@ Future
:exc:`CancelledError`. If the future isn't done yet, raises :exc:`CancelledError`. If the future isn't done yet, raises
:exc:`InvalidStateError`. :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. 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 future is already done when this is called, the callback is scheduled
with :meth:`~AbstractEventLoop.call_soon`. 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 :ref:`Use functools.partial to pass parameters to the callback
<asyncio-pass-keywords>`. For example, <asyncio-pass-keywords>`. For example,
``fut.add_done_callback(functools.partial(print, "Future:", ``fut.add_done_callback(functools.partial(print, "Future:",
flush=True))`` will call ``print("Future:", fut, flush=True)``. 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) .. method:: remove_done_callback(fn)
Remove all instances of a callback from the "call when done" list. 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` Don't directly create :class:`Task` instances: use the :func:`create_task`
function or the :meth:`AbstractEventLoop.create_task` method. 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>`. This class is :ref:`not thread safe <asyncio-multithreading>`.
.. versionchanged:: 3.7
Added support for the :mod:`contextvars` module.
.. classmethod:: all_tasks(loop=None) .. classmethod:: all_tasks(loop=None)
Return a set of all tasks for an event loop. Return a set of all tasks for an event loop.

View file

@ -608,6 +608,17 @@ include:
destroying the event loop. destroying the event loop.
(Contributed by Yury Selivanov in :issue:`32314`.) (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 * The new :func:`asyncio.create_task` function has been added as a shortcut
to ``asyncio.get_event_loop().create_task()``. to ``asyncio.get_event_loop().create_task()``.
(Contributed by Andrew Svetlov in :issue:`32311`.) (Contributed by Andrew Svetlov in :issue:`32311`.)

View file

@ -0,0 +1 @@
Document PEP 567 changes to asyncio.