asyncio doc: explain how to pass keywords to callbacks (functools.partial)

This commit is contained in:
Victor Stinner 2014-11-28 13:15:41 +01:00
parent 25c7d3fb21
commit 8464c24c82
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 one.
.. _asyncio-pass-keywords:
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)
Arrange for a callback to be called as soon as possible.
@ -83,6 +95,9 @@ Calls
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)
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
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)
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`.
:ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`.
.. method:: BaseEventLoop.time()
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
*callback* with specified arguments.
:ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`.
.. method:: BaseEventLoop.remove_reader(fd)
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
*callback* with specified arguments.
:ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`.
.. method:: BaseEventLoop.remove_writer(fd)
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:`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)
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`
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>`.
.. 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
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)
Remove all instances of a callback from the "call when done" list.