1.. currentmodule:: asyncio 2 3 4==================== 5Coroutines and Tasks 6==================== 7 8This section outlines high-level asyncio APIs to work with coroutines 9and Tasks. 10 11.. contents:: 12 :depth: 1 13 :local: 14 15 16.. _coroutine: 17 18Coroutines 19========== 20 21:term:`Coroutines <coroutine>` declared with the async/await syntax is the 22preferred way of writing asyncio applications. For example, the following 23snippet of code (requires Python 3.7+) prints "hello", waits 1 second, 24and then prints "world":: 25 26 >>> import asyncio 27 28 >>> async def main(): 29 ... print('hello') 30 ... await asyncio.sleep(1) 31 ... print('world') 32 33 >>> asyncio.run(main()) 34 hello 35 world 36 37Note that simply calling a coroutine will not schedule it to 38be executed:: 39 40 >>> main() 41 <coroutine object main at 0x1053bb7c8> 42 43To actually run a coroutine, asyncio provides three main mechanisms: 44 45* The :func:`asyncio.run` function to run the top-level 46 entry point "main()" function (see the above example.) 47 48* Awaiting on a coroutine. The following snippet of code will 49 print "hello" after waiting for 1 second, and then print "world" 50 after waiting for *another* 2 seconds:: 51 52 import asyncio 53 import time 54 55 async def say_after(delay, what): 56 await asyncio.sleep(delay) 57 print(what) 58 59 async def main(): 60 print(f"started at {time.strftime('%X')}") 61 62 await say_after(1, 'hello') 63 await say_after(2, 'world') 64 65 print(f"finished at {time.strftime('%X')}") 66 67 asyncio.run(main()) 68 69 Expected output:: 70 71 started at 17:13:52 72 hello 73 world 74 finished at 17:13:55 75 76* The :func:`asyncio.create_task` function to run coroutines 77 concurrently as asyncio :class:`Tasks <Task>`. 78 79 Let's modify the above example and run two ``say_after`` coroutines 80 *concurrently*:: 81 82 async def main(): 83 task1 = asyncio.create_task( 84 say_after(1, 'hello')) 85 86 task2 = asyncio.create_task( 87 say_after(2, 'world')) 88 89 print(f"started at {time.strftime('%X')}") 90 91 # Wait until both tasks are completed (should take 92 # around 2 seconds.) 93 await task1 94 await task2 95 96 print(f"finished at {time.strftime('%X')}") 97 98 Note that expected output now shows that the snippet runs 99 1 second faster than before:: 100 101 started at 17:14:32 102 hello 103 world 104 finished at 17:14:34 105 106 107.. _asyncio-awaitables: 108 109Awaitables 110========== 111 112We say that an object is an **awaitable** object if it can be used 113in an :keyword:`await` expression. Many asyncio APIs are designed to 114accept awaitables. 115 116There are three main types of *awaitable* objects: 117**coroutines**, **Tasks**, and **Futures**. 118 119 120.. rubric:: Coroutines 121 122Python coroutines are *awaitables* and therefore can be awaited from 123other coroutines:: 124 125 import asyncio 126 127 async def nested(): 128 return 42 129 130 async def main(): 131 # Nothing happens if we just call "nested()". 132 # A coroutine object is created but not awaited, 133 # so it *won't run at all*. 134 nested() 135 136 # Let's do it differently now and await it: 137 print(await nested()) # will print "42". 138 139 asyncio.run(main()) 140 141.. important:: 142 143 In this documentation the term "coroutine" can be used for 144 two closely related concepts: 145 146 * a *coroutine function*: an :keyword:`async def` function; 147 148 * a *coroutine object*: an object returned by calling a 149 *coroutine function*. 150 151asyncio also supports legacy :ref:`generator-based 152<asyncio_generator_based_coro>` coroutines. 153 154 155.. rubric:: Tasks 156 157*Tasks* are used to schedule coroutines *concurrently*. 158 159When a coroutine is wrapped into a *Task* with functions like 160:func:`asyncio.create_task` the coroutine is automatically 161scheduled to run soon:: 162 163 import asyncio 164 165 async def nested(): 166 return 42 167 168 async def main(): 169 # Schedule nested() to run soon concurrently 170 # with "main()". 171 task = asyncio.create_task(nested()) 172 173 # "task" can now be used to cancel "nested()", or 174 # can simply be awaited to wait until it is complete: 175 await task 176 177 asyncio.run(main()) 178 179 180.. rubric:: Futures 181 182A :class:`Future` is a special **low-level** awaitable object that 183represents an **eventual result** of an asynchronous operation. 184 185When a Future object is *awaited* it means that the coroutine will 186wait until the Future is resolved in some other place. 187 188Future objects in asyncio are needed to allow callback-based code 189to be used with async/await. 190 191Normally **there is no need** to create Future objects at the 192application level code. 193 194Future objects, sometimes exposed by libraries and some asyncio 195APIs, can be awaited:: 196 197 async def main(): 198 await function_that_returns_a_future_object() 199 200 # this is also valid: 201 await asyncio.gather( 202 function_that_returns_a_future_object(), 203 some_python_coroutine() 204 ) 205 206A good example of a low-level function that returns a Future object 207is :meth:`loop.run_in_executor`. 208 209 210Running an asyncio Program 211========================== 212 213.. function:: run(coro, \*, debug=False) 214 215 Execute the :term:`coroutine` *coro* and return the result. 216 217 This function runs the passed coroutine, taking care of 218 managing the asyncio event loop, *finalizing asynchronous 219 generators*, and closing the threadpool. 220 221 This function cannot be called when another asyncio event loop is 222 running in the same thread. 223 224 If *debug* is ``True``, the event loop will be run in debug mode. 225 226 This function always creates a new event loop and closes it at 227 the end. It should be used as a main entry point for asyncio 228 programs, and should ideally only be called once. 229 230 Example:: 231 232 async def main(): 233 await asyncio.sleep(1) 234 print('hello') 235 236 asyncio.run(main()) 237 238 .. versionadded:: 3.7 239 240 .. versionchanged:: 3.9 241 Updated to use :meth:`loop.shutdown_default_executor`. 242 243 .. note:: 244 The source code for ``asyncio.run()`` can be found in 245 :source:`Lib/asyncio/runners.py`. 246 247Creating Tasks 248============== 249 250.. function:: create_task(coro, \*, name=None) 251 252 Wrap the *coro* :ref:`coroutine <coroutine>` into a :class:`Task` 253 and schedule its execution. Return the Task object. 254 255 If *name* is not ``None``, it is set as the name of the task using 256 :meth:`Task.set_name`. 257 258 The task is executed in the loop returned by :func:`get_running_loop`, 259 :exc:`RuntimeError` is raised if there is no running loop in 260 current thread. 261 262 This function has been **added in Python 3.7**. Prior to 263 Python 3.7, the low-level :func:`asyncio.ensure_future` function 264 can be used instead:: 265 266 async def coro(): 267 ... 268 269 # In Python 3.7+ 270 task = asyncio.create_task(coro()) 271 ... 272 273 # This works in all Python versions but is less readable 274 task = asyncio.ensure_future(coro()) 275 ... 276 277 .. versionadded:: 3.7 278 279 .. versionchanged:: 3.8 280 Added the ``name`` parameter. 281 282 283Sleeping 284======== 285 286.. coroutinefunction:: sleep(delay, result=None, \*, loop=None) 287 288 Block for *delay* seconds. 289 290 If *result* is provided, it is returned to the caller 291 when the coroutine completes. 292 293 ``sleep()`` always suspends the current task, allowing other tasks 294 to run. 295 296 .. deprecated-removed:: 3.8 3.10 297 The *loop* parameter. 298 299 .. _asyncio_example_sleep: 300 301 Example of coroutine displaying the current date every second 302 for 5 seconds:: 303 304 import asyncio 305 import datetime 306 307 async def display_date(): 308 loop = asyncio.get_running_loop() 309 end_time = loop.time() + 5.0 310 while True: 311 print(datetime.datetime.now()) 312 if (loop.time() + 1.0) >= end_time: 313 break 314 await asyncio.sleep(1) 315 316 asyncio.run(display_date()) 317 318 319Running Tasks Concurrently 320========================== 321 322.. awaitablefunction:: gather(\*aws, loop=None, return_exceptions=False) 323 324 Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws* 325 sequence *concurrently*. 326 327 If any awaitable in *aws* is a coroutine, it is automatically 328 scheduled as a Task. 329 330 If all awaitables are completed successfully, the result is an 331 aggregate list of returned values. The order of result values 332 corresponds to the order of awaitables in *aws*. 333 334 If *return_exceptions* is ``False`` (default), the first 335 raised exception is immediately propagated to the task that 336 awaits on ``gather()``. Other awaitables in the *aws* sequence 337 **won't be cancelled** and will continue to run. 338 339 If *return_exceptions* is ``True``, exceptions are treated the 340 same as successful results, and aggregated in the result list. 341 342 If ``gather()`` is *cancelled*, all submitted awaitables 343 (that have not completed yet) are also *cancelled*. 344 345 If any Task or Future from the *aws* sequence is *cancelled*, it is 346 treated as if it raised :exc:`CancelledError` -- the ``gather()`` 347 call is **not** cancelled in this case. This is to prevent the 348 cancellation of one submitted Task/Future to cause other 349 Tasks/Futures to be cancelled. 350 351 .. deprecated-removed:: 3.8 3.10 352 The *loop* parameter. 353 354 .. _asyncio_example_gather: 355 356 Example:: 357 358 import asyncio 359 360 async def factorial(name, number): 361 f = 1 362 for i in range(2, number + 1): 363 print(f"Task {name}: Compute factorial({i})...") 364 await asyncio.sleep(1) 365 f *= i 366 print(f"Task {name}: factorial({number}) = {f}") 367 368 async def main(): 369 # Schedule three calls *concurrently*: 370 await asyncio.gather( 371 factorial("A", 2), 372 factorial("B", 3), 373 factorial("C", 4), 374 ) 375 376 asyncio.run(main()) 377 378 # Expected output: 379 # 380 # Task A: Compute factorial(2)... 381 # Task B: Compute factorial(2)... 382 # Task C: Compute factorial(2)... 383 # Task A: factorial(2) = 2 384 # Task B: Compute factorial(3)... 385 # Task C: Compute factorial(3)... 386 # Task B: factorial(3) = 6 387 # Task C: Compute factorial(4)... 388 # Task C: factorial(4) = 24 389 390 .. note:: 391 If *return_exceptions* is False, cancelling gather() after it 392 has been marked done won't cancel any submitted awaitables. 393 For instance, gather can be marked done after propagating an 394 exception to the caller, therefore, calling ``gather.cancel()`` 395 after catching an exception (raised by one of the awaitables) from 396 gather won't cancel any other awaitables. 397 398 .. versionchanged:: 3.7 399 If the *gather* itself is cancelled, the cancellation is 400 propagated regardless of *return_exceptions*. 401 402 403Shielding From Cancellation 404=========================== 405 406.. awaitablefunction:: shield(aw, \*, loop=None) 407 408 Protect an :ref:`awaitable object <asyncio-awaitables>` 409 from being :meth:`cancelled <Task.cancel>`. 410 411 If *aw* is a coroutine it is automatically scheduled as a Task. 412 413 The statement:: 414 415 res = await shield(something()) 416 417 is equivalent to:: 418 419 res = await something() 420 421 *except* that if the coroutine containing it is cancelled, the 422 Task running in ``something()`` is not cancelled. From the point 423 of view of ``something()``, the cancellation did not happen. 424 Although its caller is still cancelled, so the "await" expression 425 still raises a :exc:`CancelledError`. 426 427 If ``something()`` is cancelled by other means (i.e. from within 428 itself) that would also cancel ``shield()``. 429 430 If it is desired to completely ignore cancellation (not recommended) 431 the ``shield()`` function should be combined with a try/except 432 clause, as follows:: 433 434 try: 435 res = await shield(something()) 436 except CancelledError: 437 res = None 438 439 .. deprecated-removed:: 3.8 3.10 440 The *loop* parameter. 441 442 443Timeouts 444======== 445 446.. coroutinefunction:: wait_for(aw, timeout, \*, loop=None) 447 448 Wait for the *aw* :ref:`awaitable <asyncio-awaitables>` 449 to complete with a timeout. 450 451 If *aw* is a coroutine it is automatically scheduled as a Task. 452 453 *timeout* can either be ``None`` or a float or int number of seconds 454 to wait for. If *timeout* is ``None``, block until the future 455 completes. 456 457 If a timeout occurs, it cancels the task and raises 458 :exc:`asyncio.TimeoutError`. 459 460 To avoid the task :meth:`cancellation <Task.cancel>`, 461 wrap it in :func:`shield`. 462 463 The function will wait until the future is actually cancelled, 464 so the total wait time may exceed the *timeout*. If an exception 465 happens during cancellation, it is propagated. 466 467 If the wait is cancelled, the future *aw* is also cancelled. 468 469 .. deprecated-removed:: 3.8 3.10 470 The *loop* parameter. 471 472 .. _asyncio_example_waitfor: 473 474 Example:: 475 476 async def eternity(): 477 # Sleep for one hour 478 await asyncio.sleep(3600) 479 print('yay!') 480 481 async def main(): 482 # Wait for at most 1 second 483 try: 484 await asyncio.wait_for(eternity(), timeout=1.0) 485 except asyncio.TimeoutError: 486 print('timeout!') 487 488 asyncio.run(main()) 489 490 # Expected output: 491 # 492 # timeout! 493 494 .. versionchanged:: 3.7 495 When *aw* is cancelled due to a timeout, ``wait_for`` waits 496 for *aw* to be cancelled. Previously, it raised 497 :exc:`asyncio.TimeoutError` immediately. 498 499 500Waiting Primitives 501================== 502 503.. coroutinefunction:: wait(aws, \*, loop=None, timeout=None,\ 504 return_when=ALL_COMPLETED) 505 506 Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws* 507 iterable concurrently and block until the condition specified 508 by *return_when*. 509 510 The *aws* iterable must not be empty. 511 512 Returns two sets of Tasks/Futures: ``(done, pending)``. 513 514 Usage:: 515 516 done, pending = await asyncio.wait(aws) 517 518 *timeout* (a float or int), if specified, can be used to control 519 the maximum number of seconds to wait before returning. 520 521 Note that this function does not raise :exc:`asyncio.TimeoutError`. 522 Futures or Tasks that aren't done when the timeout occurs are simply 523 returned in the second set. 524 525 *return_when* indicates when this function should return. It must 526 be one of the following constants: 527 528 .. tabularcolumns:: |l|L| 529 530 +-----------------------------+----------------------------------------+ 531 | Constant | Description | 532 +=============================+========================================+ 533 | :const:`FIRST_COMPLETED` | The function will return when any | 534 | | future finishes or is cancelled. | 535 +-----------------------------+----------------------------------------+ 536 | :const:`FIRST_EXCEPTION` | The function will return when any | 537 | | future finishes by raising an | 538 | | exception. If no future raises an | 539 | | exception then it is equivalent to | 540 | | :const:`ALL_COMPLETED`. | 541 +-----------------------------+----------------------------------------+ 542 | :const:`ALL_COMPLETED` | The function will return when all | 543 | | futures finish or are cancelled. | 544 +-----------------------------+----------------------------------------+ 545 546 Unlike :func:`~asyncio.wait_for`, ``wait()`` does not cancel the 547 futures when a timeout occurs. 548 549 .. deprecated:: 3.8 550 551 If any awaitable in *aws* is a coroutine, it is automatically 552 scheduled as a Task. Passing coroutines objects to 553 ``wait()`` directly is deprecated as it leads to 554 :ref:`confusing behavior <asyncio_example_wait_coroutine>`. 555 556 .. deprecated-removed:: 3.8 3.10 557 558 The *loop* parameter. 559 560 .. _asyncio_example_wait_coroutine: 561 .. note:: 562 563 ``wait()`` schedules coroutines as Tasks automatically and later 564 returns those implicitly created Task objects in ``(done, pending)`` 565 sets. Therefore the following code won't work as expected:: 566 567 async def foo(): 568 return 42 569 570 coro = foo() 571 done, pending = await asyncio.wait({coro}) 572 573 if coro in done: 574 # This branch will never be run! 575 576 Here is how the above snippet can be fixed:: 577 578 async def foo(): 579 return 42 580 581 task = asyncio.create_task(foo()) 582 done, pending = await asyncio.wait({task}) 583 584 if task in done: 585 # Everything will work as expected now. 586 587 .. deprecated-removed:: 3.8 3.11 588 589 Passing coroutine objects to ``wait()`` directly is 590 deprecated. 591 592 593.. function:: as_completed(aws, \*, loop=None, timeout=None) 594 595 Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws* 596 iterable concurrently. Return an iterator of coroutines. 597 Each coroutine returned can be awaited to get the earliest next 598 result from the iterable of the remaining awaitables. 599 600 Raises :exc:`asyncio.TimeoutError` if the timeout occurs before 601 all Futures are done. 602 603 .. deprecated-removed:: 3.8 3.10 604 The *loop* parameter. 605 606 Example:: 607 608 for coro in as_completed(aws): 609 earliest_result = await coro 610 # ... 611 612 613Running in Threads 614================== 615 616.. coroutinefunction:: to_thread(func, /, \*args, \*\*kwargs) 617 618 Asynchronously run function *func* in a separate thread. 619 620 Any \*args and \*\*kwargs supplied for this function are directly passed 621 to *func*. Also, the current :class:`contextvars.Context` is propagated, 622 allowing context variables from the event loop thread to be accessed in the 623 separate thread. 624 625 Return a coroutine that can be awaited to get the eventual result of *func*. 626 627 This coroutine function is primarily intended to be used for executing 628 IO-bound functions/methods that would otherwise block the event loop if 629 they were ran in the main thread. For example:: 630 631 def blocking_io(): 632 print(f"start blocking_io at {time.strftime('%X')}") 633 # Note that time.sleep() can be replaced with any blocking 634 # IO-bound operation, such as file operations. 635 time.sleep(1) 636 print(f"blocking_io complete at {time.strftime('%X')}") 637 638 async def main(): 639 print(f"started main at {time.strftime('%X')}") 640 641 await asyncio.gather( 642 asyncio.to_thread(blocking_io), 643 asyncio.sleep(1)) 644 645 print(f"finished main at {time.strftime('%X')}") 646 647 648 asyncio.run(main()) 649 650 # Expected output: 651 # 652 # started main at 19:50:53 653 # start blocking_io at 19:50:53 654 # blocking_io complete at 19:50:54 655 # finished main at 19:50:54 656 657 Directly calling `blocking_io()` in any coroutine would block the event loop 658 for its duration, resulting in an additional 1 second of run time. Instead, 659 by using `asyncio.to_thread()`, we can run it in a separate thread without 660 blocking the event loop. 661 662 .. note:: 663 664 Due to the :term:`GIL`, `asyncio.to_thread()` can typically only be used 665 to make IO-bound functions non-blocking. However, for extension modules 666 that release the GIL or alternative Python implementations that don't 667 have one, `asyncio.to_thread()` can also be used for CPU-bound functions. 668 669 .. versionadded:: 3.9 670 671 672Scheduling From Other Threads 673============================= 674 675.. function:: run_coroutine_threadsafe(coro, loop) 676 677 Submit a coroutine to the given event loop. Thread-safe. 678 679 Return a :class:`concurrent.futures.Future` to wait for the result 680 from another OS thread. 681 682 This function is meant to be called from a different OS thread 683 than the one where the event loop is running. Example:: 684 685 # Create a coroutine 686 coro = asyncio.sleep(1, result=3) 687 688 # Submit the coroutine to a given loop 689 future = asyncio.run_coroutine_threadsafe(coro, loop) 690 691 # Wait for the result with an optional timeout argument 692 assert future.result(timeout) == 3 693 694 If an exception is raised in the coroutine, the returned Future 695 will be notified. It can also be used to cancel the task in 696 the event loop:: 697 698 try: 699 result = future.result(timeout) 700 except asyncio.TimeoutError: 701 print('The coroutine took too long, cancelling the task...') 702 future.cancel() 703 except Exception as exc: 704 print(f'The coroutine raised an exception: {exc!r}') 705 else: 706 print(f'The coroutine returned: {result!r}') 707 708 See the :ref:`concurrency and multithreading <asyncio-multithreading>` 709 section of the documentation. 710 711 Unlike other asyncio functions this function requires the *loop* 712 argument to be passed explicitly. 713 714 .. versionadded:: 3.5.1 715 716 717Introspection 718============= 719 720 721.. function:: current_task(loop=None) 722 723 Return the currently running :class:`Task` instance, or ``None`` if 724 no task is running. 725 726 If *loop* is ``None`` :func:`get_running_loop` is used to get 727 the current loop. 728 729 .. versionadded:: 3.7 730 731 732.. function:: all_tasks(loop=None) 733 734 Return a set of not yet finished :class:`Task` objects run by 735 the loop. 736 737 If *loop* is ``None``, :func:`get_running_loop` is used for getting 738 current loop. 739 740 .. versionadded:: 3.7 741 742 743Task Object 744=========== 745 746.. class:: Task(coro, \*, loop=None, name=None) 747 748 A :class:`Future-like <Future>` object that runs a Python 749 :ref:`coroutine <coroutine>`. Not thread-safe. 750 751 Tasks are used to run coroutines in event loops. 752 If a coroutine awaits on a Future, the Task suspends 753 the execution of the coroutine and waits for the completion 754 of the Future. When the Future is *done*, the execution of 755 the wrapped coroutine resumes. 756 757 Event loops use cooperative scheduling: an event loop runs 758 one Task at a time. While a Task awaits for the completion of a 759 Future, the event loop runs other Tasks, callbacks, or performs 760 IO operations. 761 762 Use the high-level :func:`asyncio.create_task` function to create 763 Tasks, or the low-level :meth:`loop.create_task` or 764 :func:`ensure_future` functions. Manual instantiation of Tasks 765 is discouraged. 766 767 To cancel a running Task use the :meth:`cancel` method. Calling it 768 will cause the Task to throw a :exc:`CancelledError` exception into 769 the wrapped coroutine. If a coroutine is awaiting on a Future 770 object during cancellation, the Future object will be cancelled. 771 772 :meth:`cancelled` can be used to check if the Task was cancelled. 773 The method returns ``True`` if the wrapped coroutine did not 774 suppress the :exc:`CancelledError` exception and was actually 775 cancelled. 776 777 :class:`asyncio.Task` inherits from :class:`Future` all of its 778 APIs except :meth:`Future.set_result` and 779 :meth:`Future.set_exception`. 780 781 Tasks support the :mod:`contextvars` module. When a Task 782 is created it copies the current context and later runs its 783 coroutine in the copied context. 784 785 .. versionchanged:: 3.7 786 Added support for the :mod:`contextvars` module. 787 788 .. versionchanged:: 3.8 789 Added the ``name`` parameter. 790 791 .. deprecated-removed:: 3.8 3.10 792 The *loop* parameter. 793 794 .. method:: cancel(msg=None) 795 796 Request the Task to be cancelled. 797 798 This arranges for a :exc:`CancelledError` exception to be thrown 799 into the wrapped coroutine on the next cycle of the event loop. 800 801 The coroutine then has a chance to clean up or even deny the 802 request by suppressing the exception with a :keyword:`try` ... 803 ... ``except CancelledError`` ... :keyword:`finally` block. 804 Therefore, unlike :meth:`Future.cancel`, :meth:`Task.cancel` does 805 not guarantee that the Task will be cancelled, although 806 suppressing cancellation completely is not common and is actively 807 discouraged. 808 809 .. versionchanged:: 3.9 810 Added the ``msg`` parameter. 811 812 .. _asyncio_example_task_cancel: 813 814 The following example illustrates how coroutines can intercept 815 the cancellation request:: 816 817 async def cancel_me(): 818 print('cancel_me(): before sleep') 819 820 try: 821 # Wait for 1 hour 822 await asyncio.sleep(3600) 823 except asyncio.CancelledError: 824 print('cancel_me(): cancel sleep') 825 raise 826 finally: 827 print('cancel_me(): after sleep') 828 829 async def main(): 830 # Create a "cancel_me" Task 831 task = asyncio.create_task(cancel_me()) 832 833 # Wait for 1 second 834 await asyncio.sleep(1) 835 836 task.cancel() 837 try: 838 await task 839 except asyncio.CancelledError: 840 print("main(): cancel_me is cancelled now") 841 842 asyncio.run(main()) 843 844 # Expected output: 845 # 846 # cancel_me(): before sleep 847 # cancel_me(): cancel sleep 848 # cancel_me(): after sleep 849 # main(): cancel_me is cancelled now 850 851 .. method:: cancelled() 852 853 Return ``True`` if the Task is *cancelled*. 854 855 The Task is *cancelled* when the cancellation was requested with 856 :meth:`cancel` and the wrapped coroutine propagated the 857 :exc:`CancelledError` exception thrown into it. 858 859 .. method:: done() 860 861 Return ``True`` if the Task is *done*. 862 863 A Task is *done* when the wrapped coroutine either returned 864 a value, raised an exception, or the Task was cancelled. 865 866 .. method:: result() 867 868 Return the result of the Task. 869 870 If the Task is *done*, the result of the wrapped coroutine 871 is returned (or if the coroutine raised an exception, that 872 exception is re-raised.) 873 874 If the Task has been *cancelled*, this method raises 875 a :exc:`CancelledError` exception. 876 877 If the Task's result isn't yet available, this method raises 878 a :exc:`InvalidStateError` exception. 879 880 .. method:: exception() 881 882 Return the exception of the Task. 883 884 If the wrapped coroutine raised an exception that exception 885 is returned. If the wrapped coroutine returned normally 886 this method returns ``None``. 887 888 If the Task has been *cancelled*, this method raises a 889 :exc:`CancelledError` exception. 890 891 If the Task isn't *done* yet, this method raises an 892 :exc:`InvalidStateError` exception. 893 894 .. method:: add_done_callback(callback, *, context=None) 895 896 Add a callback to be run when the Task is *done*. 897 898 This method should only be used in low-level callback-based code. 899 900 See the documentation of :meth:`Future.add_done_callback` 901 for more details. 902 903 .. method:: remove_done_callback(callback) 904 905 Remove *callback* from the callbacks list. 906 907 This method should only be used in low-level callback-based code. 908 909 See the documentation of :meth:`Future.remove_done_callback` 910 for more details. 911 912 .. method:: get_stack(\*, limit=None) 913 914 Return the list of stack frames for this Task. 915 916 If the wrapped coroutine is not done, this returns the stack 917 where it is suspended. If the coroutine has completed 918 successfully or was cancelled, this returns an empty list. 919 If the coroutine was terminated by an exception, this returns 920 the list of traceback frames. 921 922 The frames are always ordered from oldest to newest. 923 924 Only one stack frame is returned for a suspended coroutine. 925 926 The optional *limit* argument sets the maximum number of frames 927 to return; by default all available frames are returned. 928 The ordering of the returned list differs depending on whether 929 a stack or a traceback is returned: the newest frames of a 930 stack are returned, but the oldest frames of a traceback are 931 returned. (This matches the behavior of the traceback module.) 932 933 .. method:: print_stack(\*, limit=None, file=None) 934 935 Print the stack or traceback for this Task. 936 937 This produces output similar to that of the traceback module 938 for the frames retrieved by :meth:`get_stack`. 939 940 The *limit* argument is passed to :meth:`get_stack` directly. 941 942 The *file* argument is an I/O stream to which the output 943 is written; by default output is written to :data:`sys.stderr`. 944 945 .. method:: get_coro() 946 947 Return the coroutine object wrapped by the :class:`Task`. 948 949 .. versionadded:: 3.8 950 951 .. method:: get_name() 952 953 Return the name of the Task. 954 955 If no name has been explicitly assigned to the Task, the default 956 asyncio Task implementation generates a default name during 957 instantiation. 958 959 .. versionadded:: 3.8 960 961 .. method:: set_name(value) 962 963 Set the name of the Task. 964 965 The *value* argument can be any object, which is then 966 converted to a string. 967 968 In the default Task implementation, the name will be visible 969 in the :func:`repr` output of a task object. 970 971 .. versionadded:: 3.8 972 973 974.. _asyncio_generator_based_coro: 975 976Generator-based Coroutines 977========================== 978 979.. note:: 980 981 Support for generator-based coroutines is **deprecated** and 982 is scheduled for removal in Python 3.10. 983 984Generator-based coroutines predate async/await syntax. They are 985Python generators that use ``yield from`` expressions to await 986on Futures and other coroutines. 987 988Generator-based coroutines should be decorated with 989:func:`@asyncio.coroutine <asyncio.coroutine>`, although this is not 990enforced. 991 992 993.. decorator:: coroutine 994 995 Decorator to mark generator-based coroutines. 996 997 This decorator enables legacy generator-based coroutines to be 998 compatible with async/await code:: 999 1000 @asyncio.coroutine 1001 def old_style_coroutine(): 1002 yield from asyncio.sleep(1) 1003 1004 async def main(): 1005 await old_style_coroutine() 1006 1007 This decorator should not be used for :keyword:`async def` 1008 coroutines. 1009 1010 .. deprecated-removed:: 3.8 3.10 1011 1012 Use :keyword:`async def` instead. 1013 1014.. function:: iscoroutine(obj) 1015 1016 Return ``True`` if *obj* is a :ref:`coroutine object <coroutine>`. 1017 1018 This method is different from :func:`inspect.iscoroutine` because 1019 it returns ``True`` for generator-based coroutines. 1020 1021.. function:: iscoroutinefunction(func) 1022 1023 Return ``True`` if *func* is a :ref:`coroutine function 1024 <coroutine>`. 1025 1026 This method is different from :func:`inspect.iscoroutinefunction` 1027 because it returns ``True`` for generator-based coroutine functions 1028 decorated with :func:`@coroutine <coroutine>`. 1029