From d7e19bb566889343f39c34c98bca4d6db61b53d7 Mon Sep 17 00:00:00 2001 From: Yury Selivanov Date: Mon, 11 May 2015 16:33:41 -0400 Subject: docs/asyncio: Document new ensure_future() and deprecated async() --- Doc/library/asyncio-dev.rst | 26 +++++++++++++------------- Doc/library/asyncio-stream.rst | 2 +- Doc/library/asyncio-task.rst | 20 ++++++++++++++------ 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: exception=Exception('not consumed',) created at test.py:8> source_traceback: Object created at (most recent call last): File "test.py", line 8, in - 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 - task = asyncio.async(coro, loop=loop) + task = asyncio.ensure_future(coro, loop=loop) task: wait_for= 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 `: 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 -- cgit v0.12