diff options
| -rw-r--r-- | Doc/library/asyncio-eventloop.rst | 33 | ||||
| -rw-r--r-- | Doc/library/asyncio-task.rst | 5 |
2 files changed, 38 insertions, 0 deletions
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 18d8738..d6c2e30 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -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) diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 21c4e33..a07db29 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -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. |