Coverage for Lib/asyncio/tasks.py: 96%

551 statements  

« prev     ^ index     » next       coverage.py v7.17.3, created at 2026-11-20 05:46 +0000

1"""Support for tasks, coroutines and the scheduler.""" 

2 

3__all__ = ( 

4 'Task', 'create_task', 

5 'FIRST_COMPLETED', 'FIRST_EXCEPTION', 'ALL_COMPLETED', 

6 'wait', 'wait_for', 'as_completed', 'sleep', 

7 'gather', 'shield', 'ensure_future', 'run_coroutine_threadsafe', 

8 'current_task', 'all_tasks', 

9 'create_eager_task_factory', 'eager_task_factory', 

10 '_register_task', '_unregister_task', '_enter_task', '_leave_task', 

11) 

12 

13import concurrent.futures 

14import contextvars 

15import functools 

16import inspect 

17import itertools 

18import math 

19import types 

20import weakref 

21from types import GenericAlias 

22 

23from . import base_tasks 

24from . import coroutines 

25from . import events 

26from . import exceptions 

27from . import futures 

28from . import queues 

29from . import timeouts 

30 

31# Helper to generate new task names 

32# This uses itertools.count() instead of a "+= 1" operation because the latter 

33# is not thread safe. See bpo-11866 for a longer explanation. 

34_task_name_counter = itertools.count(1).__next__ 

35 

36 

37def current_task(loop=None): 

38 """Return a currently executed task.""" 

39 if loop is None: 

40 loop = events.get_running_loop() 

41 return _current_tasks.get(loop) 

42 

43 

44def all_tasks(loop=None): 

45 """Return a set of all tasks for the loop.""" 

46 if loop is None: 

47 loop = events.get_running_loop() 

48 # capturing the set of eager tasks first, so if an eager task "graduates" 

49 # to a regular task in another thread, we don't risk missing it. 

50 eager_tasks = list(_eager_tasks) 

51 

52 return {t for t in itertools.chain(_scheduled_tasks, eager_tasks) 

53 if futures._get_loop(t) is loop and not t.done()} 

54 

55 

56class Task(futures._PyFuture): # Inherit Python Task implementation 

57 # from a Python Future implementation. 

58 

59 """A coroutine wrapped in a Future.""" 

60 

61 # An important invariant maintained while a Task not done: 

62 # _fut_waiter is either None or a Future. The Future 

63 # can be either done() or not done(). 

64 # The task can be in any of 3 states: 

65 # 

66 # - 1: _fut_waiter is not None and not _fut_waiter.done(): 

67 # __step() is *not* scheduled and the Task is waiting for _fut_waiter. 

68 # - 2: (_fut_waiter is None or _fut_waiter.done()) and __step() is scheduled: 

69 # the Task is waiting for __step() to be executed. 

70 # - 3: _fut_waiter is None and __step() is *not* scheduled: 

71 # the Task is currently executing (in __step()). 

72 # 

73 # * In state 1, one of the callbacks of __fut_waiter must be __wakeup(). 

74 # * The transition from 1 to 2 happens when _fut_waiter becomes done(), 

75 # as it schedules __wakeup() to be called (which calls __step() so 

76 # we way that __step() is scheduled). 

77 # * It transitions from 2 to 3 when __step() is executed, and it clears 

78 # _fut_waiter to None. 

79 

80 # If False, don't log a message if the task is destroyed while its 

81 # status is still pending 

82 _log_destroy_pending = True 

83 

84 def __init__(self, coro, *, loop=None, name=None, context=None, 

85 eager_start=False): 

86 super().__init__(loop=loop) 

87 if self._source_traceback: 

88 del self._source_traceback[-1] 

89 if not coroutines.iscoroutine(coro): 

90 # raise after Future.__init__(), attrs are required for __del__ 

91 # prevent logging for pending task in __del__ 

92 self._log_destroy_pending = False 

93 raise TypeError(f"a coroutine was expected, got {coro!r}") 

94 

95 if name is None: 

96 self._name = f'Task-{_task_name_counter()}' 

97 else: 

98 self._name = str(name) 

99 

100 self._num_cancels_requested = 0 

101 self._must_cancel = False 

102 self._fut_waiter = None 

103 self._coro = coro 

104 if context is None: 

105 self._context = contextvars.copy_context() 

106 elif not isinstance(context, contextvars.Context): 

107 # gh-157301: the passed value must be a contextvars.Context 

108 self._log_destroy_pending = False 

109 raise TypeError('a contextvars.Context was expected, ' 

110 f'got {type(context).__name__}') 

111 else: 

112 self._context = context 

113 

114 if eager_start and self._loop.is_running(): 

115 try: 

116 self.__eager_start() 

117 except: 

118 self._log_destroy_pending = False 

119 raise 

120 else: 

121 self._loop.call_soon(self.__step, context=self._context) 

122 _py_register_task(self) 

123 

124 def __del__(self): 

125 if self._state == futures._PENDING and self._log_destroy_pending: 

126 context = { 

127 'task': self, 

128 'message': 'Task was destroyed but it is pending!', 

129 } 

130 if self._source_traceback: 

131 context['source_traceback'] = self._source_traceback 

132 self._loop.call_exception_handler(context) 

133 super().__del__() 

134 

135 __class_getitem__ = classmethod(GenericAlias) 

136 

137 def __repr__(self): 

138 return base_tasks._task_repr(self) 

139 

140 def get_coro(self): 

141 return self._coro 

142 

143 def get_context(self): 

