(Merge 3.4) asyncio doc: explain how to pass keywords to callbacks

(functools.partial)
This commit is contained in:
Victor Stinner 2014-11-28 13:16:03 +01:00
commit 07ff92a0d2
2 changed files with 38 additions and 0 deletions

View File

@ -67,10 +67,22 @@ Run an event loop
This is idempotent and irreversible. No other methods should be called after This is idempotent and irreversible. No other methods should be called after
this one. this one.
.. _asyncio-pass-keywords:
Calls Calls
----- -----
Most :mod:`asyncio` functions don't accept keywords. If you want to pass
keywords to your callback, use :func:`functools.partial`. For example,
``loop.call_soon(functools.partial(print, "Hello", flush=True))`` will call
``print("Hello", flush=True)``.
.. note::
:func:`functools.partial` is better than ``lambda`` functions, because
:mod:`asyncio` can inspect :func:`functools.partial` object to display
parameters in debug mode, whereas ``lambda`` functions have a poor
representation.
.. method:: BaseEventLoop.call_soon(callback, \*args) .. method:: BaseEventLoop.call_soon(callback, \*args)
Arrange for a callback to be called as soon as possible. Arrange for a callback to be called as soon as possible.
@ -83,6 +95,9 @@ Calls
An instance of :class:`asyncio.Handle` is returned. An instance of :class:`asyncio.Handle` is returned.
:ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`.
.. method:: BaseEventLoop.call_soon_threadsafe(callback, \*args) .. method:: BaseEventLoop.call_soon_threadsafe(callback, \*args)
Like :meth:`call_soon`, but thread safe. Like :meth:`call_soon`, but thread safe.
@ -118,6 +133,9 @@ 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`.
:ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`.
.. method:: BaseEventLoop.call_at(when, callback, *args) .. method:: BaseEventLoop.call_at(when, callback, *args)
Arrange for the *callback* to be called at the given absolute timestamp Arrange for the *callback* to be called at the given absolute timestamp
@ -126,6 +144,9 @@ a different clock than :func:`time.time`.
This method's behavior is the same as :meth:`call_later`. This method's behavior is the same as :meth:`call_later`.
:ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`.
.. method:: BaseEventLoop.time() .. method:: BaseEventLoop.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
@ -334,6 +355,9 @@ On Windows with :class:`ProactorEventLoop`, these methods are not supported.
Start watching the file descriptor for read availability and then call the Start watching the file descriptor for read availability and then call the
*callback* with specified arguments. *callback* with specified arguments.
:ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`.
.. method:: BaseEventLoop.remove_reader(fd) .. method:: BaseEventLoop.remove_reader(fd)
Stop watching the file descriptor for read availability. Stop watching the file descriptor for read availability.
@ -343,6 +367,9 @@ On Windows with :class:`ProactorEventLoop`, these methods are not supported.
Start watching the file descriptor for write availability and then call the Start watching the file descriptor for write availability and then call the
*callback* with specified arguments. *callback* with specified arguments.
:ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`.
.. method:: BaseEventLoop.remove_writer(fd) .. method:: BaseEventLoop.remove_writer(fd)
Stop watching the file descriptor for write availability. Stop watching the file descriptor for write availability.
@ -493,6 +520,9 @@ Availability: UNIX only.
Raise :exc:`ValueError` if the signal number is invalid or uncatchable. Raise :exc:`ValueError` if the signal number is invalid or uncatchable.
Raise :exc:`RuntimeError` if there is a problem setting up the handler. Raise :exc:`RuntimeError` if there is a problem setting up the handler.
:ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`.
.. method:: BaseEventLoop.remove_signal_handler(sig) .. method:: BaseEventLoop.remove_signal_handler(sig)
Remove a handler for a signal. Remove a handler for a signal.
@ -518,6 +548,9 @@ pool of processes). By default, an event loop uses a thread pool executor
The *executor* argument should be an :class:`~concurrent.futures.Executor` The *executor* argument should be an :class:`~concurrent.futures.Executor`
instance. The default executor is used if *executor* is ``None``. instance. The default executor is used if *executor* is ``None``.
:ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`.
This method is a :ref:`coroutine <coroutine>`. This method is a :ref:`coroutine <coroutine>`.
.. method:: BaseEventLoop.set_default_executor(executor) .. method:: BaseEventLoop.set_default_executor(executor)

View File

@ -253,6 +253,11 @@ Future
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:`~BaseEventLoop.call_soon`. with :meth:`~BaseEventLoop.call_soon`.
: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)``.
.. 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.