From: Victor Stinner <victor.stinner@gmail.com>
Date: Wed, 29 Jan 2014 23:18:50 +0000 (+0100)
Subject: asyncio: document iscoroutine(), iscoroutinefunction() and wait_for()
X-Git-Tag: v3.4.0rc1~177
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=1ad5afc050778759dcbd6e338d9bd94ae2211a43;p=python

asyncio: document iscoroutine(), iscoroutinefunction() and wait_for()

Mention that wait_for() now accepts None for the timeout.
---

diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index 8630f8262d..9bdf1c13f8 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -20,12 +20,13 @@ different (though related) concepts:
 
 - The function that defines a coroutine (a function definition
   decorated with ``@asyncio.coroutine``).  If disambiguation is needed
-  we will call this a *coroutine function*.
+  we will call this a *coroutine function* (:func:`iscoroutinefunction`
+  returns ``True``).
 
 - The object obtained by calling a coroutine function.  This object
   represents a computation or an I/O operation (usually a combination)
   that will complete eventually.  If disambiguation is needed we will
-  call it a *coroutine object*.
+  call it a *coroutine object* (:func:`iscoroutine` returns ``True``).
 
 Things a coroutine can do:
 
@@ -425,6 +426,15 @@ Task functions
    outer Future is *not* cancelled in this case.  (This is to prevent the
    cancellation of one child to cause other children to be cancelled.)
 
+.. function:: iscoroutine(obj)
+
+   Return ``True`` if *obj* is a :ref:`coroutine object <coroutine>`.
+
+.. function:: iscoroutinefunction(obj)
+
+   Return ``True`` if *func* is a decorated :ref:`coroutine function
+   <coroutine>`.
+
 .. function:: sleep(delay, result=None, \*, loop=None)
 
    Create a :ref:`coroutine object <coroutine>` that completes after a given
@@ -501,3 +511,19 @@ Task functions
       the timeout occurs are returned in the second set.
 
 
+.. function:: wait_for(fut, timeout, \*, loop=None)
+
+   Wait for the single :class:`Future` or :ref:`coroutine object <coroutine>`
+   to complete, with timeout. If *timeout* is ``None``, block until the future
+   completes.
+
+   Coroutine will be wrapped in :class:`Task`.
+
+   Returns result of the Future or coroutine.  When a timeout occurs, it
+   cancels the task and raises :exc:`TimeoutError`. To avoid the task
+   cancellation, wrap it in :func:`shield`.
+
+   Usage::
+
+        result = yield from asyncio.wait_for(fut, 60.0)
+