144 return self._context 

145 

146 def get_name(self): 

147 return self._name 

148 

149 def set_name(self, value): 

150 self._name = str(value) 

151 

152 def set_result(self, result): 

153 raise RuntimeError('Task does not support set_result operation') 

154 

155 def set_exception(self, exception): 

156 raise RuntimeError('Task does not support set_exception operation') 

157 

158 def get_stack(self, *, limit=None): 

159 """Return the list of stack frames for this task's coroutine. 

160 

161 If the coroutine is not done, this returns the stack where it is 

162 suspended. If the coroutine has completed successfully or was 

163 cancelled, this returns an empty list. If the coroutine was 

164 terminated by an exception, this returns the list of traceback 

165 frames. 

166 

167 The frames are always ordered from oldest to newest. 

168 

169 The optional limit gives the maximum number of frames to 

170 return; by default all available frames are returned. Its 

171 meaning differs depending on whether a stack or a traceback is 

172 returned: the newest frames of a stack are returned, but the 

173 oldest frames of a traceback are returned. (This matches the 

174 behavior of the traceback module.) 

175 

176 For reasons beyond our control, only one stack frame is 

177 returned for a suspended coroutine. 

178 """ 

179 return base_tasks._task_get_stack(self, limit) 

180 

181 def print_stack(self, *, limit=None, file=None): 

182 """Print the stack or traceback for this task's coroutine. 

183 

184 This produces output similar to that of the traceback module, 

185 for the frames retrieved by get_stack(). The limit argument 

186 is passed to get_stack(). The file argument is an I/O stream 

187 to which the output is written; by default output is written 

188 to sys.stderr. 

189 """ 

190 return base_tasks._task_print_stack(self, limit, file) 

191 

192 def cancel(self, msg=None): 

193 """Request that this task cancel itself. 

194 

195 This arranges for a CancelledError to be thrown into the 

196 wrapped coroutine on the next cycle through the event loop. 

197 The coroutine then has a chance to clean up or even deny 

198 the request using try/except/finally. 

199 

200 Unlike Future.cancel, this does not guarantee that the 

201 task will be cancelled: the exception might be caught and 

202 acted upon, delaying cancellation of the task or preventing 

203 cancellation completely. The task may also return a value or 

204 raise a different exception. 

205 

206 Immediately after this method is called, Task.cancelled() will 

207 not return True (unless the task was already cancelled). A 

208 task will be marked as cancelled when the wrapped coroutine 

209 terminates with a CancelledError exception (even if cancel() 

210 was not called). 

211 

212 This also increases the task's count of cancellation requests. 

213 """ 

214 self._log_traceback = False 

215 if self.done(): 

216 return False 

217 self._num_cancels_requested += 1 

218 # These two lines are controversial. See discussion starting at 

219 # https://github.com/python/cpython/pull/31394#issuecomment-1053545331 

220 # Also remember that this is duplicated in _asynciomodule.c. 

221 # if self._num_cancels_requested > 1: 

222 # return False 

223 if self._fut_waiter is not None: 

224 if self._fut_waiter.cancel(msg=msg): 

225 # Leave self._fut_waiter; it may be a Task that 

226 # catches and ignores the cancellation so we may have 

227 # to cancel it again later. 

228 return True 

229 # It must be the case that self.__step is already scheduled. 

230 self._must_cancel = True 

231 self._cancel_message = msg 

232 return True 

233 

234 def cancelling(self): 

235 """Return the count of the task's cancellation requests. 

236 

237 This count is incremented when .cancel() is called 

238 and may be decremented using .uncancel(). 

239 """ 

240 return self._num_cancels_requested 

241 

242 def uncancel(self): 

243 """Decrement the task's count of cancellation requests. 

244 

245 This should be called by the party that called `cancel()` on the task 

246 beforehand. 

247 

248 Returns the remaining number of cancellation requests. 

249 """ 

250 if self._num_cancels_requested > 0: 250 ↛ 254line 250 didn't jump to line 254 because the condition on line 250 was always true

251 self._num_cancels_requested -= 1 

252 if self._num_cancels_requested == 0: 252 ↛ 254line 252 didn't jump to line 254 because the condition on line 252 was always true

253 self._must_cancel = False 

254 return self._num_cancels_requested 

255 

256 def __eager_start(self): 

257 prev_task = _py_swap_current_task(self._loop, self) 

258 try: 

259 _py_register_eager_task(self) 

260 # gh-157299: the eager step must record the awaited_by edge 

261 futures.future_add_to_awaited_by(self, prev_task) 

262 try: 

263 self._context.run(self.__step_run_and_handle_result, None) 

264 finally: 

265 futures.future_discard_from_awaited_by(self, prev_task) 

266 _py_unregister_eager_task(self) 

267 finally: 

268 try: 

269 curtask = _py_swap_current_task(self._loop, prev_task) 

270 assert curtask is self 

271 finally: 

272 if self.done(): 

273 self._coro = None 

274 self = None # Needed to break cycles when an exception occurs. 

275 else: 

276 _py_register_task(self) 

277 

278 def __step(self, exc=None): 

279 if self.done(): 

280 raise exceptions.InvalidStateError( 

281 f'__step(): already done: {self!r}, {exc!r}') 

282 if self._must_cancel: 

283 # gh-108549: do not swallow SystemExit and KeyboardInterrupt. 

284 if not isinstance(exc, (exceptions.CancelledError, 

285 SystemExit, KeyboardInterrupt)): 

286 exc = self._make_cancelled_error() 

