From: Ben Darnell <ben@bendarnell.com>
Date: Mon, 19 Jan 2015 17:34:19 +0000 (-0500)
Subject: Document convert_yielded.
X-Git-Tag: v4.1.0b1~9
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b85f775f34057976327616b641471cb3544143d6;p=thirdparty%2Ftornado.git

Document convert_yielded.
---

diff --git a/docs/asyncio.rst b/docs/asyncio.rst
index e7c2c8fd9..b9e7459cb 100644
--- a/docs/asyncio.rst
+++ b/docs/asyncio.rst
@@ -45,3 +45,15 @@ loops.
 
     Each ``AsyncIOLoop`` creates a new ``asyncio.EventLoop``; this object
     can be accessed with the ``asyncio_loop`` attribute.
+
+.. py:function:: to_tornado_future
+
+   Convert an ``asyncio.Future`` to a `tornado.concurrent.Future`.
+
+   .. versionadded:: 4.1
+
+.. py:function:: to_asyncio_future
+
+   Convert a `tornado.concurrent.Future` to an ``asyncio.Future``.
+
+   .. versionadded:: 4.1
diff --git a/docs/gen.rst b/docs/gen.rst
index c010ed418..e9a7e5c53 100644
--- a/docs/gen.rst
+++ b/docs/gen.rst
@@ -34,6 +34,8 @@
       used either as a tuple ``(args, kwargs)`` or an object with attributes
       ``args`` and ``kwargs``.
 
+   .. autofunction:: convert_yielded
+
    Legacy interface
    ----------------
 
diff --git a/tornado/gen.py b/tornado/gen.py
index f41cbafd9..c9c6f5c1d 100644
--- a/tornado/gen.py
+++ b/tornado/gen.py
@@ -43,8 +43,21 @@ be returned when they are all finished::
         response3 = response_dict['response3']
         response4 = response_dict['response4']
 
+If the `~functools.singledispatch` library is available (standard in
+Python 3.4, available via the `singledispatch
+<https://pypi.python.org/pypi/singledispatch>`_ package on older
+versions), additional types of objects may be yielded. Tornado includes
+support for ``asyncio.Future`` and Twisted's ``Deferred`` class when
+``tornado.platform.asyncio`` and ``tornado.platform.twisted`` are imported.
+See the `convert_yielded` function to extend this mechanism.
+
 .. versionchanged:: 3.2
    Dict support added.
+
+.. versionchanged:: 4.1
+   Support added for yielding ``asyncio`` Futures and Twisted Deferreds
+   via ``singledispatch``.
+
 """
 from __future__ import absolute_import, division, print_function, with_statement
 
@@ -900,6 +913,19 @@ def _argument_adapter(callback):
 
 
 def convert_yielded(yielded):
+    """Convert a yielded object into a `.Future`.
+
+    The default implementation accepts lists, dictionaries, and Futures.
+
+    If the `~functools.singledispatch` library is available, this function
+    may be extended to support additional types. For example::
+
+        @convert_yielded.register(asyncio.Future)
+        def _(asyncio_future):
+            return tornado.platform.asyncio.to_tornado_future(asyncio_future)
+
+    .. versionadded:: 4.1
+    """
     # Lists and dicts containing YieldPoints were handled separately
     # via Multi().
     if isinstance(yielded, (list, dict)):