From 8464c24c82f3fc0d15afe85f86ac6b0ccd3e65d3 Mon Sep 17 00:00:00 2001
From: Victor Stinner <victor.stinner@gmail.com>
Date: Fri, 28 Nov 2014 13:15:41 +0100
Subject: [PATCH] asyncio doc: explain how to pass keywords to callbacks
 (functools.partial)

---
 Doc/library/asyncio-eventloop.rst | 33 +++++++++++++++++++++++++++++++
 Doc/library/asyncio-task.rst      |  5 +++++
 2 files changed, 38 insertions(+)

diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index 18d873881bc..d6c2e30df44 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 21c4e339f57..a07db2930a7 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.