287 self._must_cancel = False 

288 self._fut_waiter = None 

289 

290 _py_enter_task(self._loop, self) 

291 try: 

292 self.__step_run_and_handle_result(exc) 

293 finally: 

294 _py_leave_task(self._loop, self) 

295 self = None # Needed to break cycles when an exception occurs. 

296 

297 def __step_run_and_handle_result(self, exc): 

298 coro = self._coro 

299 try: 

300 if exc is None: 

301 # We use the `send` method directly, because coroutines 

302 # don't have `__iter__` and `__next__` methods. 

303 result = coro.send(None) 

304 else: 

305 result = coro.throw(exc) 

306 except StopIteration as exc: 

307 if self._must_cancel: 

308 # Task is cancelled right before coro stops. 

309 self._must_cancel = False 

310 super().cancel(msg=self._cancel_message) 

311 else: 

312 super().set_result(exc.value) 

313 except exceptions.CancelledError as exc: 

314 # Save the original exception so we can chain it later. 

315 self._cancelled_exc = exc 

316 super().cancel() # I.e., Future.cancel(self). 

317 except (KeyboardInterrupt, SystemExit) as exc: 

318 super().set_exception(exc) 

319 raise 

320 except BaseException as exc: 

321 super().set_exception(exc) 

322 else: 

323 blocking = getattr(result, '_asyncio_future_blocking', None) 

324 if blocking is not None: 

325 # Yielded Future must come from Future.__iter__(). 

326 if futures._get_loop(result) is not self._loop: 

327 new_exc = RuntimeError( 

328 f'Task {self!r} got Future ' 

329 f'{result!r} attached to a different loop') 

330 self._loop.call_soon( 

331 self.__step, new_exc, context=self._context) 

332 elif blocking: 332 ↛ 349line 332 didn't jump to line 349 because the condition on line 332 was always true

333 if result is self: 

334 new_exc = RuntimeError( 

335 f'Task cannot await on itself: {self!r}') 

336 self._loop.call_soon( 

337 self.__step, new_exc, context=self._context) 

338 else: 

339 futures.future_add_to_awaited_by(result, self) 

340 result._asyncio_future_blocking = False 

341 result.add_done_callback( 

342 self.__wakeup, context=self._context) 

343 self._fut_waiter = result 

344 if self._must_cancel: 

345 if self._fut_waiter.cancel( 345 ↛ 371line 345 didn't jump to line 371 because the condition on line 345 was always true

346 msg=self._cancel_message): 

347 self._must_cancel = False 

348 else: 

349 new_exc = RuntimeError( 

350 f'yield was used instead of yield from ' 

351 f'in task {self!r} with {result!r}') 

352 self._loop.call_soon( 

353 self.__step, new_exc, context=self._context) 

354 

355 elif result is None: 355 ↛ 358line 355 didn't jump to line 358 because the condition on line 355 was always true

356 # Bare yield relinquishes control for one event loop iteration. 

357 self._loop.call_soon(self.__step, context=self._context) 

358 elif inspect.isgenerator(result): 

359 # Yielding a generator is just wrong. 

360 new_exc = RuntimeError( 

361 f'yield was used instead of yield from for ' 

362 f'generator in task {self!r} with {result!r}') 

363 self._loop.call_soon( 

364 self.__step, new_exc, context=self._context) 

365 else: 

366 # Yielding something else is an error. 

367 new_exc = RuntimeError(f'Task got bad yield: {result!r}') 

368 self._loop.call_soon( 

369 self.__step, new_exc, context=self._context) 

370 finally: 

371 self = None # Needed to break cycles when an exception occurs. 

372 

373 def __wakeup(self, future): 

374 futures.future_discard_from_awaited_by(future, self) 

375 try: 

376 future.result() 

377 except BaseException as exc: 

378 # This may also be a cancellation. 

379 self.__step(exc) 

380 else: 

381 # Don't pass the value of `future.result()` explicitly, 

382 # as `Future.__iter__` and `Future.__await__` don't need it. 

383 # If we call `__step(value, None)` instead of `__step()`, 

384 # Python eval loop would use `.send(value)` method call, 

385 # instead of `__next__()`, which is slower for futures 

386 # that return non-generator iterators from their `__iter__`. 

387 self.__step() 

388 self = None # Needed to break cycles when an exception occurs. 

389 

390 

391_PyTask = Task 

392 

393 

394try: 

395 import _asyncio 

396except ImportError: 

397 pass 

398else: 

399 # _CTask is needed for tests. 

400 Task = _CTask = _asyncio.Task 

401 

402 

403def create_task(coro, **kwargs): 

404 """Schedule the execution of a coroutine object in a spawn task. 

405 

406 Return a Task object. 

407 """ 

408 loop = events.get_running_loop() 

409 return loop.create_task(coro, **kwargs) 

410 

411 

412# wait() and as_completed() similar to those in PEP 3148. 

413 

414FIRST_COMPLETED = concurrent.futures.FIRST_COMPLETED 

415FIRST_EXCEPTION = concurrent.futures.FIRST_EXCEPTION 

416ALL_COMPLETED = concurrent.futures.ALL_COMPLETED 

417 

418 

419async def wait(fs, *, timeout=None, return_when=ALL_COMPLETED): 

420 """Wait for the Futures or Tasks given by fs to complete. 

421 

422 The fs iterable must not be empty. 

423 

424 Returns two sets of Future: (done, pending). 

425 

426 Usage: 

427 

428 done, pending = await asyncio.wait(fs) 

429 

430 Note: This does not raise TimeoutError! Futures that aren't done 

431 when the timeout occurs are returned in the second set. 

432 """ 

