docs/asyncio: Document new ensure_future() and deprecated async()

3 files changed, 28 insertions, 20 deletions

diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst
index d7f474e..3a196db 100644
--- a/Doc/library/asyncio-dev.rst
+++ b/Doc/library/asyncio-dev.rst
@@ -210,7 +210,7 @@ Example of unhandled exception::
         raise Exception("not consumed")
 
     loop = asyncio.get_event_loop()
-    asyncio.async(bug())
+    asyncio.ensure_future(bug())
     loop.run_forever()
     loop.close()
 
@@ -234,7 +234,7 @@ traceback where the task was created. Output in debug mode::
     future: <Task finished coro=<bug() done, defined at test.py:3> exception=Exception('not consumed',) created at test.py:8>
     source_traceback: Object created at (most recent call last):
       File "test.py", line 8, in <module>
-        asyncio.async(bug())
+        asyncio.ensure_future(bug())
     Traceback (most recent call last):
       File "asyncio/tasks.py", line 237, in _step
         result = next(coro)
@@ -257,14 +257,14 @@ coroutine in another coroutine and use classic try/except::
             print("exception consumed")
 
     loop = asyncio.get_event_loop()
-    asyncio.async(handle_exception())
+    asyncio.ensure_future(handle_exception())
     loop.run_forever()
     loop.close()
 
 Another option is to use the :meth:`BaseEventLoop.run_until_complete`
 function::
 
-    task = asyncio.async(bug())
+    task = asyncio.ensure_future(bug())
     try:
         loop.run_until_complete(task)
     except Exception:
@@ -303,14 +303,14 @@ operations::
 
     @asyncio.coroutine
     def test():
-        asyncio.async(create())
-        asyncio.async(write())
-        asyncio.async(close())
+        asyncio.ensure_future(create())
+        asyncio.ensure_future(write())
+        asyncio.ensure_future(close())
         yield from asyncio.sleep(2.0)
         loop.stop()
 
     loop = asyncio.get_event_loop()
-    asyncio.async(test())
+    asyncio.ensure_future(test())
     loop.run_forever()
     print("Pending tasks at exit: %s" % asyncio.Task.all_tasks(loop))
     loop.close()
@@ -338,13 +338,13 @@ To fix the example, tasks must be marked with ``yield from``::
 
     @asyncio.coroutine
     def test():
-        yield from asyncio.async(create())
-        yield from asyncio.async(write())
-        yield from asyncio.async(close())
+        yield from asyncio.ensure_future(create())
+        yield from asyncio.ensure_future(write())
+        yield from asyncio.ensure_future(close())
         yield from asyncio.sleep(2.0)
         loop.stop()
 
-Or without ``asyncio.async()``::
+Or without ``asyncio.ensure_future()``::
 
     @asyncio.coroutine
     def test():
@@ -374,7 +374,7 @@ traceback where the task was created. Example of log in debug mode::
     Task was destroyed but it is pending!
     source_traceback: Object created at (most recent call last):
       File "test.py", line 15, in <module>
-        task = asyncio.async(coro, loop=loop)
+        task = asyncio.ensure_future(coro, loop=loop)
     task: <Task pending coro=<kill_me() done, defined at test.py:5> wait_for=<Future pending cb=[Task._wakeup()] created at test.py:7> created at test.py:15>
 
 
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 41b24ac..e9638e3 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -364,7 +364,7 @@ Simple example querying HTTP headers of the URL passed on the command line::
 
     url = sys.argv[1]
     loop = asyncio.get_event_loop()
-    task = asyncio.async(print_http_headers(url))
+    task = asyncio.ensure_future(print_http_headers(url))
     loop.run_until_complete(task)
     loop.close()
 
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index 8392967..e7ff7d2 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -296,7 +296,7 @@ Example combining a :class:`Future` and a :ref:`coroutine function
 
     loop = asyncio.get_event_loop()
     future = asyncio.Future()
-    asyncio.async(slow_operation(future))
+    asyncio.ensure_future(slow_operation(future))
     loop.run_until_complete(future)
     print(future.result())
     loop.close()
@@ -332,7 +332,7 @@ flow::
 
     loop = asyncio.get_event_loop()
     future = asyncio.Future()
-    asyncio.async(slow_operation(future))
+    asyncio.ensure_future(slow_operation(future))
     future.add_done_callback(got_result)
     try:
         loop.run_forever()
@@ -461,9 +461,9 @@ Example executing 3 tasks (A, B, C) in parallel::
 
     loop = asyncio.get_event_loop()
     tasks = [
-        asyncio.async(factorial("A", 2)),
-        asyncio.async(factorial("B", 3)),
-        asyncio.async(factorial("C", 4))]
+        asyncio.ensure_future(factorial("A", 2)),
+        asyncio.ensure_future(factorial("B", 3)),
+        asyncio.ensure_future(factorial("C", 4))]
     loop.run_until_complete(asyncio.wait(tasks))
     loop.close()
 
@@ -510,17 +510,25 @@ Task functions
 
       The futures ``f`` are not necessarily members of fs.
 
-.. function:: async(coro_or_future, \*, loop=None)
+.. function:: ensure_future(coro_or_future, \*, loop=None)
 
    Schedule the execution of a :ref:`coroutine object <coroutine>`: wrap it in
    a future. Return a :class:`Task` object.
 
    If the argument is a :class:`Future`, it is returned directly.
 
+   .. versionadded:: 3.4.4
+
    .. seealso::
 
       The :meth:`BaseEventLoop.create_task` method.
 
+.. function:: async(coro_or_future, \*, loop=None)
+
+   A deprecated alias to :func:`ensure_future`.
+
+   .. deprecated:: 3.4.4
+
 .. function:: gather(\*coros_or_futures, loop=None, return_exceptions=False)
 
    Return a future aggregating results from the given coroutine objects or