[Python-checkins] cpython: asyncio: document iscoroutine(), iscoroutinefunction() and wait_for()

[victor.stinner]

http://hg.python.org/cpython/rev/d5ad8bd335f5
changeset:   88831:d5ad8bd335f5
user:        Victor Stinner <victor.stinner at gmail.com>
date:        Thu Jan 30 00:18:50 2014 +0100
summary:
  asyncio: document iscoroutine(), iscoroutinefunction() and wait_for()

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

files:
  Doc/library/asyncio-task.rst |  30 ++++++++++++++++++++++-
  1 files changed, 28 insertions(+), 2 deletions(-)


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
@@ -20,12 +20,13 @@
 
 - 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 @@
    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 @@
       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)
+

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