433 if futures.isfuture(fs) or coroutines.iscoroutine(fs): 

434 raise TypeError(f"expect a list of futures, not {type(fs).__name__}") 

435 if not fs: 

436 raise ValueError('Set of Tasks/Futures is empty.') 

437 if return_when not in (FIRST_COMPLETED, FIRST_EXCEPTION, ALL_COMPLETED): 

438 raise ValueError(f'Invalid return_when value: {return_when}') 

439 

440 fs = set(fs) 

441 

442 if any(coroutines.iscoroutine(f) for f in fs): 442 ↛ 443line 442 didn't jump to line 443 because the condition on line 442 was never true

443 raise TypeError("Passing coroutines is forbidden, use tasks explicitly.") 

444 

445 loop = events.get_running_loop() 

446 return await _wait(fs, timeout, return_when, loop) 

447 

448 

449def _release_waiter(waiter, *args): 

450 if not waiter.done(): 450 ↛ exitline 450 didn't return from function '_release_waiter' because the condition on line 450 was always true

451 waiter.set_result(None) 

452 

453 

454async def wait_for(fut, timeout): 

455 """Wait for the single Future or coroutine to complete, with timeout. 

456 

457 Returns result of the Future or coroutine. When a timeout occurs, 

458 it cancels fut and raises TimeoutError. To prevent fut from being 

459 cancelled, wrap it in shield(). 

460 

461 If the wait is cancelled, fut is also cancelled. 

462 

463 If fut suppresses the cancellation and returns a value instead, 

464 that value is returned. 

465 

466 This function is a coroutine. 

467 """ 

468 # The special case for timeout <= 0 is for the following case: 

469 # 

470 # async def test_waitfor(): 

471 # func_started = False 

472 # 

473 # async def func(): 

474 # nonlocal func_started 

475 # func_started = True 

476 # 

477 # try: 

478 # await asyncio.wait_for(func(), 0) 

479 # except asyncio.TimeoutError: 

480 # assert not func_started 

481 # else: 

482 # assert False 

483 # 

484 # asyncio.run(test_waitfor()) 

485 

486 

487 if timeout is not None and timeout <= 0: 

488 fut = ensure_future(fut) 

489 

490 if fut.done(): 

491 return fut.result() 

492 

493 await _cancel_and_wait(fut) 

494 try: 

495 return fut.result() 

496 except exceptions.CancelledError as exc: 

497 raise TimeoutError from exc 

498 

499 async with timeouts.timeout(timeout): 

500 return await fut 

501 

502async def _wait(fs, timeout, return_when, loop): 

503 """Internal helper for wait(). 

504 

505 The fs argument must be a collection of Futures. 

506 """ 

507 assert fs, 'Set of Futures is empty.' 

508 waiter = loop.create_future() 

509 timeout_handle = None 

510 if timeout is not None: 

511 timeout_handle = loop.call_later(timeout, _release_waiter, waiter) 

512 counter = len(fs) 

513 cur_task = current_task() 

514 

515 def _on_completion(f): 

516 nonlocal counter 

517 counter -= 1 

518 if (counter <= 0 or 

519 return_when == FIRST_COMPLETED or 

520 return_when == FIRST_EXCEPTION and (not f.cancelled() and 

521 f.exception() is not None)): 

522 if timeout_handle is not None: 522 ↛ 523line 522 didn't jump to line 523 because the condition on line 522 was never true

523 timeout_handle.cancel() 

524 if not waiter.done(): 

525 waiter.set_result(None) 

526 futures.future_discard_from_awaited_by(f, cur_task) 

527 

528 for f in fs: 

529 f.add_done_callback(_on_completion) 

530 futures.future_add_to_awaited_by(f, cur_task) 

531 

532 try: 

533 await waiter 

534 finally: 

535 if timeout_handle is not None: 

536 timeout_handle.cancel() 

537 for f in fs: 

538 f.remove_done_callback(_on_completion) 

539 futures.future_discard_from_awaited_by(f, cur_task) 

540 

541 done, pending = set(), set() 

542 for f in fs: 

543 if f.done(): 

544 done.add(f) 

545 else: 

546 pending.add(f) 

547 return done, pending 

548 

549 

550async def _cancel_and_wait(fut): 

551 """Cancel the *fut* future or task and wait until it completes.""" 

552 

553 loop = events.get_running_loop() 

554 waiter = loop.create_future() 

555 cb = functools.partial(_release_waiter, waiter) 

556 fut.add_done_callback(cb) 

557 

558 # gh-157058: awaiting the waiter leaves no edge on fut, add it here 

559 cur_task = current_task() 

560 futures.future_add_to_awaited_by(fut, cur_task) 

561 

562 try: 

563 fut.cancel() 

564 # We cannot wait on *fut* directly to make 

565 # sure _cancel_and_wait itself is reliably cancellable. 

566 await waiter 

567 finally: 

568 fut.remove_done_callback(cb) 

569 futures.future_discard_from_awaited_by(fut, cur_task) 

570 

571 

572class _AsCompletedIterator: 

573 """Iterator of awaitables representing tasks of asyncio.as_completed. 

574 

575 As an asynchronous iterator, iteration yields futures as they finish. As a 

576 plain iterator, new coroutines are yielded that will return or raise the 

577 result of the next underlying future to complete. 

578 """ 

