[Python-checkins] cpython (merge 3.4 -> default): (Merge 3.4) asyncio doc: explain how to pass keywords to callbacks

[victor.stinner]

https://hg.python.org/cpython/rev/29645775b75c
changeset:   93641:29645775b75c
parent:      93639:ef5bbdc81796
parent:      93640:8dacb1a21793
user:        Victor Stinner <victor.stinner at gmail.com>
date:        Fri Nov 28 13:16:03 2014 +0100
summary:
  (Merge 3.4) asyncio doc: explain how to pass keywords to callbacks
(functools.partial)

files:
  Doc/library/asyncio-eventloop.rst |  33 +++++++++++++++++++
  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
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -67,10 +67,22 @@
    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 @@
 
    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 @@
    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 @@
 
    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 @@
    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 @@
    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 @@
    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 @@
    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
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -253,6 +253,11 @@
       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.

-- 
Repository URL: https://hg.python.org/cpython