[Python-checkins] cpython (merge 3.4 -> default): Merge 3.4 (asyncio docs)

[yury.selivanov]

https://hg.python.org/cpython/rev/90ff2b9e9244
changeset:   95962:90ff2b9e9244
parent:      95959:976223ff4566
parent:      95961:9d9e445d25dc
user:        Yury Selivanov <yselivanov at sprymix.com>
date:        Mon May 11 16:34:13 2015 -0400
summary:
  Merge 3.4 (asyncio docs)

files:
  Doc/library/asyncio-dev.rst       |  26 +++++++++---------
  Doc/library/asyncio-eventloop.rst |  20 ++++++++++++++
  Doc/library/asyncio-stream.rst    |   2 +-
  Doc/library/asyncio-task.rst      |  20 ++++++++++----
  4 files changed, 48 insertions(+), 20 deletions(-)


diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst
--- a/Doc/library/asyncio-dev.rst
+++ b/Doc/library/asyncio-dev.rst
@@ -210,7 +210,7 @@
         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 @@
     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 @@
             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 @@
 
     @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 @@
 
     @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 @@
     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-eventloop.rst b/Doc/library/asyncio-eventloop.rst
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -181,6 +181,26 @@
 
    .. versionadded:: 3.4.2
 
+.. method:: BaseEventLoop.set_task_factory(factory)
+
+   Set a task factory that will be used by
+   :meth:`BaseEventLoop.create_task`.
+
+   If *factory* is ``None`` the default task factory will be set.
+
+   If *factory* is a *callable*, it should have a signature matching
+   ``(loop, coro)``, where *loop* will be a reference to the active
+   event loop, *coro* will be a coroutine object.  The callable
+   must return an :class:`asyncio.Future` compatible object.
+
+   .. versionadded:: 3.4.4
+
+.. method:: BaseEventLoop.get_task_factory()
+
+   Return a task factory, or ``None`` if the default one is in use.
+
+   .. versionadded:: 3.4.4
+
 
 Creating connections
 --------------------
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
@@ -364,7 +364,7 @@
 
     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
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -296,7 +296,7 @@
 
     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 @@
 
     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 @@
 
     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 @@
 
       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

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