579 def __init__(self, aws, timeout): 

580 self._done = queues.Queue() 

581 self._timeout_handle = None 

582 

583 loop = events.get_event_loop() 

584 # The iterator may be created outside of a running event loop and 

585 # then driven with loop.run_until_complete(), in which case there 

586 # is no current task to record as the waiter. 

587 if events._get_running_loop() is loop: 

588 self._cur_task = current_task(loop) 

589 else: 

590 self._cur_task = None 

591 todo = {ensure_future(aw, loop=loop) for aw in set(aws)} 

592 for f in todo: 

593 f.add_done_callback(self._handle_completion) 

594 futures.future_add_to_awaited_by(f, self._cur_task) 

595 if todo and timeout is not None: 

596 self._timeout_handle = ( 

597 loop.call_later(timeout, self._handle_timeout) 

598 ) 

599 self._todo = todo 

600 self._todo_left = len(todo) 

601 

602 def __aiter__(self): 

603 return self 

604 

605 def __iter__(self): 

606 return self 

607 

608 async def __anext__(self): 

609 if not self._todo_left: 

610 raise StopAsyncIteration 

611 assert self._todo_left > 0 

612 self._todo_left -= 1 

613 return await self._wait_for_one() 

614 

615 def __next__(self): 

616 if not self._todo_left: 

617 raise StopIteration 

618 assert self._todo_left > 0 

619 self._todo_left -= 1 

620 return self._wait_for_one(resolve=True) 

621 

622 def _handle_timeout(self): 

623 for f in self._todo: 

624 f.remove_done_callback(self._handle_completion) 

625 futures.future_discard_from_awaited_by(f, self._cur_task) 

626 self._done.put_nowait(None) # Sentinel for _wait_for_one(). 

627 self._todo.clear() # Can't do todo.remove(f) in the loop. 

628 

629 def _handle_completion(self, f): 

630 if not self._todo: 630 ↛ 631line 630 didn't jump to line 631 because the condition on line 630 was never true

631 return # _handle_timeout() was here first. 

632 self._todo.remove(f) 

633 futures.future_discard_from_awaited_by(f, self._cur_task) 

634 self._done.put_nowait(f) 

635 if not self._todo and self._timeout_handle is not None: 

636 self._timeout_handle.cancel() 

637 

638 async def _wait_for_one(self, resolve=False): 

639 # Wait for the next future to be done and return it unless resolve is 

640 # set, in which case return either the result of the future or raise 

641 # an exception. 

642 try: 

643 f = await self._done.get() 

644 except: 

645 self._todo_left += 1 

646 raise 

647 if f is None: 

648 # Dummy value from _handle_timeout(). 

649 raise exceptions.TimeoutError 

650 return f.result() if resolve else f 

651 

652 

653def as_completed(fs, *, timeout=None): 

654 """Create an iterator of awaitables or their results in completion order. 

655 

656 Run the supplied awaitables concurrently. The returned object can be 

657 iterated to obtain the results of the awaitables as they finish. 

658 

659 The object returned can be iterated as an asynchronous iterator or 

660 a plain iterator. When asynchronous iteration is used, the 

661 originally-supplied awaitables are yielded if they are tasks or 

662 futures. This makes it easy to correlate previously-scheduled tasks 

663 with their results: 

664 

665 ipv4_connect = create_task(open_connection("127.0.0.1", 80)) 

666 ipv6_connect = create_task(open_connection("::1", 80)) 

667 tasks = [ipv4_connect, ipv6_connect] 

668 

669 async for earliest_connect in as_completed(tasks): 

670 # earliest_connect is done. The result can be obtained by 

671 # awaiting it or calling earliest_connect.result() 

672 reader, writer = await earliest_connect 

673 

674 if earliest_connect is ipv6_connect: 

675 print("IPv6 connection established.") 

676 else: 

677 print("IPv4 connection established.") 

678 

679 During asynchronous iteration, implicitly-created tasks will be 

680 yielded for supplied awaitables that aren't tasks or futures. 

681 

682 When used as a plain iterator, each iteration yields a new coroutine 

683 that returns the result or raises the exception of the next completed 

684 awaitable. This pattern is compatible with Python versions older than 

685 3.13: 

686 

687 ipv4_connect = create_task(open_connection("127.0.0.1", 80)) 

688 ipv6_connect = create_task(open_connection("::1", 80)) 

689 tasks = [ipv4_connect, ipv6_connect] 

690 

691 for next_connect in as_completed(tasks): 

692 # next_connect is not one of the original task objects. It must 

693 # be awaited to obtain the result value or raise the exception 

694 # of the awaitable that finishes next. 

695 reader, writer = await next_connect 

696 

697 A TimeoutError is raised if the timeout occurs before all awaitables 

698 are done. This is raised by the async for loop during asynchronous 

699 iteration or by the coroutines yielded during plain iteration. 

700 """ 

701 if inspect.isawaitable(fs): 

702 raise TypeError( 

703 f"expects an iterable of awaitables, not {type(fs).__name__}" 

704 ) 

705 

706 return _AsCompletedIterator(fs, timeout) 

707 

708 

709@types.coroutine 

710def __sleep0(): 

711 """Skip one event loop run cycle. 

712 

713 This is a private helper for 'asyncio.sleep()', used 

714 when the 'delay' is set to 0. It uses a bare 'yield' 

715 expression (which Task.__step knows how to handle) 

716 instead of creating a Future object. 

717 """ 

718 yield 

719 

720 

721async def sleep(delay, result=None): 

