[Python-checkins] cpython (3.4): Issue #22112, asyncio doc: replace loop.create_task(coro) with

[victor.stinner]

http://hg.python.org/cpython/rev/d0ea92701b1e
changeset:   92069:d0ea92701b1e
branch:      3.4
parent:      92067:51472399ca09
user:        Victor Stinner <victor.stinner at gmail.com>
date:        Mon Aug 11 01:11:13 2014 +0200
summary:
  Issue #22112, asyncio doc: replace loop.create_task(coro) with
asyncio.async(coro), mention that asyncio.async() can be used to scheduler a
coroutine, and make it clear that create_task() is only available in Python
3.4.2 and later.

files:
  Doc/library/asyncio-eventloop.rst |   5 +--
  Doc/library/asyncio-stream.rst    |   2 +-
  Doc/library/asyncio-task.rst      |  28 ++++++++++--------
  3 files changed, 19 insertions(+), 16 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
@@ -147,9 +147,8 @@
    interoperability. In this case, the result type is a subclass of
    :class:`Task`.
 
-   .. seealso::
-
-      The :meth:`async` function.
+   This method was added in Python 3.4.2. Use the :func:`async` function to
+   support also older Python versions.
 
    .. versionadded:: 3.4.2
 
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -43,7 +43,7 @@
    :class:`StreamWriter` object.  The *client_connected_cb* parameter can
    either be a plain callback function or a :ref:`coroutine function
    <coroutine>`; if it is a coroutine function, it will be automatically
-   wrapped in a future using the :meth:`BaseEventLoop.create_task` method.
+   converted into a :class:`Task`.
 
    The rest of the arguments are all the usual arguments to
    :meth:`~BaseEventLoop.create_server()` except *protocol_factory*; most
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
@@ -52,7 +52,9 @@
 In the case of a coroutine object, there are two basic ways to start
 it running: call ``yield from coroutine`` from another coroutine
 (assuming the other coroutine is already running!), or schedule its execution
-using the :meth:`BaseEventLoop.create_task` method.
+using the :func:`async` function or the :meth:`BaseEventLoop.create_task`
+method.
+
 
 Coroutines (and tasks) can only run when the event loop is running.
 
@@ -256,7 +258,7 @@
 
     loop = asyncio.get_event_loop()
     future = asyncio.Future()
-    loop.create_task(slow_operation(future))
+    asyncio.async(slow_operation(future))
     loop.run_until_complete(future)
     print(future.result())
     loop.close()
@@ -292,7 +294,7 @@
 
     loop = asyncio.get_event_loop()
     future = asyncio.Future()
-    loop.create_task(slow_operation(future))
+    asyncio.async(slow_operation(future))
     future.add_done_callback(got_result)
     try:
         loop.run_forever()
@@ -339,8 +341,8 @@
    <coroutine>` did not complete. It is probably a bug and a warning is
    logged: see :ref:`Pending task destroyed <asyncio-pending-task-destroyed>`.
 
-   Don't create directly :class:`Task` instances: use the
-   :meth:`BaseEventLoop.create_task` method.
+   Don't create directly :class:`Task` instances: use the :func:`async`
+   function or the :meth:`BaseEventLoop.create_task` method.
 
    .. classmethod:: all_tasks(loop=None)
 
@@ -424,9 +426,9 @@
 
     loop = asyncio.get_event_loop()
     tasks = [
-        loop.create_task(factorial("A", 2)),
-        loop.create_task(factorial("B", 3)),
-        loop.create_task(factorial("C", 4))]
+        asyncio.async(factorial("A", 2)),
+        asyncio.async(factorial("B", 3)),
+        asyncio.async(factorial("C", 4))]
     loop.run_until_complete(asyncio.wait(tasks))
     loop.close()
 
@@ -475,11 +477,14 @@
 
 .. function:: async(coro_or_future, \*, loop=None)
 
-   Wrap a :ref:`coroutine object <coroutine>` in a future using the
-   :meth:`BaseEventLoop.create_task` method.
+   Wrap a :ref:`coroutine object <coroutine>` in a future.
 
    If the argument is a :class:`Future`, it is returned directly.
 
+   .. seealso::
+
+      The :meth:`BaseEventLoop.create_task` method.
+
 .. function:: gather(\*coros_or_futures, loop=None, return_exceptions=False)
 
    Return a future aggregating results from the given coroutine objects or
@@ -595,8 +600,7 @@
    to complete with timeout. If *timeout* is ``None``, block until the future
    completes.
 
-   Coroutine objects are wrapped in a future using the
-   :meth:`BaseEventLoop.create_task` method.
+   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:`asyncio.TimeoutError`. To avoid the task

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