Debian Codegraph @

Doc/library/asyncio-task.rst

raw
1 .. currentmodule:: asyncio
2
3
4 ====================
5 Coroutines and tasks
6 ====================
7
8 This section outlines high-level asyncio APIs to work with coroutines
9 and Tasks.
10
11 .. contents::
12 :depth: 1
13 :local:
14
15
16 .. _coroutine:
17
18 Coroutines
19 ==========
20
21 **Source code:** :source:`Lib/asyncio/coroutines.py`
22
23 ----------------------------------------------------
24
25 :term:`Coroutines <coroutine>` declared with the async/await syntax is the
26 preferred way of writing asyncio applications. For example, the following
27 snippet of code prints "hello", waits 1 second,
28 and then prints "world"::
29
30 >>> import asyncio
31
32 >>> async def main():
33 ... print('hello')
34 ... await asyncio.sleep(1)
35 ... print('world')
36
37 >>> asyncio.run(main())
38 hello
39 world
40
41 Note that simply calling a coroutine will not schedule it to
42 be executed::
43
44 >>> main()
45 <coroutine object main at 0x1053bb7c8>
46
47 To actually run a coroutine, asyncio provides the following mechanisms:
48
49 * The :func:`asyncio.run` function to run the top-level
50 entry point "main()" function (see the above example.)
51
52 * Awaiting on a coroutine. The following snippet of code will
53 print "hello" after waiting for 1 second, and then print "world"
54 after waiting for *another* 2 seconds::
55
56 import asyncio
57 import time
58
59 async def say_after(delay, what):
60 await asyncio.sleep(delay)
61 print(what)
62
63 async def main():
64 print(f"started at {time.strftime('%X')}")
65
66 await say_after(1, 'hello')
67 await say_after(2, 'world')
68
69 print(f"finished at {time.strftime('%X')}")
70
71 asyncio.run(main())
72
73 Expected output::
74
75 started at 17:13:52
76 hello
77 world
78 finished at 17:13:55
79
80 * The :func:`asyncio.create_task` function to run coroutines
81 concurrently as asyncio :class:`Tasks <Task>`.
82
83 Let's modify the above example and run two ``say_after`` coroutines
84 *concurrently*::
85
86 async def main():
87 task1 = asyncio.create_task(
88 say_after(1, 'hello'))
89
90 task2 = asyncio.create_task(
91 say_after(2, 'world'))
92
93 print(f"started at {time.strftime('%X')}")
94
95 # Wait until both tasks are completed (should take
96 # around 2 seconds.)
97 await task1
98 await task2
99
100 print(f"finished at {time.strftime('%X')}")
101
102 Note that expected output now shows that the snippet runs
103 1 second faster than before::
104
105 started at 17:14:32
106 hello
107 world
108 finished at 17:14:34
109
110 * The :class:`asyncio.TaskGroup` class provides a more modern
111 alternative to :func:`create_task`.
112 Using this API, the last example becomes::
113
114 async def main():
115 async with asyncio.TaskGroup() as tg:
116 task1 = tg.create_task(
117 say_after(1, 'hello'))
118
119 task2 = tg.create_task(
120 say_after(2, 'world'))
121
122 print(f"started at {time.strftime('%X')}")
123
124 # The await is implicit when the context manager exits.
125
126 print(f"finished at {time.strftime('%X')}")
127
128 The timing and output should be the same as for the previous version.
129
130 .. versionadded:: 3.11
131 :class:`asyncio.TaskGroup`.
132
133
134 .. _asyncio-awaitables:
135
136 Awaitables
137 ==========
138
139 We say that an object is an **awaitable** object if it can be used
140 in an :keyword:`await` expression. Many asyncio APIs are designed to
141 accept awaitables.
142
143 There are three main types of *awaitable* objects:
144 **coroutines**, **Tasks**, and **Futures**.
145
146
147 .. rubric:: Coroutines
148
149 Python coroutines are *awaitables* and therefore can be awaited from
150 other coroutines::
151
152 import asyncio
153
154 async def nested():
155 return 42
156
157 async def main():
158 # Nothing happens if we just call "nested()".
159 # A coroutine object is created but not awaited,
160 # so it *won't run at all*.
161 nested() # will raise a "RuntimeWarning".
162
163 # Let's do it differently now and await it:
164 print(await nested()) # will print "42".
165
166 asyncio.run(main())
167
168 .. important::
169
170 In this documentation the term "coroutine" can be used for
171 two closely related concepts:
172
173 * a *coroutine function*: an :keyword:`async def` function;
174
175 * a *coroutine object*: an object returned by calling a
176 *coroutine function*.
177
178
179 .. rubric:: Tasks
180
181 *Tasks* are used to schedule coroutines *concurrently*.
182
183 When a coroutine is wrapped into a *Task* with functions like
184 :func:`asyncio.create_task` the coroutine is automatically
185 scheduled to run soon::
186
187 import asyncio
188
189 async def nested():
190 return 42
191
192 async def main():
193 # Schedule nested() to run soon concurrently
194 # with "main()".
195 task = asyncio.create_task(nested())
196
197 # "task" can now be used to cancel "nested()", or
198 # can simply be awaited to wait until it is complete:
199 await task
200
201 asyncio.run(main())
202
203
204 .. rubric:: Futures
205
206 A :class:`Future` is a special **low-level** awaitable object that
207 represents an **eventual result** of an asynchronous operation.
208
209 When a Future object is *awaited* it means that the coroutine will
210 wait until the Future is resolved in some other place.
211
212 Future objects in asyncio are needed to allow callback-based code
213 to be used with async/await.
214
215 Normally **there is no need** to create Future objects at the
216 application level code.
217
218 Future objects, sometimes exposed by libraries and some asyncio
219 APIs, can be awaited::
220
221 async def main():
222 await function_that_returns_a_future_object()
223
224 # this is also valid:
225 await asyncio.gather(
226 function_that_returns_a_future_object(),
227 some_python_coroutine()
228 )
229
230 A good example of a low-level function that returns a Future object
231 is :meth:`loop.run_in_executor`.
232
233
234 Creating tasks
235 ==============
236
237 **Source code:** :source:`Lib/asyncio/tasks.py`
238
239 -----------------------------------------------
240
241 .. function:: create_task(coro, *, name=None, context=None)
242
243 Wrap the *coro* :ref:`coroutine <coroutine>` into a :class:`Task`
244 and schedule its execution. Return the Task object.
245
246 If *name* is not ``None``, it is set as the name of the task using
247 :meth:`Task.set_name`.
248
249 An optional keyword-only *context* argument allows specifying a
250 custom :class:`contextvars.Context` for the *coro* to run in.
251 The current context copy is created when no *context* is provided.
252
253 The task is executed in the loop returned by :func:`get_running_loop`,
254 :exc:`RuntimeError` is raised if there is no running loop in
255 current thread.
256
257 .. note::
258
259 :meth:`asyncio.TaskGroup.create_task` is a new alternative
260 leveraging structural concurrency; it allows for waiting
261 for a group of related tasks with strong safety guarantees.
262
263 .. important::
264
265 Save a reference to the result of this function, to avoid
266 a task disappearing mid-execution. The event loop only keeps
267 weak references to tasks. A task that isn't referenced elsewhere
268 may get garbage collected at any time, even before it's done.
269 For reliable "fire-and-forget" background tasks, gather them in
270 a collection::
271
272 background_tasks = set()
273
274 for i in range(10):
275 task = asyncio.create_task(some_coro(param=i))
276
277 # Add task to the set. This creates a strong reference.
278 background_tasks.add(task)
279
280 # To prevent keeping references to finished tasks forever,
281 # make each task remove its own reference from the set after
282 # completion:
283 task.add_done_callback(background_tasks.discard)
284
285 Note that this approach never awaits the tasks, so if a task
286 fails, its exception is never retrieved and asyncio logs a
287 "Task exception was never retrieved" message when the task is
288 garbage collected. To avoid this, use :class:`asyncio.TaskGroup`
289 which keeps a strong reference to each task, awaits them and
290 propagates their exceptions::
291
292 async with asyncio.TaskGroup() as tg:
293 for i in range(10):
294 tg.create_task(some_coro(param=i))
295
296 .. versionadded:: 3.7
297
298 .. versionchanged:: 3.8
299 Added the *name* parameter.
300
301 .. versionchanged:: 3.11
302 Added the *context* parameter.
303
304
305 Task cancellation
306 =================
307
308 Tasks can easily and safely be cancelled.
309 When a task is cancelled, :exc:`asyncio.CancelledError` will be raised
310 in the task at the next opportunity.
311
312 It is recommended that coroutines use ``try/finally`` blocks to robustly
313 perform clean-up logic. In case :exc:`asyncio.CancelledError`
314 is explicitly caught, it should generally be propagated when
315 clean-up is complete. :exc:`asyncio.CancelledError` directly subclasses
316 :exc:`BaseException` so most code will not need to be aware of it.
317
318 The asyncio components that enable structured concurrency, like
319 :class:`asyncio.TaskGroup` and :func:`asyncio.timeout`,
320 are implemented using cancellation internally and might misbehave if
321 a coroutine swallows :exc:`asyncio.CancelledError`. Similarly, user code
322 should not generally call :meth:`uncancel <asyncio.Task.uncancel>`.
323 However, in cases when suppressing :exc:`asyncio.CancelledError` is
324 truly desired, it is necessary to also call ``uncancel()`` to completely
325 remove the cancellation state.
326
327 .. _taskgroups:
328
329 Task groups
330 ===========
331
332 Task groups combine a task creation API with a convenient
333 and reliable way to wait for all tasks in the group to finish.
334
335 .. class:: TaskGroup()
336
337 An :ref:`asynchronous context manager <async-context-managers>`
338 holding a group of tasks.
339 Tasks can be added to the group using :meth:`create_task`.
340 All tasks are awaited when the context manager exits.
341
342 .. versionadded:: 3.11
343
344 .. method:: create_task(coro, *, name=None, context=None)
345
346 Create a task in this task group.
347 The signature matches that of :func:`asyncio.create_task`.
348 If the task group is inactive (e.g. not yet entered,
349 already finished, or in the process of shutting down),
350 we will close the given ``coro``.
351
352 .. versionchanged:: 3.13
353
354 Close the given coroutine if the task group is not active.
355
356 Example::
357
358 async def main():
359 async with asyncio.TaskGroup() as tg:
360 task1 = tg.create_task(some_coro(...))
361 task2 = tg.create_task(another_coro(...))
362 print(f"Both tasks have completed now: {task1.result()}, {task2.result()}")
363
364 The ``async with`` statement will wait for all tasks in the group to finish.
365 While waiting, new tasks may still be added to the group
366 (for example, by passing ``tg`` into one of the coroutines
367 and calling ``tg.create_task()`` in that coroutine).
368 Once the last task has finished and the ``async with`` block is exited,
369 no new tasks may be added to the group.
370
371 The first time any of the tasks belonging to the group fails
372 with an exception other than :exc:`asyncio.CancelledError`,
373 the remaining tasks in the group are cancelled.
374 No further tasks can then be added to the group.
375 At this point, if the body of the ``async with`` statement is still active
376 (i.e., :meth:`~object.__aexit__` hasn't been called yet),
377 the task directly containing the ``async with`` statement is also cancelled.
378 The resulting :exc:`asyncio.CancelledError` will interrupt an ``await``,
379 but it will not bubble out of the containing ``async with`` statement.
380
381 Once all tasks have finished, if any tasks have failed
382 with an exception other than :exc:`asyncio.CancelledError`,
383 those exceptions are combined in an
384 :exc:`ExceptionGroup` or :exc:`BaseExceptionGroup`
385 (as appropriate; see their documentation)
386 which is then raised.
387
388 Two base exceptions are treated specially:
389 If any task fails with :exc:`KeyboardInterrupt` or :exc:`SystemExit`,
390 the task group still cancels the remaining tasks and waits for them,
391 but then the initial :exc:`KeyboardInterrupt` or :exc:`SystemExit`
392 is re-raised instead of :exc:`ExceptionGroup` or :exc:`BaseExceptionGroup`.
393
394 If the body of the ``async with`` statement exits with an exception
395 (so :meth:`~object.__aexit__` is called with an exception set),
396 this is treated the same as if one of the tasks failed:
397 the remaining tasks are cancelled and then waited for,
398 and non-cancellation exceptions are grouped into an
399 exception group and raised.
400 The exception passed into :meth:`~object.__aexit__`,
401 unless it is :exc:`asyncio.CancelledError`,
402 is also included in the exception group.
403 The same special case is made for
404 :exc:`KeyboardInterrupt` and :exc:`SystemExit` as in the previous paragraph.
405
406 Task groups are careful not to mix up the internal cancellation used to
407 "wake up" their :meth:`~object.__aexit__` with cancellation requests
408 for the task in which they are running made by other parties.
409 In particular, when one task group is syntactically nested in another,
410 and both experience an exception in one of their child tasks simultaneously,
411 the inner task group will process its exceptions, and then the outer task group
412 will receive another cancellation and process its own exceptions.
413
414 In the case where a task group is cancelled externally and also must
415 raise an :exc:`ExceptionGroup`, it will call the parent task's
416 :meth:`~asyncio.Task.cancel` method. This ensures that a
417 :exc:`asyncio.CancelledError` will be raised at the next
418 :keyword:`await`, so the cancellation is not lost.
419
420 Task groups preserve the cancellation count
421 reported by :meth:`asyncio.Task.cancelling`.
422
423 .. versionchanged:: 3.13
424
425 Improved handling of simultaneous internal and external cancellations
426 and correct preservation of cancellation counts.
427
428 Terminating a task group
429 ------------------------
430
431 While terminating a task group is not natively supported by the standard
432 library, termination can be achieved by adding an exception-raising task
433 to the task group and ignoring the raised exception:
434
435 .. code-block:: python
436
437 import asyncio
438 from asyncio import TaskGroup
439
440 class TerminateTaskGroup(Exception):
441 """Exception raised to terminate a task group."""
442
443 async def force_terminate_task_group():
444 """Used to force termination of a task group."""
445 raise TerminateTaskGroup()
446
447 async def job(task_id, sleep_time):
448 print(f'Task {task_id}: start')
449 await asyncio.sleep(sleep_time)
450 print(f'Task {task_id}: done')
451
452 async def main():
453 try:
454 async with TaskGroup() as group:
455 # spawn some tasks
456 group.create_task(job(1, 0.5))
457 group.create_task(job(2, 1.5))
458 # sleep for 1 second
459 await asyncio.sleep(1)
460 # add an exception-raising task to force the group to terminate
461 group.create_task(force_terminate_task_group())
462 except* TerminateTaskGroup:
463 pass
464
465 asyncio.run(main())
466
467 Expected output:
468
469 .. code-block:: text
470
471 Task 1: start
472 Task 2: start
473 Task 1: done
474
475 Sleeping
476 ========
477
478 .. function:: sleep(delay, result=None)
479 :async:
480
481 Block for *delay* seconds.
482
483 If *result* is provided, it is returned to the caller
484 when the coroutine completes.
485
486 ``sleep()`` always suspends the current task, allowing other tasks
487 to run.
488
489 Setting the delay to 0 provides an optimized path to allow other
490 tasks to run. This can be used by long-running functions to avoid
491 blocking the event loop for the full duration of the function call.
492
493 .. _asyncio_example_sleep:
494
495 Example of coroutine displaying the current date every second
496 for 5 seconds::
497
498 import asyncio
499 import datetime as dt
500
501 async def display_date():
502 loop = asyncio.get_running_loop()
503 end_time = loop.time() + 5.0
504 while True:
505 print(dt.datetime.now())
506 if (loop.time() + 1.0) >= end_time:
507 break
508 await asyncio.sleep(1)
509
510 asyncio.run(display_date())
511
512
513 .. versionchanged:: 3.10
514 Removed the *loop* parameter.
515
516 .. versionchanged:: 3.13
517 Raises :exc:`ValueError` if *delay* is :data:`~math.nan`.
518
519
520 Running tasks concurrently
521 ==========================
522
523 .. awaitablefunction:: gather(*aws, return_exceptions=False)
524
525 Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
526 sequence *concurrently*.
527
528 If any awaitable in *aws* is a coroutine, it is automatically
529 scheduled as a Task.
530
531 If all awaitables are completed successfully, the result is an
532 aggregate list of returned values. The order of result values
533 corresponds to the order of awaitables in *aws*.
534
535 If *return_exceptions* is ``False`` (default), the first
536 raised exception is immediately propagated to the task that
537 awaits on ``gather()``. Other awaitables in the *aws* sequence
538 **won't be cancelled** and will continue to run.
539
540 If *return_exceptions* is ``True``, exceptions are treated the
541 same as successful results, and aggregated in the result list.
542
543 If ``gather()`` is *cancelled*, all submitted awaitables
544 (that have not completed yet) are also *cancelled*.
545
546 If any Task or Future from the *aws* sequence is *cancelled*, it is
547 treated as if it raised :exc:`CancelledError` -- the ``gather()``
548 call is **not** cancelled in this case. This is to prevent the
549 cancellation of one submitted Task/Future to cause other
550 Tasks/Futures to be cancelled.
551
552 .. note::
553 A new alternative to create and run tasks concurrently and
554 wait for their completion is :class:`asyncio.TaskGroup`. *TaskGroup*
555 provides stronger safety guarantees than *gather* for scheduling a nesting of subtasks:
556 if a task (or a subtask, a task scheduled by a task)
557 raises an exception, *TaskGroup* will, while *gather* will not,
558 cancel the remaining scheduled tasks.
559
560 .. _asyncio_example_gather:
561
562 Example::
563
564 import asyncio
565
566 async def factorial(name, number):
567 f = 1
568 for i in range(2, number + 1):
569 print(f"Task {name}: Compute factorial({number}), currently i={i}...")
570 await asyncio.sleep(1)
571 f *= i
572 print(f"Task {name}: factorial({number}) = {f}")
573 return f
574
575 async def main():
576 # Schedule three calls *concurrently*:
577 L = await asyncio.gather(
578 factorial("A", 2),
579 factorial("B", 3),
580 factorial("C", 4),
581 )
582 print(L)
583
584 asyncio.run(main())
585
586 # Expected output:
587 #
588 # Task A: Compute factorial(2), currently i=2...
589 # Task B: Compute factorial(3), currently i=2...
590 # Task C: Compute factorial(4), currently i=2...
591 # Task A: factorial(2) = 2
592 # Task B: Compute factorial(3), currently i=3...
593 # Task C: Compute factorial(4), currently i=3...
594 # Task B: factorial(3) = 6
595 # Task C: Compute factorial(4), currently i=4...
596 # Task C: factorial(4) = 24
597 # [2, 6, 24]
598
599 .. note::
600 If *return_exceptions* is false, cancelling gather() after it
601 has been marked done won't cancel any submitted awaitables.
602 For instance, gather can be marked done after propagating an
603 exception to the caller, therefore, calling ``gather.cancel()``
604 after catching an exception (raised by one of the awaitables) from
605 gather won't cancel any other awaitables.
606
607 .. versionchanged:: 3.7
608 If the *gather* itself is cancelled, the cancellation is
609 propagated regardless of *return_exceptions*.
610
611 .. versionchanged:: 3.10
612 Removed the *loop* parameter.
613
614 .. deprecated:: 3.10
615 Deprecation warning is emitted if no positional arguments are provided
616 or not all positional arguments are Future-like objects
617 and there is no running event loop.
618
619
620 .. _eager-task-factory:
621
622 Eager task factory
623 ==================
624
625 .. function:: eager_task_factory(loop, coro, *, name=None, context=None)
626
627 A task factory for eager task execution.
628
629 When using this factory (via :meth:`loop.set_task_factory(asyncio.eager_task_factory) <loop.set_task_factory>`),
630 coroutines begin execution synchronously during :class:`Task` construction.
631 Tasks are only scheduled on the event loop if they block.
632 This can be a performance improvement as the overhead of loop scheduling
633 is avoided for coroutines that complete synchronously.
634
635 A common example where this is beneficial is coroutines which employ
636 caching or memoization to avoid actual I/O when possible.
637
638 .. note::
639
640 Immediate execution of the coroutine is a semantic change.
641 If the coroutine returns or raises, the task is never scheduled
642 to the event loop. If the coroutine execution blocks, the task is
643 scheduled to the event loop. This change may introduce behavior
644 changes to existing applications. For example,
645 the application's task execution order is likely to change.
646
647 .. versionadded:: 3.12
648
649 .. function:: create_eager_task_factory(custom_task_constructor)
650
651 Create an eager task factory, similar to :func:`eager_task_factory`,
652 using the provided *custom_task_constructor* when creating a new task instead
653 of the default :class:`Task`.
654
655 *custom_task_constructor* must be a *callable* with the signature matching
656 the signature of :class:`Task.__init__ <Task>`.
657 The callable must return a :class:`asyncio.Task`-compatible object.
658
659 This function returns a *callable* intended to be used as a task factory of an
660 event loop via :meth:`loop.set_task_factory(factory) <loop.set_task_factory>`).
661
662 .. versionadded:: 3.12
663
664
665 Shielding from cancellation
666 ===========================
667
668 .. awaitablefunction:: shield(aw)
669
670 Protect an :ref:`awaitable object <asyncio-awaitables>`
671 from being :meth:`cancelled <Task.cancel>`.
672
673 If *aw* is a coroutine it is automatically scheduled as a Task.
674
675 The statement::
676
677 task = asyncio.create_task(something())
678 res = await shield(task)
679
680 is equivalent to::
681
682 res = await something()
683
684 *except* that if the coroutine containing it is cancelled, the
685 Task running in ``something()`` is not cancelled. From the point
686 of view of ``something()``, the cancellation did not happen.
687 Although its caller is still cancelled, so the "await" expression
688 still raises a :exc:`CancelledError`.
689
690 If ``something()`` is cancelled by other means (i.e. from within
691 itself) that would also cancel ``shield()``.
692
693 If it is desired to completely ignore cancellation (not recommended)
694 the ``shield()`` function should be combined with a try/except
695 clause, as follows::
696
697 task = asyncio.create_task(something())
698 try:
699 res = await shield(task)
700 except CancelledError:
701 res = None
702
703 .. important::
704
705 Save a reference to tasks passed to this function, to avoid
706 a task disappearing mid-execution. The event loop only keeps
707 weak references to tasks. A task that isn't referenced elsewhere
708 may get garbage collected at any time, even before it's done.
709
710 .. versionchanged:: 3.10
711 Removed the *loop* parameter.
712
713 .. deprecated:: 3.10
714 Deprecation warning is emitted if *aw* is not Future-like object
715 and there is no running event loop.
716
717
718 Timeouts
719 ========
720
721 .. function:: timeout(delay)
722
723 Return an :ref:`asynchronous context manager <async-context-managers>`
724 that can be used to limit the amount of time spent waiting on
725 something.
726
727 *delay* can either be ``None``, or a float/int number of
728 seconds to wait. If *delay* is ``None``, no time limit will
729 be applied; this can be useful if the delay is unknown when
730 the context manager is created.
731
732 In either case, the context manager can be rescheduled after
733 creation using :meth:`Timeout.reschedule`.
734
735 Example::
736
737 async def main():
738 async with asyncio.timeout(10):
739 await long_running_task()
740
741 If ``long_running_task`` takes more than 10 seconds to complete,
742 the context manager will cancel the current task and handle
743 the resulting :exc:`asyncio.CancelledError` internally, transforming it
744 into a :exc:`TimeoutError` which can be caught and handled.
745
746 .. note::
747
748 The :func:`asyncio.timeout` context manager is what transforms
749 the :exc:`asyncio.CancelledError` into a :exc:`TimeoutError`,
750 which means the :exc:`TimeoutError` can only be caught
751 *outside* of the context manager.
752
753 Example of catching :exc:`TimeoutError`::
754
755 async def main():
756 try:
757 async with asyncio.timeout(10):
758 await long_running_task()
759 except TimeoutError:
760 print("The long operation timed out, but we've handled it.")
761
762 print("This statement will run regardless.")
763
764 The context manager produced by :func:`asyncio.timeout` can be
765 rescheduled to a different deadline and inspected.
766
767 .. class:: Timeout(when)
768
769 An :ref:`asynchronous context manager <async-context-managers>`
770 for cancelling overdue coroutines.
771
772 Prefer using :func:`asyncio.timeout` or :func:`asyncio.timeout_at`
773 rather than instantiating :class:`!Timeout` directly.
774
775 ``when`` should be an absolute time at which the context should time out,
776 as measured by the event loop's clock:
777
778 - If ``when`` is ``None``, the timeout will never trigger.
779 - If ``when < loop.time()``, the timeout will trigger on the next
780 iteration of the event loop.
781
782 .. method:: when() -> float | None
783
784 Return the current deadline, or ``None`` if the current
785 deadline is not set.
786
787 .. method:: reschedule(when: float | None)
788
789 Reschedule the timeout.
790
791 .. method:: expired() -> bool
792
793 Return whether the context manager has exceeded its deadline
794 (expired).
795
796 Example::
797
798 async def main():
799 try:
800 # We do not know the timeout when starting, so we pass ``None``.
801 async with asyncio.timeout(None) as cm:
802 # We know the timeout now, so we reschedule it.
803 new_deadline = get_running_loop().time() + 10
804 cm.reschedule(new_deadline)
805
806 await long_running_task()
807 except TimeoutError:
808 pass
809
810 if cm.expired():
811 print("Looks like we haven't finished on time.")
812
813 Timeout context managers can be safely nested.
814
815 .. versionadded:: 3.11
816
817 .. function:: timeout_at(when)
818
819 Similar to :func:`asyncio.timeout`, except *when* is the absolute time
820 to stop waiting, or ``None``.
821
822 Example::
823
824 async def main():
825 loop = get_running_loop()
826 deadline = loop.time() + 20
827 try:
828 async with asyncio.timeout_at(deadline):
829 await long_running_task()
830 except TimeoutError:
831 print("The long operation timed out, but we've handled it.")
832
833 print("This statement will run regardless.")
834
835 .. versionadded:: 3.11
836
837 .. function:: wait_for(aw, timeout)
838 :async:
839
840 Wait for the *aw* :ref:`awaitable <asyncio-awaitables>`
841 to complete with a timeout.
842
843 If *aw* is a coroutine it is automatically scheduled as a Task.
844
845 *timeout* can either be ``None`` or a float or int number of seconds
846 to wait for. If *timeout* is ``None``, block until the future
847 completes.
848
849 If a timeout occurs, it cancels the task and raises
850 :exc:`TimeoutError`.
851
852 To avoid the task :meth:`cancellation <Task.cancel>`,
853 wrap it in :func:`shield`.
854
855 The function will wait until the future is actually cancelled,
856 so the total wait time may exceed the *timeout*. If an exception
857 happens during cancellation, it is propagated.
858
859 If the wait is cancelled, the future *aw* is also cancelled.
860
861 .. _asyncio_example_waitfor:
862
863 Example::
864
865 async def eternity():
866 # Sleep for one hour
867 await asyncio.sleep(3600)
868 print('yay!')
869
870 async def main():
871 # Wait for at most 1 second
872 try:
873 await asyncio.wait_for(eternity(), timeout=1.0)
874 except TimeoutError:
875 print('timeout!')
876
877 asyncio.run(main())
878
879 # Expected output:
880 #
881 # timeout!
882
883 .. versionchanged:: 3.7
884 When *aw* is cancelled due to a timeout, ``wait_for`` waits
885 for *aw* to be cancelled. Previously, it raised
886 :exc:`TimeoutError` immediately.
887
888 .. versionchanged:: 3.10
889 Removed the *loop* parameter.
890
891 .. versionchanged:: 3.11
892 Raises :exc:`TimeoutError` instead of :exc:`asyncio.TimeoutError`.
893
894
895 Waiting primitives
896 ==================
897
898 .. function:: wait(aws, *, timeout=None, return_when=ALL_COMPLETED)
899 :async:
900
901 Run :class:`~asyncio.Future` and :class:`~asyncio.Task` instances in the *aws*
902 iterable concurrently and block until the condition specified
903 by *return_when*.
904
905 The *aws* iterable must not be empty.
906
907 Returns two sets of Tasks/Futures: ``(done, pending)``.
908
909 Usage::
910
911 done, pending = await asyncio.wait(aws)
912
913 *timeout* (a float or int), if specified, can be used to control
914 the maximum number of seconds to wait before returning.
915
916 Note that this function does not raise :exc:`TimeoutError`.
917 Futures or Tasks that aren't done when the timeout occurs are simply
918 returned in the second set.
919
920 *return_when* indicates when this function should return. It must
921 be one of the following constants:
922
923 .. list-table::
924 :header-rows: 1
925
926 * - Constant
927 - Description
928
929 * - .. data:: FIRST_COMPLETED
930 - The function will return when any future finishes or is cancelled.
931
932 * - .. data:: FIRST_EXCEPTION
933 - The function will return when any future finishes by raising an
934 exception. If no future raises an exception
935 then it is equivalent to :const:`ALL_COMPLETED`.
936
937 * - .. data:: ALL_COMPLETED
938 - The function will return when all futures finish or are cancelled.
939
940 Unlike :func:`~asyncio.wait_for`, ``wait()`` does not cancel the
941 futures when a timeout occurs.
942
943 If ``wait()`` is cancelled, the futures in *aws* are not cancelled
944 and continue to run.
945
946 .. versionchanged:: 3.10
947 Removed the *loop* parameter.
948
949 .. versionchanged:: 3.11
950 Passing coroutine objects to ``wait()`` directly is forbidden.
951
952 .. versionchanged:: 3.12
953 Added support for generators yielding tasks.
954
955
956 .. function:: as_completed(aws, *, timeout=None)
957
958 Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws* iterable
959 concurrently. The returned object can be iterated to obtain the results
960 of the awaitables as they finish.
961
962 The object returned by ``as_completed()`` can be iterated as an
963 :term:`asynchronous iterator` or a plain :term:`iterator`. When asynchronous
964 iteration is used, the originally-supplied awaitables are yielded if they
965 are tasks or futures. This makes it easy to correlate previously-scheduled
966 tasks with their results. Example::
967
968 ipv4_connect = create_task(open_connection("127.0.0.1", 80))
969 ipv6_connect = create_task(open_connection("::1", 80))
970 tasks = [ipv4_connect, ipv6_connect]
971
972 async for earliest_connect in as_completed(tasks):
973 # earliest_connect is done. The result can be obtained by
974 # awaiting it or calling earliest_connect.result()
975 reader, writer = await earliest_connect
976
977 if earliest_connect is ipv6_connect:
978 print("IPv6 connection established.")
979 else:
980 print("IPv4 connection established.")
981
982 During asynchronous iteration, implicitly-created tasks will be yielded for
983 supplied awaitables that aren't tasks or futures.
984
985 When used as a plain iterator, each iteration yields a new coroutine that
986 returns the result or raises the exception of the next completed awaitable.
987 This pattern is compatible with Python versions older than 3.13::
988
989 ipv4_connect = create_task(open_connection("127.0.0.1", 80))
990 ipv6_connect = create_task(open_connection("::1", 80))
991 tasks = [ipv4_connect, ipv6_connect]
992
993 for next_connect in as_completed(tasks):
994 # next_connect is not one of the original task objects. It must be
995 # awaited to obtain the result value or raise the exception of the
996 # awaitable that finishes next.
997 reader, writer = await next_connect
998
999 A :exc:`TimeoutError` is raised if the timeout occurs before all awaitables
1000 are done. This is raised by the ``async for`` loop during asynchronous
1001 iteration or by the coroutines yielded during plain iteration.
1002
1003 ``as_completed()`` does not cancel the tasks running the supplied
1004 awaitables: if a timeout occurs or the iteration is cancelled, the
1005 remaining tasks continue to run.
1006
1007 .. versionchanged:: 3.10
1008 Removed the *loop* parameter.
1009
1010 .. deprecated:: 3.10
1011 Deprecation warning is emitted if not all awaitable objects in the *aws*
1012 iterable are Future-like objects and there is no running event loop.
1013
1014 .. versionchanged:: 3.12
1015 Added support for generators yielding tasks.
1016
1017 .. versionchanged:: 3.13
1018 The result can now be used as either an :term:`asynchronous iterator`
1019 or as a plain :term:`iterator` (previously it was only a plain iterator).
1020
1021
1022 Running in threads
1023 ==================
1024
1025 .. function:: to_thread(func, /, *args, **kwargs)
1026 :async:
1027
1028 Asynchronously run function *func* in a separate thread.
1029
1030 Any \*args and \*\*kwargs supplied for this function are directly passed
1031 to *func*. Also, the current :class:`contextvars.Context` is propagated,
1032 allowing context variables from the event loop thread to be accessed in the
1033 separate thread.
1034
1035 Return a coroutine that can be awaited to get the eventual result of *func*.
1036
1037 This coroutine function is primarily intended to be used for executing
1038 IO-bound functions/methods that would otherwise block the event loop if
1039 they were run in the main thread. For example::
1040
1041 def blocking_io():
1042 print(f"start blocking_io at {time.strftime('%X')}")
1043 # Note that time.sleep() can be replaced with any blocking
1044 # IO-bound operation, such as file operations.
1045 time.sleep(1)
1046 print(f"blocking_io complete at {time.strftime('%X')}")
1047
1048 async def main():
1049 print(f"started main at {time.strftime('%X')}")
1050
1051 await asyncio.gather(
1052 asyncio.to_thread(blocking_io),
1053 asyncio.sleep(1))
1054
1055 print(f"finished main at {time.strftime('%X')}")
1056
1057
1058 asyncio.run(main())
1059
1060 # Expected output:
1061 #
1062 # started main at 19:50:53
1063 # start blocking_io at 19:50:53
1064 # blocking_io complete at 19:50:54
1065 # finished main at 19:50:54
1066
1067 Directly calling ``blocking_io()`` in any coroutine would block the event loop
1068 for its duration, resulting in an additional 1 second of run time. Instead,
1069 by using ``asyncio.to_thread()``, we can run it in a separate thread without
1070 blocking the event loop.
1071
1072 .. note::
1073
1074 Due to the :term:`GIL`, ``asyncio.to_thread()`` can typically only be used
1075 to make IO-bound functions non-blocking. However, for extension modules
1076 that release the GIL or alternative Python implementations that don't
1077 have one, ``asyncio.to_thread()`` can also be used for CPU-bound functions.
1078
1079 .. versionadded:: 3.9
1080
1081
1082 Scheduling from other threads
1083 =============================
1084
1085 .. function:: run_coroutine_threadsafe(coro, loop)
1086
1087 Submit a coroutine to the given event loop. Thread-safe.
1088
1089 Return a :class:`concurrent.futures.Future` to wait for the result
1090 from another OS thread.
1091
1092 This function is meant to be called from a different OS thread
1093 than the one where the event loop is running. Example::
1094
1095 # Create a coroutine
1096 coro = asyncio.sleep(1, result=3)
1097
1098 # Submit the coroutine to a given loop
1099 future = asyncio.run_coroutine_threadsafe(coro, loop)
1100
1101 # Wait for the result with an optional timeout argument
1102 assert future.result(timeout) == 3
1103
1104 If an exception is raised in the coroutine, the returned Future
1105 will be notified. It can also be used to cancel the task in
1106 the event loop::
1107
1108 try:
1109 result = future.result(timeout)
1110 except TimeoutError:
1111 print('The coroutine took too long, cancelling the task...')
1112 future.cancel()
1113 except Exception as exc:
1114 print(f'The coroutine raised an exception: {exc!r}')
1115 else:
1116 print(f'The coroutine returned: {result!r}')
1117
1118 See the :ref:`concurrency and multithreading <asyncio-multithreading>`
1119 section of the documentation.
1120
1121 Unlike other asyncio functions this function requires the *loop*
1122 argument to be passed explicitly.
1123
1124 .. versionadded:: 3.5.1
1125
1126
1127 Introspection
1128 =============
1129
1130
1131 .. function:: current_task(loop=None)
1132
1133 Return the currently running :class:`Task` instance, or ``None`` if
1134 no task is running.
1135
1136 If *loop* is ``None`` :func:`get_running_loop` is used to get
1137 the current loop.
1138
1139 .. versionadded:: 3.7
1140
1141
1142 .. function:: all_tasks(loop=None)
1143
1144 Return a set of not yet finished :class:`Task` objects run by
1145 the loop.
1146
1147 If *loop* is ``None``, :func:`get_running_loop` is used for getting
1148 current loop.
1149
1150 .. versionadded:: 3.7
1151
1152
1153 .. function:: iscoroutine(obj)
1154
1155 Return ``True`` if *obj* is a coroutine object.
1156
1157 .. versionadded:: 3.4
1158
1159 .. _asyncio-task-obj:
1160
1161 Task object
1162 ===========
1163
1164 .. class:: Task(coro, *, loop=None, name=None, context=None, eager_start=False)
1165
1166 A :class:`Future-like <Future>` object that runs a Python
1167 :ref:`coroutine <coroutine>`. Not thread-safe.
1168
1169 Tasks are used to run coroutines in event loops.
1170 If a coroutine awaits on a Future, the Task suspends
1171 the execution of the coroutine and waits for the completion
1172 of the Future. When the Future is *done*, the execution of
1173 the wrapped coroutine resumes.
1174
1175 Event loops use cooperative scheduling: an event loop runs
1176 one Task at a time. While a Task awaits for the completion of a
1177 Future, the event loop runs other Tasks, callbacks, or performs
1178 IO operations.
1179
1180 Use the high-level :func:`asyncio.create_task` function to create
1181 Tasks, or the low-level :meth:`loop.create_task` or
1182 :func:`ensure_future` functions. Manual instantiation of Tasks
1183 is discouraged.
1184
1185 To cancel a running Task use the :meth:`cancel` method. Calling it
1186 will cause the Task to throw a :exc:`CancelledError` exception into
1187 the wrapped coroutine. If a coroutine is awaiting on a Future
1188 object during cancellation, the Future object will be cancelled.
1189
1190 :meth:`cancelled` can be used to check if the Task was cancelled.
1191 The method returns ``True`` if the wrapped coroutine did not
1192 suppress the :exc:`CancelledError` exception and was actually
1193 cancelled.
1194
1195 :class:`asyncio.Task` inherits from :class:`Future` all of its
1196 APIs except :meth:`Future.set_result` and
1197 :meth:`Future.set_exception`.
1198
1199 An optional keyword-only *context* argument allows specifying a
1200 custom :class:`contextvars.Context` for the *coro* to run in.
1201 If no *context* is provided, the Task copies the current context
1202 and later runs its coroutine in the copied context.
1203
1204 An optional keyword-only *eager_start* argument allows eagerly starting
1205 the execution of the :class:`asyncio.Task` at task creation time.
1206 If set to ``True`` and the event loop is running, the task will start
1207 executing the coroutine immediately, until the first time the coroutine
1208 blocks. If the coroutine returns or raises without blocking, the task
1209 will be finished eagerly and will skip scheduling to the event loop.
1210
1211 Tasks are :ref:`generic <generics>` over the return type of their wrapped
1212 coroutines.
1213
1214 .. versionchanged:: 3.7
1215 Added support for the :mod:`contextvars` module.
1216
1217 .. versionchanged:: 3.8
1218 Added the *name* parameter.
1219
1220 .. deprecated:: 3.10
1221 Deprecation warning is emitted if *loop* is not specified
1222 and there is no running event loop.
1223
1224 .. versionchanged:: 3.11
1225 Added the *context* parameter.
1226
1227 .. versionchanged:: 3.12
1228 Added the *eager_start* parameter.
1229
1230 .. method:: done()
1231
1232 Return ``True`` if the Task is *done*.
1233
1234 A Task is *done* when the wrapped coroutine either returned
1235 a value, raised an exception, or the Task was cancelled.
1236
1237 .. method:: result()
1238
1239 Return the result of the Task.
1240
1241 If the Task is *done*, the result of the wrapped coroutine
1242 is returned (or if the coroutine raised an exception, that
1243 exception is re-raised.)
1244
1245 If the Task has been *cancelled*, this method raises
1246 a :exc:`CancelledError` exception.
1247
1248 If the Task's result isn't yet available, this method raises
1249 an :exc:`InvalidStateError` exception.
1250
1251 .. method:: exception()
1252
1253 Return the exception of the Task.
1254
1255 If the wrapped coroutine raised an exception that exception
1256 is returned. If the wrapped coroutine returned normally
1257 this method returns ``None``.
1258
1259 If the Task has been *cancelled*, this method raises a
1260 :exc:`CancelledError` exception.
1261
1262 If the Task isn't *done* yet, this method raises an
1263 :exc:`InvalidStateError` exception.
1264
1265 .. method:: add_done_callback(callback, *, context=None)
1266
1267 Add a callback to be run when the Task is *done*.
1268
1269 This method should only be used in low-level callback-based code.
1270
1271 See the documentation of :meth:`Future.add_done_callback`
1272 for more details.
1273
1274 .. method:: remove_done_callback(callback)
1275
1276 Remove *callback* from the callbacks list.
1277
1278 This method should only be used in low-level callback-based code.
1279
1280 See the documentation of :meth:`Future.remove_done_callback`
1281 for more details.
1282
1283 .. method:: get_stack(*, limit=None)
1284
1285 Return the list of stack frames for this Task.
1286
1287 If the wrapped coroutine is not done, this returns the stack
1288 where it is suspended. If the coroutine has completed
1289 successfully or was cancelled, this returns an empty list.
1290 If the coroutine was terminated by an exception, this returns
1291 the list of traceback frames.
1292
1293 The frames are always ordered from oldest to newest.
1294
1295 Only one stack frame is returned for a suspended coroutine.
1296
1297 The optional *limit* argument sets the maximum number of frames
1298 to return; by default all available frames are returned.
1299 The ordering of the returned list differs depending on whether
1300 a stack or a traceback is returned: the newest frames of a
1301 stack are returned, but the oldest frames of a traceback are
1302 returned. (This matches the behavior of the traceback module.)
1303
1304 .. method:: print_stack(*, limit=None, file=None)
1305
1306 Print the stack or traceback for this Task.
1307
1308 This produces output similar to that of the traceback module
1309 for the frames retrieved by :meth:`get_stack`.
1310
1311 The *limit* argument is passed to :meth:`get_stack` directly.
1312
1313 The *file* argument is an I/O stream to which the output
1314 is written; by default output is written to :data:`sys.stdout`.
1315
1316 .. method:: get_coro()
1317
1318 Return the coroutine object wrapped by the :class:`Task`.
1319
1320 .. note::
1321
1322 This will return ``None`` for Tasks which have already
1323 completed eagerly. See the :ref:`Eager Task Factory <eager-task-factory>`.
1324
1325 .. versionadded:: 3.8
1326
1327 .. versionchanged:: 3.12
1328
1329 Newly added eager task execution means result may be ``None``.
1330
1331 .. method:: get_context()
1332
1333 Return the :class:`contextvars.Context` object
1334 associated with the task.
1335
1336 .. versionadded:: 3.12
1337
1338 .. method:: get_name()
1339
1340 Return the name of the Task.
1341
1342 If no name has been explicitly assigned to the Task, the default
1343 asyncio Task implementation generates a default name during
1344 instantiation.
1345
1346 .. versionadded:: 3.8
1347
1348 .. method:: set_name(value)
1349
1350 Set the name of the Task.
1351
1352 The *value* argument can be any object, which is then
1353 converted to a string.
1354
1355 In the default Task implementation, the name will be visible
1356 in the :func:`repr` output of a task object.
1357
1358 .. versionadded:: 3.8
1359
1360 .. method:: cancel(msg=None)
1361
1362 Request the Task to be cancelled.
1363
1364 If the Task is already *done* or *cancelled*, return ``False``,
1365 otherwise, return ``True``.
1366
1367 The method arranges for a :exc:`CancelledError` exception to be thrown
1368 into the wrapped coroutine on the next cycle of the event loop.
1369
1370 The coroutine then has a chance to clean up or even deny the
1371 request by suppressing the exception with a :keyword:`try` ...
1372 ... ``except CancelledError`` ... :keyword:`finally` block.
1373 Therefore, unlike :meth:`Future.cancel`, :meth:`Task.cancel` does
1374 not guarantee that the Task will be cancelled, although
1375 suppressing cancellation completely is not common and is actively
1376 discouraged. Should the coroutine nevertheless decide to suppress
1377 the cancellation, it needs to call :meth:`Task.uncancel` in addition
1378 to catching the exception.
1379
1380 .. versionchanged:: 3.9
1381 Added the *msg* parameter.
1382
1383 .. versionchanged:: 3.11
1384 The ``msg`` parameter is propagated from cancelled task to its awaiter.
1385
1386 .. _asyncio_example_task_cancel:
1387
1388 The following example illustrates how coroutines can intercept
1389 the cancellation request::
1390
1391 async def cancel_me():
1392 print('cancel_me(): before sleep')
1393
1394 try:
1395 # Wait for 1 hour
1396 await asyncio.sleep(3600)
1397 except asyncio.CancelledError:
1398 print('cancel_me(): cancel sleep')
1399 raise
1400 finally:
1401 print('cancel_me(): after sleep')
1402
1403 async def main():
1404 # Create a "cancel_me" Task
1405 task = asyncio.create_task(cancel_me())
1406
1407 # Wait for 1 second
1408 await asyncio.sleep(1)
1409
1410 task.cancel()
1411 try:
1412 await task
1413 except asyncio.CancelledError:
1414 print("main(): cancel_me is cancelled now")
1415
1416 asyncio.run(main())
1417
1418 # Expected output:
1419 #
1420 # cancel_me(): before sleep
1421 # cancel_me(): cancel sleep
1422 # cancel_me(): after sleep
1423 # main(): cancel_me is cancelled now
1424
1425 .. method:: cancelled()
1426
1427 Return ``True`` if the Task is *cancelled*.
1428
1429 The Task is *cancelled* when the cancellation was requested with
1430 :meth:`cancel` and the wrapped coroutine propagated the
1431 :exc:`CancelledError` exception thrown into it.
1432
1433 .. method:: uncancel()
1434
1435 Decrement the count of cancellation requests to this Task.
1436
1437 Returns the remaining number of cancellation requests.
1438
1439 Note that once execution of a cancelled task completed, further
1440 calls to :meth:`uncancel` are ineffective.
1441
1442 .. versionadded:: 3.11
1443
1444 This method is used by asyncio's internals and isn't expected to be
1445 used by end-user code. In particular, if a Task gets successfully
1446 uncancelled, this allows for elements of structured concurrency like
1447 :ref:`taskgroups` and :func:`asyncio.timeout` to continue running,
1448 isolating cancellation to the respective structured block.
1449 For example::
1450
1451 async def make_request_with_timeout():
1452 try:
1453 async with asyncio.timeout(1):
1454 # Structured block affected by the timeout:
1455 await make_request()
1456 await make_another_request()
1457 except TimeoutError:
1458 log("There was a timeout")
1459 # Outer code not affected by the timeout:
1460 await unrelated_code()
1461
1462 While the block with ``make_request()`` and ``make_another_request()``
1463 might get cancelled due to the timeout, ``unrelated_code()`` should
1464 continue running even in case of the timeout. This is implemented
1465 with :meth:`uncancel`. :class:`TaskGroup` context managers use
1466 :func:`uncancel` in a similar fashion.
1467
1468 If end-user code is, for some reason, suppressing cancellation by
1469 catching :exc:`CancelledError`, it needs to call this method to remove
1470 the cancellation state.
1471
1472 When this method decrements the cancellation count to zero,
1473 the method checks if a previous :meth:`cancel` call had arranged
1474 for :exc:`CancelledError` to be thrown into the task.
1475 If it hasn't been thrown yet, that arrangement will be
1476 rescinded (by resetting the internal ``_must_cancel`` flag).
1477
1478 .. versionchanged:: 3.13
1479 Changed to rescind pending cancellation requests upon reaching zero.
1480
1481 .. method:: cancelling()
1482
1483 Return the number of pending cancellation requests to this Task, i.e.,
1484 the number of calls to :meth:`cancel` less the number of
1485 :meth:`uncancel` calls.
1486
1487 Note that if this number is greater than zero but the Task is
1488 still executing, :meth:`cancelled` will still return ``False``.
1489 This is because this number can be lowered by calling :meth:`uncancel`,
1490 which can lead to the task not being cancelled after all if the
1491 cancellation requests go down to zero.
1492
1493 This method is used by asyncio's internals and isn't expected to be
1494 used by end-user code. See :meth:`uncancel` for more details.
1495
1496 .. versionadded:: 3.11