722 """Coroutine that completes after a given time (in seconds).""" 

723 if delay <= 0: 

724 await __sleep0() 

725 return result 

726 

727 if math.isnan(delay): 

728 raise ValueError("Invalid delay: NaN (not a number)") 

729 

730 loop = events.get_running_loop() 

731 future = loop.create_future() 

732 h = loop.call_later(delay, 

733 futures._set_result_unless_cancelled, 

734 future, result) 

735 try: 

736 return await future 

737 finally: 

738 h.cancel() 

739 

740 

741def ensure_future(coro_or_future, *, loop=None): 

742 """Wrap a coroutine or an awaitable in a future. 

743 

744 If the argument is a Future, it is returned directly. 

745 """ 

746 if futures.isfuture(coro_or_future): 

747 if loop is not None and loop is not futures._get_loop(coro_or_future): 

748 raise ValueError('The future belongs to a different loop than ' 

749 'the one specified as the loop argument') 

750 return coro_or_future 

751 should_close = True 

752 if not coroutines.iscoroutine(coro_or_future): 

753 if inspect.isawaitable(coro_or_future): 

754 async def _wrap_awaitable(awaitable): 

755 return await awaitable 

756 

757 coro_or_future = _wrap_awaitable(coro_or_future) 

758 should_close = False 

759 else: 

760 raise TypeError('An asyncio.Future, a coroutine or an awaitable ' 

761 'is required') 

762 

763 if loop is None: 

764 loop = events.get_event_loop() 

765 try: 

766 return loop.create_task(coro_or_future) 

767 except RuntimeError: 

768 if should_close: 768 ↛ 770line 768 didn't jump to line 770 because the condition on line 768 was always true

769 coro_or_future.close() 

770 raise 

771 

772 

773class _GatheringFuture(futures.Future): 

774 """Helper for gather(). 

775 

776 This overrides cancel() to cancel all the children and act more 

777 like Task.cancel(), which doesn't immediately mark itself as 

778 cancelled. 

779 """ 

780 

781 def __init__(self, children, *, loop): 

782 assert loop is not None 

783 super().__init__(loop=loop) 

784 self._children = children 

785 self._cancel_requested = False 

786 

787 def cancel(self, msg=None): 

788 if self.done(): 

789 return False 

790 ret = False 

791 for child in self._children: 

792 if child.cancel(msg=msg): 

793 ret = True 

794 if ret: 

795 # If any child tasks were actually cancelled, we should 

796 # propagate the cancellation request regardless of 

797 # *return_exceptions* argument. See issue 32684. 

798 self._cancel_requested = True 

799 return ret 

800 

801 

802def _discard_awaited_by(children, waiter): 

803 for fut in children: 

804 futures.future_discard_from_awaited_by(fut, waiter) 

805 

806 

807def gather(*coros_or_futures, return_exceptions=False): 

808 """Return a future aggregating results from the given coroutines/futures. 

809 

810 Coroutines will be wrapped in a future and scheduled in the event 

811 loop. They will not necessarily be scheduled in the same order as 

812 passed in. 

813 

814 All futures must share the same event loop. If all the tasks are 

815 done successfully, the returned future's result is the list of 

816 results (in the order of the original sequence, not necessarily 

817 the order of results arrival). If *return_exceptions* is True, 

818 exceptions in the tasks are treated the same as successful 

819 results, and gathered in the result list; otherwise, the first 

820 raised exception will be immediately propagated to the returned 

821 future. 

822 

823 Cancellation: if the outer Future is cancelled, all children (that 

824 have not completed yet) are also cancelled. If any child is 

825 cancelled, this is treated as if it raised CancelledError -- 

826 the outer Future is *not* cancelled in this case. (This is to 

827 prevent the cancellation of one child to cause other children to 

828 be cancelled.) 

829 

830 If *return_exceptions* is False, cancelling gather() after it 

831 has been marked done won't cancel any submitted awaitables. 

832 For instance, gather can be marked done after propagating an 

833 exception to the caller, therefore, calling ``gather.cancel()`` 

834 after catching an exception (raised by one of the awaitables) from 

835 gather won't cancel any other awaitables. 

836 """ 

837 if not coros_or_futures: 

838 loop = events.get_event_loop() 

839 outer = loop.create_future() 

840 outer.set_result([]) 

841 return outer 

842 

843 loop = events._get_running_loop() 

844 if loop is not None: 

845 cur_task = current_task(loop) 

846 else: 

847 cur_task = None 

848 

849 def _done_callback(fut, cur_task=cur_task): 

850 nonlocal nfinished 

851 nfinished += 1 

852 

853 if cur_task is not None: 

854 futures.future_discard_from_awaited_by(fut, cur_task) 

855 

856 if outer is None or outer.done(): 

857 if not fut.cancelled(): 

858 # Mark exception retrieved. 

859 fut.exception() 

860 return 

861 

862 if not return_exceptions: 

863 if fut.cancelled(): 

864 # Check if 'fut' is cancelled first, as 

865 # 'fut.exception()' will *raise* a CancelledError 

866 # instead of returning it. 

867 exc = fut._make_cancelled_error() 

868 # gh-157213: children outliving gather() must lose the edge 

869 _discard_awaited_by(children, cur_task) 

870 outer.set_exception(exc) 

871 return 

872 else: 

873 exc = fut.exception() 

874 if exc is not None: 

875 _discard_awaited_by(children, cur_task) 

876 outer.set_exception(exc) 

877 return 

878 

879 if nfinished == nfuts: 

880 # All futures are done; create a list of results 

881 # and set it to the 'outer' future. 

882 results = [] 

883 

884 for fut in children: 

885 if fut.cancelled(): 

886 # Check if 'fut' is cancelled first, as 'fut.exception()' 

887 # will *raise* a CancelledError instead of returning it. 

888 # Also, since we're adding the exception return value 

889 # to 'results' instead of raising it, don't bother 

890 # setting __context__. This also lets us preserve 

891 # calling '_make_cancelled_error()' at most once. 

892 res = exceptions.CancelledError( 

893 '' if fut._cancel_message is None else 

894 fut._cancel_message) 

895 else: 

896 res = fut.exception() 

897 if res is None: 

898 res = fut.result() 

899 results.append(res) 

900 

901 if outer._cancel_requested: 

902 # If gather is being cancelled we must propagate the 

903 # cancellation regardless of *return_exceptions* argument. 

904 # See issue 32684. 

905 exc = fut._make_cancelled_error() 

906 outer.set_exception(exc) 

907 else: 

908 outer.set_result(results) 

909 

910 arg_to_fut = {} 

911 children = [] 

912 nfuts = 0 

913 nfinished = 0 

914 done_futs = [] 

915 outer = None # bpo-46672 

916 for arg in coros_or_futures: 

917 if arg not in arg_to_fut: 

918 fut = ensure_future(arg, loop=loop) 

919 if loop is None: 

920 loop = futures._get_loop(fut) 

921 if fut is not arg: 

922 # 'arg' was not a Future, therefore, 'fut' is a new 

923 # Future created specifically for 'arg'. Since the caller 

924 # can't control it, disable the "destroy pending task" 

925 # warning. 

926 fut._log_destroy_pending = False 

927 nfuts += 1 

928 arg_to_fut[arg] = fut 

929 if fut.done(): 

930 done_futs.append(fut) 

931 else: 

932 fut.add_done_callback(_done_callback) 

933 

934 else: 

935 # There's a duplicate Future object in coros_or_futures. 

936 fut = arg_to_fut[arg] 

937 

938 children.append(fut) 

939 

940 outer = _GatheringFuture(children, loop=loop) 

941 # Add the awaited-by edges only after all arguments are validated 

942 if cur_task is not None and len(done_futs) < nfuts: 

943 for fut in arg_to_fut.values(): 

944 if not fut.done(): 

945 futures.future_add_to_awaited_by(fut, cur_task) 

946 # Run done callbacks after GatheringFuture created so any post-processing 

947 # can be performed at this point 

948 # optimization: in the special case that *all* futures finished eagerly, 

949 # this will effectively complete the gather eagerly, with the last 

950 # callback setting the result (or exception) on outer before returning it 

951 for fut in done_futs: 

952 _done_callback(fut) 

953 return outer 

954 

955 

956def shield(arg): 

957 """Wait for a future, shielding it from cancellation. 

958 

959 The statement 

960 

961 task = asyncio.create_task(something()) 

962 res = await shield(task) 

963 

964 is exactly equivalent to the statement 

965 

966 res = await something() 

967 

968 *except* that if the coroutine containing it is cancelled, the 

969 task running in something() is not cancelled. From the POV of 

970 something(), the cancellation did not happen. But its caller is 

971 still cancelled, so the yield-from expression still raises 

972 CancelledError. Note: If something() is cancelled by other means 

973 this will still cancel shield(). 

974 

975 If you want to completely ignore cancellation (not recommended) 

976 you can combine shield() with a try/except clause, as follows: 

977 

978 task = asyncio.create_task(something()) 

979 try: 

980 res = await shield(task) 

981 except CancelledError: 

982 res = None 

983 

984 Save a reference to tasks passed to this function, to avoid 

985 a task disappearing mid-execution. The event loop only keeps 

986 weak references to tasks. A task that isn't referenced elsewhere 

987 may get garbage collected at any time, even before it's done. 

988 """ 

989 inner = ensure_future(arg) 

990 if inner.done(): 

991 # Shortcut. 

992 return inner 

993 loop = futures._get_loop(inner) 

994 outer = loop.create_future() 

995 

996 if loop is not None and (cur_task := current_task(loop)) is not None: 

997 futures.future_add_to_awaited_by(inner, cur_task) 

998 else: 

999 cur_task = None 

1000 

1001 def _clear_awaited_by_callback(inner): 

1002 futures.future_discard_from_awaited_by(inner, cur_task) 

1003 

1004 def _inner_done_callback(inner): 

1005 if outer.cancelled(): 1005 ↛ 1006line 1005 didn't jump to line 1006 because the condition on line 1005 was never true

1006 return 

1007 

1008 if inner.cancelled(): 

1009 outer.cancel() 

1010 else: 

1011 exc = inner.exception() 

1012 if exc is not None: 

1013 outer.set_exception(exc) 

1014 else: 

1015 outer.set_result(inner.result()) 

1016 

1017 def _outer_done_callback(outer): 

1018 if not inner.done(): 

1019 inner.remove_done_callback(_inner_done_callback) 

1020 if cur_task is not None: 

1021 inner.remove_done_callback(_clear_awaited_by_callback) 

1022 futures.future_discard_from_awaited_by(inner, cur_task) 

1023 

1024 if cur_task is not None: 

1025 inner.add_done_callback(_clear_awaited_by_callback) 

1026 

1027 

1028 inner.add_done_callback(_inner_done_callback) 

1029 outer.add_done_callback(_outer_done_callback) 

1030 return outer 

1031 

1032 

1033def run_coroutine_threadsafe(coro, loop): 

1034 """Submit a coroutine object to a given event loop. 

1035 

1036 Return a concurrent.futures.Future to access the result. 

1037 """ 

1038 if not coroutines.iscoroutine(coro): 1038 ↛ 1039line 1038 didn't jump to line 1039 because the condition on line 1038 was never true

1039 raise TypeError('A coroutine object is required') 

1040 future = concurrent.futures.Future() 

1041 

1042 def callback(): 

1043 try: 

1044 futures._chain_future(ensure_future(coro, loop=loop), future) 

1045 except (SystemExit, KeyboardInterrupt): 

1046 raise 

1047 except BaseException as exc: 

1048 if future.set_running_or_notify_cancel(): 1048 ↛ 1050line 1048 didn't jump to line 1050 because the condition on line 1048 was always true

1049 future.set_exception(exc) 

1050 raise 

1051 

1052 loop.call_soon_threadsafe(callback) 

1053 return future 

1054 

1055 

1056def create_eager_task_factory(custom_task_constructor): 

1057 """Create a function suitable for use as a task factory on an event-loop. 

1058 

1059 Example usage: 

1060 

1061 loop.set_task_factory( 

1062 asyncio.create_eager_task_factory(my_task_constructor)) 

1063 

1064 Now, tasks created will be started immediately (rather than being first 

1065 scheduled to an event loop). The constructor argument can be any 

1066 callable that returns a Task-compatible object and has a signature 

1067 compatible with `Task.__init__`; it must have the `eager_start` 

1068 keyword argument. 

1069 

1070 Most applications will use `Task` for `custom_task_constructor` and in 

1071 this case there's no need to call `create_eager_task_factory()` 

1072 directly. Instead the global `eager_task_factory` instance can be 

1073 used. E.g. `loop.set_task_factory(asyncio.eager_task_factory)`. 

1074 """ 

1075 

1076 def factory(loop, coro, *, eager_start=True, **kwargs): 

1077 return custom_task_constructor( 

1078 coro, loop=loop, eager_start=eager_start, **kwargs) 

1079 

1080 return factory 

1081 

1082 

1083eager_task_factory = create_eager_task_factory(Task) 

1084 

1085 

1086# Collectively these two sets hold references to the complete set of active 

1087# tasks. Eagerly executed tasks use a faster regular set as an optimization 

1088# but may graduate to a WeakSet if the task blocks on IO. 

1089_scheduled_tasks = weakref.WeakSet() 

1090_eager_tasks = set() 

1091 

1092# Dictionary containing tasks that are currently active in 

1093# all running event loops. {EventLoop: Task} 

1094_current_tasks = {} 

1095 

1096 

1097def _register_task(task): 

1098 """Register an asyncio Task scheduled to run on an event loop.""" 

1099 _scheduled_tasks.add(task) 

1100 

1101 

1102def _register_eager_task(task): 

1103 """Register an asyncio Task about to be eagerly executed.""" 

1104 _eager_tasks.add(task) 

1105 

1106 

1107def _enter_task(loop, task): 

1108 current_task = _current_tasks.get(loop) 

1109 if current_task is not None: 

1110 raise RuntimeError(f"Cannot enter into task {task!r} while another " 

1111 f"task {current_task!r} is being executed.") 

1112 _current_tasks[loop] = task 

1113 

1114 

1115def _leave_task(loop, task): 

1116 current_task = _current_tasks.get(loop) 

1117 if current_task is not task: 

1118 raise RuntimeError(f"Leaving task {task!r} does not match " 

1119 f"the current task {current_task!r}.") 

1120 del _current_tasks[loop] 

1121 

1122 

1123def _swap_current_task(loop, task): 

1124 prev_task = _current_tasks.get(loop) 

1125 if task is None: 

1126 del _current_tasks[loop] 

1127 else: 

1128 _current_tasks[loop] = task 

1129 return prev_task 

1130 

1131 

1132def _unregister_task(task): 

1133 """Unregister a completed, scheduled Task.""" 

1134 _scheduled_tasks.discard(task) 

1135 

1136 

1137def _unregister_eager_task(task): 

1138 """Unregister a task which finished its first eager step.""" 

1139 _eager_tasks.discard(task) 

1140 

1141 

1142_py_current_task = current_task 

1143_py_register_task = _register_task 

1144_py_register_eager_task = _register_eager_task 

1145_py_unregister_task = _unregister_task 

1146_py_unregister_eager_task = _unregister_eager_task 

1147_py_enter_task = _enter_task 

1148_py_leave_task = _leave_task 

1149_py_swap_current_task = _swap_current_task 

1150_py_all_tasks = all_tasks 

1151 

1152try: 

1153 from _asyncio import (_register_task, _register_eager_task, 

1154 _unregister_task, _unregister_eager_task, 

1155 _enter_task, _leave_task, _swap_current_task, 

1156 current_task, all_tasks) 

1157except ImportError: 

1158 pass 

1159else: 

1160 _c_current_task = current_task 

1161 _c_register_task = _register_task 

1162 _c_register_eager_task = _register_eager_task 

1163 _c_unregister_task = _unregister_task 

1164 _c_unregister_eager_task = _unregister_eager_task 

1165 _c_enter_task = _enter_task 

1166 _c_leave_task = _leave_task 

1167 _c_swap_current_task = _swap_current_task 

1168 _c_all_tasks = all_tasks