Debian Codegraph @

Doc/library/asyncio-eventloop.rst

raw
1 .. currentmodule:: asyncio
2
3
4 .. _asyncio-event-loop:
5
6 ==========
7 Event loop
8 ==========
9
10 **Source code:** :source:`Lib/asyncio/events.py`,
11 :source:`Lib/asyncio/base_events.py`
12
13 ------------------------------------
14
15 .. rubric:: Preface
16
17 The event loop is the core of every asyncio application.
18 Event loops run asynchronous tasks and callbacks, perform network
19 IO operations, and run subprocesses.
20
21 Application developers should typically use the high-level asyncio functions,
22 such as :func:`asyncio.run`, and should rarely need to reference the loop
23 object or call its methods. This section is intended mostly for authors
24 of lower-level code, libraries, and frameworks, who need finer control over
25 the event loop behavior.
26
27 .. rubric:: Obtaining the Event Loop
28
29 The following low-level functions can be used to get, set, or create
30 an event loop:
31
32 .. function:: get_running_loop()
33
34 Return the running event loop in the current OS thread.
35
36 Raise a :exc:`RuntimeError` if there is no running event loop.
37
38 This function can only be called from a coroutine or a callback.
39
40 .. versionadded:: 3.7
41
42 .. function:: get_event_loop()
43
44 Get the current event loop.
45
46 When called from a coroutine or a callback (e.g. scheduled with
47 call_soon or similar API), this function will always return the
48 running event loop.
49
50 If there is no running event loop set, the function will return
51 the result of the ``get_event_loop_policy().get_event_loop()`` call.
52
53 Because this function has rather complex behavior (especially
54 when custom event loop policies are in use), using the
55 :func:`get_running_loop` function is preferred to :func:`get_event_loop`
56 in coroutines and callbacks.
57
58 As noted above, consider using the higher-level :func:`asyncio.run` function,
59 instead of using these lower level functions to manually create and close an
60 event loop.
61
62 .. versionchanged:: 3.14
63 Raises a :exc:`RuntimeError` if there is no current event loop.
64
65 .. note::
66
67 The :mod:`!asyncio` policy system is deprecated and will be removed
68 in Python 3.16; from there on, this function will return the current
69 running event loop if present else it will return the
70 loop set by :func:`set_event_loop`.
71
72 .. function:: set_event_loop(loop)
73
74 Set *loop* as the current event loop for the current OS thread.
75
76 .. function:: new_event_loop()
77
78 Create and return a new event loop object.
79
80 Note that the behaviour of :func:`get_event_loop`, :func:`set_event_loop`,
81 and :func:`new_event_loop` functions can be altered by
82 :ref:`setting a custom event loop policy <asyncio-policies>`.
83
84
85 .. rubric:: Contents
86
87 This documentation page contains the following sections:
88
89 * The `Event Loop Methods`_ section is the reference documentation of
90 the event loop APIs;
91
92 * The `Callback Handles`_ section documents the :class:`Handle` and
93 :class:`TimerHandle` instances which are returned from scheduling
94 methods such as :meth:`loop.call_soon` and :meth:`loop.call_later`;
95
96 * The `Server Objects`_ section documents types returned from
97 event loop methods like :meth:`loop.create_server`;
98
99 * The `Event Loop Implementations`_ section documents the
100 :class:`SelectorEventLoop` and :class:`ProactorEventLoop` classes;
101
102 * The `Examples`_ section showcases how to work with some event
103 loop APIs.
104
105
106 .. _asyncio-event-loop-methods:
107
108 Event loop methods
109 ==================
110
111 Event loops have **low-level** APIs for the following:
112
113 .. contents::
114 :depth: 1
115 :local:
116
117
118 Running and stopping the loop
119 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
120
121 .. method:: loop.run_until_complete(future)
122
123 Run until the *future* (an instance of :class:`Future`) has
124 completed.
125
126 If the argument is a :ref:`coroutine object <coroutine>` it
127 is implicitly scheduled to run as a :class:`asyncio.Task`.
128
129 Return the Future's result or raise its exception.
130
131 .. method:: loop.run_forever()
132
133 Run the event loop until :meth:`stop` is called.
134
135 If :meth:`stop` is called before :meth:`run_forever` is called,
136 the loop will poll the I/O selector once with a timeout of zero,
137 run all callbacks scheduled in response to I/O events (and
138 those that were already scheduled), and then exit.
139
140 If :meth:`stop` is called while :meth:`run_forever` is running,
141 the loop will run the current batch of callbacks and then exit.
142 Note that new callbacks scheduled by callbacks will not run in this
143 case; instead, they will run the next time :meth:`run_forever` or
144 :meth:`run_until_complete` is called.
145
146 .. method:: loop.stop()
147
148 Stop the event loop.
149
150 .. method:: loop.is_running()
151
152 Return ``True`` if the event loop is currently running.
153
154 .. method:: loop.is_closed()
155
156 Return ``True`` if the event loop was closed.
157
158 .. method:: loop.close()
159
160 Close the event loop.
161
162 The loop must not be running when this function is called.
163 Any pending callbacks will be discarded.
164
165 This method clears all queues and shuts down the executor, but does
166 not wait for the executor to finish.
167
168 This method is idempotent and irreversible. No other methods
169 should be called after the event loop is closed.
170
171 .. method:: loop.shutdown_asyncgens()
172 :async:
173
174 Schedule all currently open :term:`asynchronous generator` objects to
175 close with an :meth:`~agen.aclose` call. After calling this method,
176 the event loop will issue a warning if a new asynchronous generator
177 is iterated. This should be used to reliably finalize all scheduled
178 asynchronous generators.
179
180 Note that there is no need to call this function when
181 :func:`asyncio.run` is used.
182
183 Example::
184
185 try:
186 loop.run_forever()
187 finally:
188 loop.run_until_complete(loop.shutdown_asyncgens())
189 loop.close()
190
191 .. versionadded:: 3.6
192
193 .. method:: loop.shutdown_default_executor(timeout=None)
194 :async:
195
196 Schedule the closure of the default executor and wait for it to join all of
197 the threads in the :class:`~concurrent.futures.ThreadPoolExecutor`.
198 Once this method has been called,
199 using the default executor with :meth:`loop.run_in_executor`
200 will raise a :exc:`RuntimeError`.
201
202 The *timeout* parameter specifies the amount of time
203 (in :class:`float` seconds) the executor will be given to finish joining.
204 With the default, ``None``,
205 the executor is allowed an unlimited amount of time.
206
207 If the *timeout* is reached, a :exc:`RuntimeWarning` is emitted
208 and the default executor is terminated
209 without waiting for its threads to finish joining.
210
211 .. note::
212
213 Do not call this method when using :func:`asyncio.run`,
214 as the latter handles default executor shutdown automatically.
215
216 .. versionadded:: 3.9
217
218 .. versionchanged:: 3.12
219 Added the *timeout* parameter.
220
221 Scheduling callbacks
222 ^^^^^^^^^^^^^^^^^^^^
223
224 .. method:: loop.call_soon(callback, *args, context=None)
225
226 Schedule the *callback* :term:`callback` to be called with
227 *args* arguments at the next iteration of the event loop.
228
229 Return an instance of :class:`asyncio.Handle`,
230 which can be used later to cancel the callback.
231
232 Callbacks are called in the order in which they are registered.
233 Each callback will be called exactly once.
234
235 The optional keyword-only *context* argument specifies a
236 custom :class:`contextvars.Context` for the *callback* to run in.
237 Callbacks use the current context when no *context* is provided.
238
239 Unlike :meth:`call_soon_threadsafe`, this method is not thread-safe.
240
241 .. method:: loop.call_soon_threadsafe(callback, *args, context=None)
242
243 A thread-safe variant of :meth:`call_soon`. When scheduling callbacks from
244 another thread, this function *must* be used, since :meth:`call_soon` is not
245 thread-safe.
246
247 This function is safe to be called from a reentrant context or signal handler,
248 however, it is not safe or fruitful to use the returned handle in such contexts.
249
250 Raises :exc:`RuntimeError` if called on a loop that's been closed.
251 This can happen on a secondary thread when the main application is
252 shutting down.
253
254 See the :ref:`concurrency and multithreading <asyncio-multithreading>`
255 section of the documentation.
256
257 .. versionchanged:: 3.7
258 The *context* keyword-only parameter was added. See :pep:`567`
259 for more details.
260
261 .. _asyncio-pass-keywords:
262
263 .. note::
264
265 Most :mod:`asyncio` scheduling functions don't allow passing
266 keyword arguments. To do that, use :func:`functools.partial`::
267
268 # will schedule "print("Hello", flush=True)"
269 loop.call_soon(
270 functools.partial(print, "Hello", flush=True))
271
272 Using partial objects is usually more convenient than using lambdas,
273 as asyncio can render partial objects better in debug and error
274 messages.
275
276
277 .. _asyncio-delayed-calls:
278
279 Scheduling delayed callbacks
280 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
281
282 Event loop provides mechanisms to schedule callback functions
283 to be called at some point in the future. Event loop uses monotonic
284 clocks to track time.
285
286
287 .. method:: loop.call_later(delay, callback, *args, context=None)
288
289 Schedule *callback* to be called after the given *delay*
290 number of seconds (can be either an int or a float).
291
292 An instance of :class:`asyncio.TimerHandle` is returned which can
293 be used to cancel the callback.
294
295 *callback* will be called exactly once. If two callbacks are
296 scheduled for exactly the same time, the order in which they
297 are called is undefined.
298
299 The optional positional *args* will be passed to the callback when
300 it is called. Use :func:`functools.partial`
301 :ref:`to pass keyword arguments <asyncio-pass-keywords>` to
302 *callback*.
303
304 An optional keyword-only *context* argument allows specifying a
305 custom :class:`contextvars.Context` for the *callback* to run in.
306 The current context is used when no *context* is provided.
307
308 .. note::
309
310 For performance, callbacks scheduled with :meth:`loop.call_later`
311 may run up to one clock-resolution early (see
312 ``time.get_clock_info('monotonic').resolution``).
313
314 .. versionchanged:: 3.7
315 The *context* keyword-only parameter was added. See :pep:`567`
316 for more details.
317
318 .. versionchanged:: 3.8
319 In Python 3.7 and earlier with the default event loop implementation,
320 the *delay* could not exceed one day.
321 This has been fixed in Python 3.8.
322
323 .. method:: loop.call_at(when, callback, *args, context=None)
324
325 Schedule *callback* to be called at the given absolute timestamp
326 *when* (an int or a float), using the same time reference as
327 :meth:`loop.time`.
328
329 This method's behavior is the same as :meth:`call_later`.
330
331 An instance of :class:`asyncio.TimerHandle` is returned which can
332 be used to cancel the callback.
333
334 .. note::
335
336 For performance, callbacks scheduled with :meth:`loop.call_at`
337 may run up to one clock-resolution early (see
338 ``time.get_clock_info('monotonic').resolution``).
339
340 .. versionchanged:: 3.7
341 The *context* keyword-only parameter was added. See :pep:`567`
342 for more details.
343
344 .. versionchanged:: 3.8
345 In Python 3.7 and earlier with the default event loop implementation,
346 the difference between *when* and the current time could not exceed
347 one day. This has been fixed in Python 3.8.
348
349 .. method:: loop.time()
350
351 Return the current time, as a :class:`float` value, according to
352 the event loop's internal monotonic clock.
353
354 .. note::
355 .. versionchanged:: 3.8
356 In Python 3.7 and earlier timeouts (relative *delay* or absolute *when*)
357 should not exceed one day. This has been fixed in Python 3.8.
358
359 .. seealso::
360
361 The :func:`asyncio.sleep` function.
362
363
364 Creating futures and tasks
365 ^^^^^^^^^^^^^^^^^^^^^^^^^^
366
367 .. method:: loop.create_future()
368
369 Create an :class:`asyncio.Future` object attached to the event loop.
370
371 This is the preferred way to create Futures in asyncio. This lets
372 third-party event loops provide alternative implementations of
373 the Future object (with better performance or instrumentation).
374
375 .. versionadded:: 3.5.2
376
377 .. method:: loop.create_task(coro, *, name=None, context=None, eager_start=None, **kwargs)
378
379 Schedule the execution of :ref:`coroutine <coroutine>` *coro*.
380 Return a :class:`Task` object.
381
382 Third-party event loops can use their own subclass of :class:`Task`
383 for interoperability. In this case, the result type is a subclass
384 of :class:`Task`.
385
386 The full function signature is largely the same as that of the
387 :class:`Task` constructor (or factory) - all of the keyword arguments to
388 this function are passed through to that interface.
389
390 If the *name* argument is provided and not ``None``, it is set as
391 the name of the task using :meth:`Task.set_name`.
392
393 An optional keyword-only *context* argument allows specifying a
394 custom :class:`contextvars.Context` for the *coro* to run in.
395 The current context copy is created when no *context* is provided.
396
397 An optional keyword-only *eager_start* argument allows specifying
398 if the task should execute eagerly during the call to create_task,
399 or be scheduled later. If *eager_start* is not passed the mode set
400 by :meth:`loop.set_task_factory` will be used.
401
402 .. versionchanged:: 3.8
403 Added the *name* parameter.
404
405 .. versionchanged:: 3.11
406 Added the *context* parameter.
407
408 .. versionchanged:: 3.13.3
409 Added ``kwargs`` which passes on arbitrary extra parameters, including ``name`` and ``context``.
410
411 .. versionchanged:: 3.13.4
412 Rolled back the change that passes on *name* and *context* (if it is None),
413 while still passing on other arbitrary keyword arguments (to avoid breaking backwards compatibility with 3.13.3).
414
415 .. versionchanged:: 3.14
416 All *kwargs* are now passed on. The *eager_start* parameter works with eager task factories.
417
418 .. method:: loop.set_task_factory(factory)
419
420 Set a task factory that will be used by
421 :meth:`loop.create_task`.
422
423 If *factory* is ``None`` the default task factory will be set.
424 Otherwise, *factory* must be a *callable* with the signature matching
425 ``(loop, coro, **kwargs)``, where *loop* is a reference to the active
426 event loop, and *coro* is a coroutine object. The callable
427 must pass on all *kwargs*, and return a :class:`asyncio.Task`-compatible object.
428
429 .. versionchanged:: 3.13.3
430 Required that all *kwargs* are passed on to :class:`asyncio.Task`.
431
432 .. versionchanged:: 3.13.4
433 *name* is no longer passed to task factories. *context* is no longer passed
434 to task factories if it is ``None``.
435
436 .. versionchanged:: 3.14
437 *name* and *context* are now unconditionally passed on to task factories again.
438
439 .. method:: loop.get_task_factory()
440
441 Return a task factory or ``None`` if the default one is in use.
442
443
444 Opening network connections
445 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
446
447 .. method:: loop.create_connection(protocol_factory, \
448 host=None, port=None, *, ssl=None, \
449 family=0, proto=0, flags=0, sock=None, \
450 local_addr=None, server_hostname=None, \
451 ssl_handshake_timeout=None, \
452 ssl_shutdown_timeout=None, \
453 happy_eyeballs_delay=None, interleave=None, \
454 all_errors=False)
455 :async:
456
457 Open a streaming transport connection to a given
458 address specified by *host* and *port*.
459
460 The socket family can be either :py:const:`~socket.AF_INET` or
461 :py:const:`~socket.AF_INET6` depending on *host* (or the *family*
462 argument, if provided).
463
464 The socket type will be :py:const:`~socket.SOCK_STREAM`.
465
466 *protocol_factory* must be a callable returning an
467 :ref:`asyncio protocol <asyncio-protocol>` implementation.
468
469 This method will try to establish the connection in the background.
470 When successful, it returns a ``(transport, protocol)`` pair.
471
472 The chronological synopsis of the underlying operation is as follows:
473
474 #. The connection is established and a :ref:`transport <asyncio-transport>`
475 is created for it.
476
477 #. *protocol_factory* is called without arguments and is expected to
478 return a :ref:`protocol <asyncio-protocol>` instance.
479
480 #. The protocol instance is coupled with the transport by calling its
481 :meth:`~BaseProtocol.connection_made` method.
482
483 #. A ``(transport, protocol)`` tuple is returned on success.
484
485 The created transport is an implementation-dependent bidirectional
486 stream.
487
488 Other arguments:
489
490 * *ssl*: if given and not false, a SSL/TLS transport is created
491 (by default a plain TCP transport is created). If *ssl* is
492 a :class:`ssl.SSLContext` object, this context is used to create
493 the transport; if *ssl* is :const:`True`, a default context returned
494 from :func:`ssl.create_default_context` is used.
495
496 .. seealso:: :ref:`SSL/TLS security considerations <ssl-security>`
497
498 * *server_hostname* sets or overrides the hostname that the target
499 server's certificate will be matched against. Should only be passed
500 if *ssl* is not ``None``. By default the value of the *host* argument
501 is used. If *host* is empty, there is no default and you must pass a
502 value for *server_hostname*. If *server_hostname* is an empty
503 string, hostname matching is disabled (which is a serious security
504 risk, allowing for potential man-in-the-middle attacks).
505
506 * *family*, *proto*, *flags* are the optional address family, protocol
507 and flags to be passed through to getaddrinfo() for *host* resolution.
508 If given, these should all be integers from the corresponding
509 :mod:`socket` module constants.
510
511 * *happy_eyeballs_delay*, if given, enables Happy Eyeballs for this
512 connection. It should
513 be a floating-point number representing the amount of time in seconds
514 to wait for a connection attempt to complete, before starting the next
515 attempt in parallel. This is the "Connection Attempt Delay" as defined
516 in :rfc:`8305`. A sensible default value recommended by the RFC is ``0.25``
517 (250 milliseconds).
518
519 * *interleave* controls address reordering when a host name resolves to
520 multiple IP addresses.
521 If ``0`` or unspecified, no reordering is done, and addresses are
522 tried in the order returned by :meth:`getaddrinfo`. If a positive integer
523 is specified, the addresses are interleaved by address family, and the
524 given integer is interpreted as "First Address Family Count" as defined
525 in :rfc:`8305`. The default is ``0`` if *happy_eyeballs_delay* is not
526 specified, and ``1`` if it is.
527
528 * *sock*, if given, should be an existing, already connected
529 :class:`socket.socket` object to be used by the transport.
530 If *sock* is given, none of *host*, *port*, *family*, *proto*, *flags*,
531 *happy_eyeballs_delay*, *interleave*
532 and *local_addr* should be specified.
533
534 .. note::
535
536 The *sock* argument transfers ownership of the socket to the
537 transport created. To close the socket, call the transport's
538 :meth:`~asyncio.BaseTransport.close` method.
539
540 * *local_addr*, if given, is a ``(local_host, local_port)`` tuple used
541 to bind the socket locally. The *local_host* and *local_port*
542 are looked up using ``getaddrinfo()``, similarly to *host* and *port*.
543
544 * *ssl_handshake_timeout* is (for a TLS connection) the time in seconds
545 to wait for the TLS handshake to complete before aborting the connection.
546 ``60.0`` seconds if ``None`` (default).
547
548 * *ssl_shutdown_timeout* is the time in seconds to wait for the SSL shutdown
549 to complete before aborting the connection. ``30.0`` seconds if ``None``
550 (default).
551
552 * *all_errors* determines what exceptions are raised when a connection cannot
553 be created. By default, only a single ``Exception`` is raised: the first
554 exception if there is only one or all errors have same message, or a single
555 ``OSError`` with the error messages combined. When ``all_errors`` is ``True``,
556 an ``ExceptionGroup`` will be raised containing all exceptions (even if there
557 is only one).
558
559
560 .. versionchanged:: 3.5
561
562 Added support for SSL/TLS in :class:`ProactorEventLoop`.
563
564 .. versionchanged:: 3.6
565
566 The socket option :ref:`socket.TCP_NODELAY <socket-unix-constants>` is set by default
567 for all TCP connections.
568
569 .. versionchanged:: 3.7
570
571 Added the *ssl_handshake_timeout* parameter.
572
573 .. versionchanged:: 3.8
574
575 Added the *happy_eyeballs_delay* and *interleave* parameters.
576
577 Happy Eyeballs Algorithm: Success with Dual-Stack Hosts.
578 When a server's IPv4 path and protocol are working, but the server's
579 IPv6 path and protocol are not working, a dual-stack client
580 application experiences significant connection delay compared to an
581 IPv4-only client. This is undesirable because it causes the
582 dual-stack client to have a worse user experience. This document
583 specifies requirements for algorithms that reduce this user-visible
584 delay and provides an algorithm.
585
586 For more information: https://datatracker.ietf.org/doc/html/rfc6555
587
588 .. versionchanged:: 3.11
589
590 Added the *ssl_shutdown_timeout* parameter.
591
592 .. versionchanged:: 3.12
593 *all_errors* was added.
594
595 .. seealso::
596
597 The :func:`open_connection` function is a high-level alternative
598 API. It returns a pair of (:class:`StreamReader`, :class:`StreamWriter`)
599 that can be used directly in async/await code.
600
601 .. method:: loop.create_datagram_endpoint(protocol_factory, \
602 local_addr=None, remote_addr=None, *, \
603 family=0, proto=0, flags=0, \
604 reuse_port=None, \
605 allow_broadcast=None, sock=None)
606 :async:
607
608 Create a datagram connection.
609
610 The socket family can be either :py:const:`~socket.AF_INET`,
611 :py:const:`~socket.AF_INET6`, or :py:const:`~socket.AF_UNIX`,
612 depending on *host* (or the *family* argument, if provided).
613
614 The socket type will be :py:const:`~socket.SOCK_DGRAM`.
615
616 *protocol_factory* must be a callable returning a
617 :ref:`protocol <asyncio-protocol>` implementation.
618
619 A tuple of ``(transport, protocol)`` is returned on success.
620
621 Other arguments:
622
623 * *local_addr*, if given, is a ``(local_host, local_port)`` tuple used
624 to bind the socket locally. The *local_host* and *local_port*
625 are looked up using :meth:`getaddrinfo`.
626
627 .. note::
628
629 On Windows, when using the proactor event loop with ``local_addr=None``,
630 an :exc:`OSError` with :attr:`!errno.WSAEINVAL` will be raised
631 when running it.
632
633 * *remote_addr*, if given, is a ``(remote_host, remote_port)`` tuple used
634 to connect the socket to a remote address. The *remote_host* and
635 *remote_port* are looked up using :meth:`getaddrinfo`.
636
637 * *family*, *proto*, *flags* are the optional address family, protocol
638 and flags to be passed through to :meth:`getaddrinfo` for *host*
639 resolution. If given, these should all be integers from the
640 corresponding :mod:`socket` module constants.
641
642 * *reuse_port* tells the kernel to allow this endpoint to be bound to the
643 same port as other existing endpoints are bound to, so long as they all
644 set this flag when being created. This option is not supported on Windows
645 and some Unixes. If the :ref:`socket.SO_REUSEPORT <socket-unix-constants>` constant is not
646 defined then this capability is unsupported.
647
648 * *allow_broadcast* tells the kernel to allow this endpoint to send
649 messages to the broadcast address.
650
651 * *sock* can optionally be specified in order to use a preexisting,
652 already connected, :class:`socket.socket` object to be used by the
653 transport. If specified, *local_addr* and *remote_addr* should be omitted
654 (must be :const:`None`).
655
656 .. note::
657
658 The *sock* argument transfers ownership of the socket to the
659 transport created. To close the socket, call the transport's
660 :meth:`~asyncio.BaseTransport.close` method.
661
662 See :ref:`UDP echo client protocol <asyncio-udp-echo-client-protocol>` and
663 :ref:`UDP echo server protocol <asyncio-udp-echo-server-protocol>` examples.
664
665 .. versionchanged:: 3.4.4
666 The *family*, *proto*, *flags*, *reuse_address*, *reuse_port*,
667 *allow_broadcast*, and *sock* parameters were added.
668
669 .. versionchanged:: 3.8
670 Added support for Windows.
671
672 .. versionchanged:: 3.8.1
673 The *reuse_address* parameter is no longer supported, as using
674 :ref:`socket.SO_REUSEADDR <socket-unix-constants>`
675 poses a significant security concern for
676 UDP. Explicitly passing ``reuse_address=True`` will raise an exception.
677
678 When multiple processes with differing UIDs assign sockets to an
679 identical UDP socket address with ``SO_REUSEADDR``, incoming packets can
680 become randomly distributed among the sockets.
681
682 For supported platforms, *reuse_port* can be used as a replacement for
683 similar functionality. With *reuse_port*,
684 :ref:`socket.SO_REUSEPORT <socket-unix-constants>`
685 is used instead, which specifically
686 prevents processes with differing UIDs from assigning sockets to the same
687 socket address.
688
689 .. versionchanged:: 3.11
690 The *reuse_address* parameter, disabled since Python 3.8.1,
691 3.7.6 and 3.6.10, has been entirely removed.
692
693 .. method:: loop.create_unix_connection(protocol_factory, \
694 path=None, *, ssl=None, sock=None, \
695 server_hostname=None, ssl_handshake_timeout=None, \
696 ssl_shutdown_timeout=None)
697 :async:
698
699 Create a Unix connection.
700
701 The socket family will be :py:const:`~socket.AF_UNIX`; socket
702 type will be :py:const:`~socket.SOCK_STREAM`.
703
704 A tuple of ``(transport, protocol)`` is returned on success.
705
706 *path* is the name of a Unix domain socket and is required,
707 unless a *sock* parameter is specified. Abstract Unix sockets,
708 :class:`str`, :class:`bytes`, and :class:`~pathlib.Path` paths are
709 supported.
710
711 See the documentation of the :meth:`loop.create_connection` method
712 for information about arguments to this method.
713
714 .. availability:: Unix.
715
716 .. versionchanged:: 3.7
717 Added the *ssl_handshake_timeout* parameter.
718 The *path* parameter can now be a :term:`path-like object`.
719
720 .. versionchanged:: 3.11
721
722 Added the *ssl_shutdown_timeout* parameter.
723
724
725 Creating network servers
726 ^^^^^^^^^^^^^^^^^^^^^^^^
727
728 .. _loop_create_server:
729
730 .. method:: loop.create_server(protocol_factory, \
731 host=None, port=None, *, \
732 family=socket.AF_UNSPEC, \
733 flags=socket.AI_PASSIVE, \
734 sock=None, backlog=100, ssl=None, \
735 reuse_address=None, reuse_port=None, \
736 keep_alive=None, \
737 ssl_handshake_timeout=None, \
738 ssl_shutdown_timeout=None, \
739 start_serving=True)
740 :async:
741
742 Create a TCP server (socket type :const:`~socket.SOCK_STREAM`) listening
743 on *port* of the *host* address.
744
745 Returns a :class:`Server` object.
746
747 Arguments:
748
749 * *protocol_factory* must be a callable returning a
750 :ref:`protocol <asyncio-protocol>` implementation.
751
752 * The *host* parameter can be set to several types which determine where
753 the server would be listening:
754
755 - If *host* is a string, the TCP server is bound to a single network
756 interface specified by *host*.
757
758 - If *host* is a sequence of strings, the TCP server is bound to all
759 network interfaces specified by the sequence.
760
761 - If *host* is an empty string or ``None``, all interfaces are
762 assumed and a list of multiple sockets will be returned (most likely
763 one for IPv4 and another one for IPv6).
764
765 * The *port* parameter can be set to specify which port the server should
766 listen on. If ``0`` or ``None`` (the default), a random unused port will
767 be selected (note that if *host* resolves to multiple network interfaces,
768 a different random port will be selected for each interface).
769
770 * *family* can be set to either :const:`socket.AF_INET` or
771 :const:`~socket.AF_INET6` to force the socket to use IPv4 or IPv6.
772 If not set, the *family* will be determined from host name
773 (defaults to :const:`~socket.AF_UNSPEC`).
774
775 * *flags* is a bitmask for :meth:`getaddrinfo`.
776
777 * *sock* can optionally be specified in order to use a preexisting
778 socket object. If specified, *host* and *port* must not be specified.
779
780 .. note::
781
782 The *sock* argument transfers ownership of the socket to the
783 server created. To close the socket, call the server's
784 :meth:`~asyncio.Server.close` method.
785
786 * *backlog* is the maximum number of queued connections passed to
787 :meth:`~socket.socket.listen` (defaults to 100).
788
789 * *ssl* can be set to an :class:`~ssl.SSLContext` instance to enable
790 TLS over the accepted connections.
791
792 * *reuse_address* tells the kernel to reuse a local socket in
793 ``TIME_WAIT`` state, without waiting for its natural timeout to
794 expire. If not specified will automatically be set to ``True`` on
795 Unix.
796
797 * *reuse_port* tells the kernel to allow this endpoint to be bound to the
798 same port as other existing endpoints are bound to, so long as they all
799 set this flag when being created. This option is not supported on
800 Windows.
801
802 * *keep_alive* set to ``True`` keeps connections active by enabling the
803 periodic transmission of messages.
804
805 .. versionchanged:: 3.13
806
807 Added the *keep_alive* parameter.
808
809 * *ssl_handshake_timeout* is (for a TLS server) the time in seconds to wait
810 for the TLS handshake to complete before aborting the connection.
811 ``60.0`` seconds if ``None`` (default).
812
813 * *ssl_shutdown_timeout* is the time in seconds to wait for the SSL shutdown
814 to complete before aborting the connection. ``30.0`` seconds if ``None``
815 (default).
816
817 * *start_serving* set to ``True`` (the default) causes the created server
818 to start accepting connections immediately. When set to ``False``,
819 the user should await on :meth:`Server.start_serving` or
820 :meth:`Server.serve_forever` to make the server to start accepting
821 connections.
822
823 .. versionchanged:: 3.5
824
825 Added support for SSL/TLS in :class:`ProactorEventLoop`.
826
827 .. versionchanged:: 3.5.1
828
829 The *host* parameter can be a sequence of strings.
830
831 .. versionchanged:: 3.6
832
833 Added *ssl_handshake_timeout* and *start_serving* parameters.
834 The socket option :ref:`socket.TCP_NODELAY <socket-unix-constants>` is set by default
835 for all TCP connections.
836
837 .. versionchanged:: 3.11
838
839 Added the *ssl_shutdown_timeout* parameter.
840
841 .. seealso::
842
843 The :func:`start_server` function is a higher-level alternative API
844 that returns a pair of :class:`StreamReader` and :class:`StreamWriter`
845 that can be used in an async/await code.
846
847
848 .. method:: loop.create_unix_server(protocol_factory, path=None, \
849 *, sock=None, backlog=100, ssl=None, \
850 ssl_handshake_timeout=None, \
851 ssl_shutdown_timeout=None, \
852 start_serving=True, cleanup_socket=True)
853 :async:
854
855 Similar to :meth:`loop.create_server` but works with the
856 :py:const:`~socket.AF_UNIX` socket family.
857
858 *path* is the name of a Unix domain socket, and is required,
859 unless a *sock* argument is provided. Abstract Unix sockets,
860 :class:`str`, :class:`bytes`, and :class:`~pathlib.Path` paths
861 are supported.
862
863 If *cleanup_socket* is true then the Unix socket will automatically
864 be removed from the filesystem when the server is closed, unless the
865 socket has been replaced after the server has been created.
866
867 See the documentation of the :meth:`loop.create_server` method
868 for information about arguments to this method.
869
870 .. availability:: Unix.
871
872 .. versionchanged:: 3.7
873
874 Added the *ssl_handshake_timeout* and *start_serving* parameters.
875 The *path* parameter can now be a :class:`~pathlib.Path` object.
876
877 .. versionchanged:: 3.11
878
879 Added the *ssl_shutdown_timeout* parameter.
880
881 .. versionchanged:: 3.13
882
883 Added the *cleanup_socket* parameter.
884
885
886 .. method:: loop.connect_accepted_socket(protocol_factory, \
887 sock, *, ssl=None, ssl_handshake_timeout=None, \
888 ssl_shutdown_timeout=None)
889 :async:
890
891 Wrap an already accepted connection into a transport/protocol pair.
892
893 This method can be used by servers that accept connections outside
894 of asyncio but that use asyncio to handle them.
895
896 Parameters:
897
898 * *protocol_factory* must be a callable returning a
899 :ref:`protocol <asyncio-protocol>` implementation.
900
901 * *sock* is a preexisting socket object returned from
902 :meth:`socket.accept <socket.socket.accept>`.
903
904 .. note::
905
906 The *sock* argument transfers ownership of the socket to the
907 transport created. To close the socket, call the transport's
908 :meth:`~asyncio.BaseTransport.close` method.
909
910 * *ssl* can be set to an :class:`~ssl.SSLContext` to enable SSL over
911 the accepted connections.
912
913 * *ssl_handshake_timeout* is (for an SSL connection) the time in seconds to
914 wait for the SSL handshake to complete before aborting the connection.
915 ``60.0`` seconds if ``None`` (default).
916
917 * *ssl_shutdown_timeout* is the time in seconds to wait for the SSL shutdown
918 to complete before aborting the connection. ``30.0`` seconds if ``None``
919 (default).
920
921 Returns a ``(transport, protocol)`` pair.
922
923 .. versionadded:: 3.5.3
924
925 .. versionchanged:: 3.7
926
927 Added the *ssl_handshake_timeout* parameter.
928
929 .. versionchanged:: 3.11
930
931 Added the *ssl_shutdown_timeout* parameter.
932
933
934 Transferring files
935 ^^^^^^^^^^^^^^^^^^
936
937 .. method:: loop.sendfile(transport, file, \
938 offset=0, count=None, *, fallback=True)
939 :async:
940
941 Send a *file* over a *transport*. Return the total number of bytes
942 sent.
943
944 The method uses high-performance :meth:`os.sendfile` if available.
945
946 *file* must be a regular file object opened in binary mode.
947
948 *offset* tells from where to start reading the file. If specified,
949 *count* is the total number of bytes to transmit as opposed to
950 sending the file until EOF is reached. File position is always updated,
951 even when this method raises an error, and
952 :meth:`file.tell() <io.IOBase.tell>` can be used to obtain the actual
953 number of bytes sent.
954
955 *fallback* set to ``True`` makes asyncio to manually read and send
956 the file when the platform does not support the sendfile system call
957 (e.g. Windows or SSL socket on Unix).
958
959 Raise :exc:`SendfileNotAvailableError` if the system does not support
960 the *sendfile* syscall and *fallback* is ``False``.
961
962 .. versionadded:: 3.7
963
964
965 TLS upgrade
966 ^^^^^^^^^^^
967
968 .. method:: loop.start_tls(transport, protocol, \
969 sslcontext, *, server_side=False, \
970 server_hostname=None, ssl_handshake_timeout=None, \
971 ssl_shutdown_timeout=None)
972 :async:
973
974 Upgrade an existing transport-based connection to TLS.
975
976 Create a TLS coder/decoder instance and insert it between the *transport*
977 and the *protocol*. The coder/decoder implements both *transport*-facing
978 protocol and *protocol*-facing transport.
979
980 Return the created two-interface instance. After *await*, the *protocol*
981 must stop using the original *transport* and communicate with the returned
982 object only because the coder caches *protocol*-side data and sporadically
983 exchanges extra TLS session packets with *transport*.
984
985 In some situations (e.g. when the passed transport is already closing) this
986 may return ``None``.
987
988 Parameters:
989
990 * *transport* and *protocol* instances that methods like
991 :meth:`~loop.create_server` and
992 :meth:`~loop.create_connection` return.
993
994 * *sslcontext*: a configured instance of :class:`~ssl.SSLContext`.
995
996 * *server_side* pass ``True`` when a server-side connection is being
997 upgraded (like the one created by :meth:`~loop.create_server`).
998
999 * *server_hostname*: sets or overrides the host name that the target
1000 server's certificate will be matched against.
1001
1002 * *ssl_handshake_timeout* is (for a TLS connection) the time in seconds to
1003 wait for the TLS handshake to complete before aborting the connection.
1004 ``60.0`` seconds if ``None`` (default).
1005
1006 * *ssl_shutdown_timeout* is the time in seconds to wait for the SSL shutdown
1007 to complete before aborting the connection. ``30.0`` seconds if ``None``
1008 (default).
1009
1010 .. versionadded:: 3.7
1011
1012 .. versionchanged:: 3.11
1013
1014 Added the *ssl_shutdown_timeout* parameter.
1015
1016
1017
1018 Watching file descriptors
1019 ^^^^^^^^^^^^^^^^^^^^^^^^^
1020
1021 .. method:: loop.add_reader(fd, callback, *args)
1022
1023 Start monitoring the *fd* file descriptor for read availability and
1024 invoke *callback* with the specified arguments once *fd* is available for
1025 reading.
1026
1027 Any preexisting callback registered for *fd* is cancelled and replaced by
1028 *callback*.
1029
1030 .. method:: loop.remove_reader(fd)
1031
1032 Stop monitoring the *fd* file descriptor for read availability. Returns
1033 ``True`` if *fd* was previously being monitored for reads.
1034
1035 .. method:: loop.add_writer(fd, callback, *args)
1036
1037 Start monitoring the *fd* file descriptor for write availability and
1038 invoke *callback* with the specified arguments *args* once *fd* is
1039 available for writing.
1040
1041 Any preexisting callback registered for *fd* is cancelled and replaced by
1042 *callback*.
1043
1044 Use :func:`functools.partial` :ref:`to pass keyword arguments
1045 <asyncio-pass-keywords>` to *callback*.
1046
1047 .. method:: loop.remove_writer(fd)
1048
1049 Stop monitoring the *fd* file descriptor for write availability. Returns
1050 ``True`` if *fd* was previously being monitored for writes.
1051
1052 See also :ref:`Platform Support <asyncio-platform-support>` section
1053 for some limitations of these methods.
1054
1055
1056 Working with socket objects directly
1057 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1058
1059 In general, protocol implementations that use transport-based APIs
1060 such as :meth:`loop.create_connection` and :meth:`loop.create_server`
1061 are faster than implementations that work with sockets directly.
1062 However, there are some use cases when performance is not critical, and
1063 working with :class:`~socket.socket` objects directly is more
1064 convenient.
1065
1066 .. method:: loop.sock_recv(sock, nbytes)
1067 :async:
1068
1069 Receive up to *nbytes* from *sock*. Asynchronous version of
1070 :meth:`socket.recv() <socket.socket.recv>`.
1071
1072 Return the received data as a bytes object.
1073
1074 *sock* must be a non-blocking socket.
1075
1076 .. versionchanged:: 3.7
1077 Even though this method was always documented as a coroutine
1078 method, releases before Python 3.7 returned a :class:`Future`.
1079 Since Python 3.7 this is an ``async def`` method.
1080
1081 .. method:: loop.sock_recv_into(sock, buf)
1082 :async:
1083
1084 Receive data from *sock* into the *buf* buffer. Modeled after the blocking
1085 :meth:`socket.recv_into() <socket.socket.recv_into>` method.
1086
1087 Return the number of bytes written to the buffer.
1088
1089 *sock* must be a non-blocking socket.
1090
1091 .. versionadded:: 3.7
1092
1093 .. method:: loop.sock_recvfrom(sock, bufsize)
1094 :async:
1095
1096 Receive a datagram of up to *bufsize* from *sock*. Asynchronous version of
1097 :meth:`socket.recvfrom() <socket.socket.recvfrom>`.
1098
1099 Return a tuple of (received data, remote address).
1100
1101 *sock* must be a non-blocking socket.
1102
1103 .. versionadded:: 3.11
1104
1105 .. method:: loop.sock_recvfrom_into(sock, buf, nbytes=0)
1106 :async:
1107
1108 Receive a datagram of up to *nbytes* from *sock* into *buf*.
1109 Asynchronous version of
1110 :meth:`socket.recvfrom_into() <socket.socket.recvfrom_into>`.
1111
1112 Return a tuple of (number of bytes received, remote address).
1113
1114 *sock* must be a non-blocking socket.
1115
1116 .. versionadded:: 3.11
1117
1118 .. method:: loop.sock_sendall(sock, data)
1119 :async:
1120
1121 Send *data* to the *sock* socket. Asynchronous version of
1122 :meth:`socket.sendall() <socket.socket.sendall>`.
1123
1124 This method continues to send to the socket until either all data
1125 in *data* has been sent or an error occurs. ``None`` is returned
1126 on success. On error, an exception is raised. Additionally, there is no way
1127 to determine how much data, if any, was successfully processed by the
1128 receiving end of the connection.
1129
1130 *sock* must be a non-blocking socket.
1131
1132 .. versionchanged:: 3.7
1133 Even though the method was always documented as a coroutine
1134 method, before Python 3.7 it returned a :class:`Future`.
1135 Since Python 3.7, this is an ``async def`` method.
1136
1137 .. method:: loop.sock_sendto(sock, data, address)
1138 :async:
1139
1140 Send a datagram from *sock* to *address*.
1141 Asynchronous version of
1142 :meth:`socket.sendto() <socket.socket.sendto>`.
1143
1144 Return the number of bytes sent.
1145
1146 *sock* must be a non-blocking socket.
1147
1148 .. versionadded:: 3.11
1149
1150 .. method:: loop.sock_connect(sock, address)
1151 :async:
1152
1153 Connect *sock* to a remote socket at *address*.
1154
1155 Asynchronous version of :meth:`socket.connect() <socket.socket.connect>`.
1156
1157 *sock* must be a non-blocking socket.
1158
1159 .. versionchanged:: 3.5.2
1160 ``address`` no longer needs to be resolved. ``sock_connect``
1161 will try to check if the *address* is already resolved by calling
1162 :func:`socket.inet_pton`. If not,
1163 :meth:`loop.getaddrinfo` will be used to resolve the
1164 *address*.
1165
1166 .. seealso::
1167
1168 :meth:`loop.create_connection`
1169 and :func:`asyncio.open_connection() <open_connection>`.
1170
1171
1172 .. method:: loop.sock_accept(sock)
1173 :async:
1174
1175 Accept a connection. Modeled after the blocking
1176 :meth:`socket.accept() <socket.socket.accept>` method.
1177
1178 The socket must be bound to an address and listening
1179 for connections. The return value is a pair ``(conn, address)`` where *conn*
1180 is a *new* socket object usable to send and receive data on the connection,
1181 and *address* is the address bound to the socket on the other end of the
1182 connection.
1183
1184 *sock* must be a non-blocking socket.
1185
1186 .. versionchanged:: 3.7
1187 Even though the method was always documented as a coroutine
1188 method, before Python 3.7 it returned a :class:`Future`.
1189 Since Python 3.7, this is an ``async def`` method.
1190
1191 .. seealso::
1192
1193 :meth:`loop.create_server` and :func:`start_server`.
1194
1195 .. method:: loop.sock_sendfile(sock, file, offset=0, count=None, \
1196 *, fallback=True)
1197 :async:
1198
1199 Send a file using high-performance :mod:`os.sendfile` if possible.
1200 Return the total number of bytes sent.
1201
1202 Asynchronous version of :meth:`socket.sendfile() <socket.socket.sendfile>`.
1203
1204 *sock* must be a non-blocking :const:`socket.SOCK_STREAM`
1205 :class:`~socket.socket`.
1206
1207 *file* must be a regular file object open in binary mode.
1208
1209 *offset* tells from where to start reading the file. If specified,
1210 *count* is the total number of bytes to transmit as opposed to
1211 sending the file until EOF is reached. File position is always updated,
1212 even when this method raises an error, and
1213 :meth:`file.tell() <io.IOBase.tell>` can be used to obtain the actual
1214 number of bytes sent.
1215
1216 *fallback*, when set to ``True``, makes asyncio manually read and send
1217 the file when the platform does not support the sendfile syscall
1218 (e.g. Windows or SSL socket on Unix).
1219
1220 Raise :exc:`SendfileNotAvailableError` if the system does not support
1221 *sendfile* syscall and *fallback* is ``False``.
1222
1223 *sock* must be a non-blocking socket.
1224
1225 .. versionadded:: 3.7
1226
1227
1228 DNS
1229 ^^^
1230
1231 .. method:: loop.getaddrinfo(host, port, *, family=0, \
1232 type=0, proto=0, flags=0)
1233 :async:
1234
1235 Asynchronous version of :meth:`socket.getaddrinfo`.
1236
1237 .. method:: loop.getnameinfo(sockaddr, flags=0)
1238 :async:
1239
1240 Asynchronous version of :meth:`socket.getnameinfo`.
1241
1242 .. note::
1243 Both *getaddrinfo* and *getnameinfo* internally utilize their synchronous
1244 versions through the loop's default thread pool executor.
1245 When this executor is saturated, these methods may experience delays,
1246 which higher-level networking libraries may report as increased timeouts.
1247 To mitigate this, consider using a custom executor for other user tasks,
1248 or setting a default executor with a larger number of workers.
1249
1250 .. versionchanged:: 3.7
1251 Both *getaddrinfo* and *getnameinfo* methods were always documented
1252 to return a coroutine, but prior to Python 3.7 they were, in fact,
1253 returning :class:`asyncio.Future` objects. Starting with Python 3.7
1254 both methods are coroutines.
1255
1256
1257 Working with pipes
1258 ^^^^^^^^^^^^^^^^^^
1259
1260 .. method:: loop.connect_read_pipe(protocol_factory, pipe)
1261 :async:
1262
1263 Register the read end of *pipe* in the event loop.
1264
1265 *protocol_factory* must be a callable returning an
1266 :ref:`asyncio protocol <asyncio-protocol>` implementation.
1267
1268 *pipe* is a :term:`file-like object <file object>`.
1269
1270 Return pair ``(transport, protocol)``, where *transport* supports
1271 the :class:`ReadTransport` interface and *protocol* is an object
1272 instantiated by the *protocol_factory*.
1273
1274 With :class:`SelectorEventLoop` event loop, the *pipe* is set to
1275 non-blocking mode.
1276
1277 .. method:: loop.connect_write_pipe(protocol_factory, pipe)
1278 :async:
1279
1280 Register the write end of *pipe* in the event loop.
1281
1282 *protocol_factory* must be a callable returning an
1283 :ref:`asyncio protocol <asyncio-protocol>` implementation.
1284
1285 *pipe* is :term:`file-like object <file object>`.
1286
1287 Return pair ``(transport, protocol)``, where *transport* supports
1288 :class:`WriteTransport` interface and *protocol* is an object
1289 instantiated by the *protocol_factory*.
1290
1291 With :class:`SelectorEventLoop` event loop, the *pipe* is set to
1292 non-blocking mode.
1293
1294 .. note::
1295
1296 :class:`SelectorEventLoop` does not support the above methods on
1297 Windows. Use :class:`ProactorEventLoop` instead for Windows.
1298
1299 .. seealso::
1300
1301 The :meth:`loop.subprocess_exec` and
1302 :meth:`loop.subprocess_shell` methods.
1303
1304
1305 Unix signals
1306 ^^^^^^^^^^^^
1307
1308 .. _loop_add_signal_handler:
1309
1310 .. method:: loop.add_signal_handler(signum, callback, *args)
1311
1312 Set *callback* as the handler for the *signum* signal,
1313 passing *args* as positional arguments.
1314
1315 The callback will be invoked by *loop*, along with other queued callbacks
1316 and runnable coroutines of that event loop. Unlike signal handlers
1317 registered using :func:`signal.signal`, a callback registered with this
1318 function is allowed to interact with the event loop.
1319
1320 Raise :exc:`ValueError` if the signal number is invalid or uncatchable.
1321 Raise :exc:`RuntimeError` if there is a problem setting up the handler.
1322
1323 Use :func:`functools.partial` :ref:`to pass keyword arguments
1324 <asyncio-pass-keywords>` to *callback*.
1325
1326 Like :func:`signal.signal`, this function must be invoked in the main
1327 thread.
1328
1329 .. method:: loop.remove_signal_handler(sig)
1330
1331 Remove the handler for the *sig* signal.
1332
1333 Return ``True`` if the signal handler was removed, or ``False`` if
1334 no handler was set for the given signal.
1335
1336 .. availability:: Unix.
1337
1338 .. seealso::
1339
1340 The :mod:`signal` module.
1341
1342
1343 Executing code in thread or process pools
1344 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1345
1346 .. awaitablemethod:: loop.run_in_executor(executor, func, *args)
1347
1348 Arrange for *func* to be called in the specified executor
1349 passing *args* as positional arguments.
1350
1351 The *executor* argument should be an :class:`concurrent.futures.Executor`
1352 instance. The default executor is used if *executor* is ``None``.
1353 The default executor can be set by :meth:`loop.set_default_executor`,
1354 otherwise, a :class:`concurrent.futures.ThreadPoolExecutor` will be
1355 lazy-initialized and used by :func:`run_in_executor` if needed.
1356
1357 Example::
1358
1359 import asyncio
1360 import concurrent.futures
1361
1362 def blocking_io():
1363 # File operations (such as logging) can block the
1364 # event loop: run them in a thread pool.
1365 with open('/dev/urandom', 'rb') as f:
1366 return f.read(100)
1367
1368 def cpu_bound():
1369 # CPU-bound operations will block the event loop:
1370 # in general it is preferable to run them in a
1371 # process pool.
1372 return sum(i * i for i in range(10 ** 7))
1373
1374 async def main():
1375 loop = asyncio.get_running_loop()
1376
1377 ## Options:
1378
1379 # 1. Run in the default loop's executor:
1380 result = await loop.run_in_executor(
1381 None, blocking_io)
1382 print('default thread pool', result)
1383
1384 # 2. Run in a custom thread pool:
1385 with concurrent.futures.ThreadPoolExecutor() as pool:
1386 result = await loop.run_in_executor(
1387 pool, blocking_io)
1388 print('custom thread pool', result)
1389
1390 # 3. Run in a custom process pool:
1391 with concurrent.futures.ProcessPoolExecutor() as pool:
1392 result = await loop.run_in_executor(
1393 pool, cpu_bound)
1394 print('custom process pool', result)
1395
1396 # 4. Run in a custom interpreter pool:
1397 with concurrent.futures.InterpreterPoolExecutor() as pool:
1398 result = await loop.run_in_executor(
1399 pool, cpu_bound)
1400 print('custom interpreter pool', result)
1401
1402 if __name__ == '__main__':
1403 asyncio.run(main())
1404
1405 Note that the entry point guard (``if __name__ == '__main__'``)
1406 is required for option 3 due to the peculiarities of :mod:`multiprocessing`,
1407 which is used by :class:`~concurrent.futures.ProcessPoolExecutor`.
1408 See :ref:`Safe importing of main module <multiprocessing-safe-main-import>`.
1409
1410 This method returns a :class:`asyncio.Future` object.
1411
1412 Use :func:`functools.partial` :ref:`to pass keyword arguments
1413 <asyncio-pass-keywords>` to *func*.
1414
1415 .. versionchanged:: 3.5.3
1416 :meth:`loop.run_in_executor` no longer configures the
1417 ``max_workers`` of the thread pool executor it creates, instead
1418 leaving it up to the thread pool executor
1419 (:class:`~concurrent.futures.ThreadPoolExecutor`) to set the
1420 default.
1421
1422 .. method:: loop.set_default_executor(executor)
1423
1424 Set *executor* as the default executor used by :meth:`run_in_executor`.
1425 *executor* must be an instance of
1426 :class:`~concurrent.futures.ThreadPoolExecutor`, which includes
1427 :class:`~concurrent.futures.InterpreterPoolExecutor`.
1428
1429 .. versionchanged:: 3.11
1430 *executor* must be an instance of
1431 :class:`~concurrent.futures.ThreadPoolExecutor`.
1432
1433
1434 Error handling API
1435 ^^^^^^^^^^^^^^^^^^
1436
1437 Allows customizing how exceptions are handled in the event loop.
1438
1439 .. method:: loop.set_exception_handler(handler)
1440
1441 Set *handler* as the new event loop exception handler.
1442
1443 If *handler* is ``None``, the default exception handler will
1444 be set. Otherwise, *handler* must be a callable with the signature
1445 matching ``(loop, context)``, where ``loop``
1446 is a reference to the active event loop, and ``context``
1447 is a ``dict`` object containing the details of the exception
1448 (see :meth:`call_exception_handler` documentation for details
1449 about context).
1450
1451 If the handler is called on behalf of a :class:`~asyncio.Task` or
1452 :class:`~asyncio.Handle`, it is run in the
1453 :class:`contextvars.Context` of that task or callback handle.
1454
1455 .. versionchanged:: 3.12
1456
1457 The handler may be called in the :class:`~contextvars.Context`
1458 of the task or handle where the exception originated.
1459
1460 .. method:: loop.get_exception_handler()
1461
1462 Return the current exception handler, or ``None`` if no custom
1463 exception handler was set.
1464
1465 .. versionadded:: 3.5.2
1466
1467 .. method:: loop.default_exception_handler(context)
1468
1469 Default exception handler.
1470
1471 This is called when an exception occurs and no exception
1472 handler is set. This can be called by a custom exception
1473 handler that wants to defer to the default handler behavior.
1474
1475 *context* parameter has the same meaning as in
1476 :meth:`call_exception_handler`.
1477
1478 .. method:: loop.call_exception_handler(context)
1479
1480 Call the current event loop exception handler.
1481
1482 *context* is a ``dict`` object containing the following keys
1483 (new keys may be introduced in future Python versions):
1484
1485 * 'message': Error message;
1486 * 'exception' (optional): Exception object;
1487 * 'future' (optional): :class:`asyncio.Future` instance;
1488 * 'task' (optional): :class:`asyncio.Task` instance;
1489 * 'handle' (optional): :class:`asyncio.Handle` instance;
1490 * 'protocol' (optional): :ref:`Protocol <asyncio-protocol>` instance;
1491 * 'transport' (optional): :ref:`Transport <asyncio-transport>` instance;
1492 * 'socket' (optional): :class:`socket.socket` instance;
1493 * 'source_traceback' (optional): Traceback of the source;
1494 * 'handle_traceback' (optional): Traceback of the handle;
1495 * 'asyncgen' (optional): Asynchronous generator that caused
1496 the exception.
1497
1498 .. note::
1499
1500 This method should not be overloaded in subclassed
1501 event loops. For custom exception handling, use
1502 the :meth:`set_exception_handler` method.
1503
1504 Enabling debug mode
1505 ^^^^^^^^^^^^^^^^^^^
1506
1507 .. method:: loop.get_debug()
1508
1509 Get the debug mode (:class:`bool`) of the event loop.
1510
1511 The default value is ``True`` if the environment variable
1512 :envvar:`PYTHONASYNCIODEBUG` is set to a non-empty string, ``False``
1513 otherwise.
1514
1515 .. method:: loop.set_debug(enabled: bool)
1516
1517 Set the debug mode of the event loop.
1518
1519 .. versionchanged:: 3.7
1520
1521 The new :ref:`Python Development Mode <devmode>` can now also be used
1522 to enable the debug mode.
1523
1524 .. attribute:: loop.slow_callback_duration
1525
1526 This attribute can be used to set the
1527 minimum execution duration in seconds that is considered "slow".
1528 When debug mode is enabled, "slow" callbacks are logged.
1529
1530 Default value is 100 milliseconds.
1531
1532 .. seealso::
1533
1534 The :ref:`debug mode of asyncio <asyncio-debug-mode>`.
1535
1536
1537 Running subprocesses
1538 ^^^^^^^^^^^^^^^^^^^^
1539
1540 Methods described in this subsections are low-level. In regular
1541 async/await code consider using the high-level
1542 :func:`asyncio.create_subprocess_shell` and
1543 :func:`asyncio.create_subprocess_exec` convenience functions instead.
1544
1545 .. note::
1546
1547 On Windows, the default event loop :class:`ProactorEventLoop` supports
1548 subprocesses, whereas :class:`SelectorEventLoop` does not. See
1549 :ref:`Subprocess Support on Windows <asyncio-windows-subprocess>` for
1550 details.
1551
1552 .. _loop_subprocess_exec:
1553
1554 .. method:: loop.subprocess_exec(protocol_factory, *args, \
1555 stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
1556 stderr=subprocess.PIPE, **kwargs)
1557 :async:
1558
1559 Create a subprocess from one or more string arguments specified by
1560 *args*.
1561
1562 *args* must be a list of strings represented by:
1563
1564 * :class:`str`;
1565 * or :class:`bytes`, encoded to the
1566 :ref:`filesystem encoding <filesystem-encoding>`.
1567
1568 The first string specifies the program executable,
1569 and the remaining strings specify the arguments. Together, string
1570 arguments form the ``argv`` of the program.
1571
1572 This is similar to the standard library :class:`subprocess.Popen`
1573 class called with ``shell=False`` and the list of strings passed as
1574 the first argument; however, where :class:`~subprocess.Popen` takes
1575 a single argument which is list of strings, *subprocess_exec*
1576 takes multiple string arguments.
1577
1578 The *protocol_factory* must be a callable returning a subclass of the
1579 :class:`asyncio.SubprocessProtocol` class.
1580
1581 Other parameters:
1582
1583 * *stdin* can be any of these:
1584
1585 * a file-like object
1586 * an existing file descriptor (a positive integer), for example those created with :meth:`os.pipe`
1587 * the :const:`subprocess.PIPE` constant (default) which will create a new
1588 pipe and connect it,
1589 * the value ``None`` which will make the subprocess inherit the file
1590 descriptor from this process
1591 * the :const:`subprocess.DEVNULL` constant which indicates that the
1592 special :data:`os.devnull` file will be used
1593
1594 * *stdout* can be any of these:
1595
1596 * a file-like object
1597 * the :const:`subprocess.PIPE` constant (default) which will create a new
1598 pipe and connect it,
1599 * the value ``None`` which will make the subprocess inherit the file
1600 descriptor from this process
1601 * the :const:`subprocess.DEVNULL` constant which indicates that the
1602 special :data:`os.devnull` file will be used
1603
1604 * *stderr* can be any of these:
1605
1606 * a file-like object
1607 * the :const:`subprocess.PIPE` constant (default) which will create a new
1608 pipe and connect it,
1609 * the value ``None`` which will make the subprocess inherit the file
1610 descriptor from this process
1611 * the :const:`subprocess.DEVNULL` constant which indicates that the
1612 special :data:`os.devnull` file will be used
1613 * the :const:`subprocess.STDOUT` constant which will connect the standard
1614 error stream to the process' standard output stream
1615
1616 * All other keyword arguments are passed to :class:`subprocess.Popen`
1617 without interpretation, except for *bufsize*, *universal_newlines*,
1618 *shell*, *text*, *encoding* and *errors*, which should not be specified
1619 at all.
1620
1621 The ``asyncio`` subprocess API does not support decoding the streams
1622 as text. :func:`bytes.decode` can be used to convert the bytes returned
1623 from the stream to text.
1624
1625 If a file-like object passed as *stdin*, *stdout* or *stderr* represents a
1626 pipe, then the other side of this pipe should be registered with
1627 :meth:`~loop.connect_write_pipe` or :meth:`~loop.connect_read_pipe` for use
1628 with the event loop.
1629
1630 See the constructor of the :class:`subprocess.Popen` class
1631 for documentation on other arguments.
1632
1633 Returns a pair of ``(transport, protocol)``, where *transport*
1634 conforms to the :class:`asyncio.SubprocessTransport` base class and
1635 *protocol* is an object instantiated by the *protocol_factory*.
1636
1637 If the transport is closed or is garbage collected, the child process
1638 is killed if it is still running.
1639
1640 .. method:: loop.subprocess_shell(protocol_factory, cmd, *, \
1641 stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
1642 stderr=subprocess.PIPE, **kwargs)
1643 :async:
1644
1645 Create a subprocess from *cmd*, which can be a :class:`str` or a
1646 :class:`bytes` string encoded to the
1647 :ref:`filesystem encoding <filesystem-encoding>`,
1648 using the platform's "shell" syntax.
1649
1650 This is similar to the standard library :class:`subprocess.Popen`
1651 class called with ``shell=True``.
1652
1653 The *protocol_factory* must be a callable returning a subclass of the
1654 :class:`SubprocessProtocol` class.
1655
1656 See :meth:`~loop.subprocess_exec` for more details about
1657 the remaining arguments.
1658
1659 Returns a pair of ``(transport, protocol)``, where *transport*
1660 conforms to the :class:`SubprocessTransport` base class and
1661 *protocol* is an object instantiated by the *protocol_factory*.
1662
1663 If the transport is closed or is garbage collected, the child process
1664 is killed if it is still running.
1665
1666 .. note::
1667 It is the application's responsibility to ensure that all whitespace
1668 and special characters are quoted appropriately to avoid `shell injection
1669 <https://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_
1670 vulnerabilities. The :func:`shlex.quote` function can be used to
1671 properly escape whitespace and special characters in strings that
1672 are going to be used to construct shell commands.
1673
1674
1675 Callback handles
1676 ================
1677
1678 .. class:: Handle
1679
1680 A callback wrapper object returned by :meth:`loop.call_soon`,
1681 :meth:`loop.call_soon_threadsafe`.
1682
1683 .. method:: get_context()
1684
1685 Return the :class:`contextvars.Context` object
1686 associated with the handle.
1687
1688 .. versionadded:: 3.12
1689
1690 .. method:: cancel()
1691
1692 Cancel the callback. If the callback has already been canceled
1693 or executed, this method has no effect.
1694
1695 .. method:: cancelled()
1696
1697 Return ``True`` if the callback was cancelled.
1698
1699 .. versionadded:: 3.7
1700
1701 .. class:: TimerHandle
1702
1703 A callback wrapper object returned by :meth:`loop.call_later`,
1704 and :meth:`loop.call_at`.
1705
1706 This class is a subclass of :class:`Handle`.
1707
1708 .. method:: when()
1709
1710 Return a scheduled callback time as :class:`float` seconds.
1711
1712 The time is an absolute timestamp, using the same time
1713 reference as :meth:`loop.time`.
1714
1715 .. versionadded:: 3.7
1716
1717
1718 Server objects
1719 ==============
1720
1721 Server objects are created by :meth:`loop.create_server`,
1722 :meth:`loop.create_unix_server`, :func:`start_server`,
1723 and :func:`start_unix_server` functions.
1724
1725 Do not instantiate the :class:`Server` class directly.
1726
1727 .. class:: Server
1728
1729 *Server* objects are asynchronous context managers. When used in an
1730 ``async with`` statement, it's guaranteed that the Server object is
1731 closed and not accepting new connections when the ``async with``
1732 statement is completed::
1733
1734 srv = await loop.create_server(...)
1735
1736 async with srv:
1737 # some code
1738
1739 # At this point, srv is closed and no longer accepts new connections.
1740
1741
1742 .. versionchanged:: 3.7
1743 Server object is an asynchronous context manager since Python 3.7.
1744
1745 .. versionchanged:: 3.11
1746 This class was exposed publicly as ``asyncio.Server`` in Python 3.9.11, 3.10.3 and 3.11.
1747
1748 .. method:: close()
1749
1750 Stop serving: close listening sockets and set the :attr:`sockets`
1751 attribute to ``None``.
1752
1753 The sockets that represent existing incoming client connections
1754 are left open.
1755
1756 The server is closed asynchronously; use the :meth:`wait_closed`
1757 coroutine to wait until the server is closed (and no more
1758 connections are active).
1759
1760 .. method:: close_clients()
1761
1762 Close all existing incoming client connections.
1763
1764 Calls :meth:`~asyncio.BaseTransport.close` on all associated
1765 transports.
1766
1767 :meth:`close` should be called before :meth:`close_clients` when
1768 closing the server to avoid races with new clients connecting.
1769
1770 .. versionadded:: 3.13
1771
1772 .. method:: abort_clients()
1773
1774 Close all existing incoming client connections immediately,
1775 without waiting for pending operations to complete.
1776
1777 Calls :meth:`~asyncio.WriteTransport.abort` on all associated
1778 transports.
1779
1780 :meth:`close` should be called before :meth:`abort_clients` when
1781 closing the server to avoid races with new clients connecting.
1782
1783 .. versionadded:: 3.13
1784
1785 .. method:: get_loop()
1786
1787 Return the event loop associated with the server object.
1788
1789 .. versionadded:: 3.7
1790
1791 .. method:: start_serving()
1792 :async:
1793
1794 Start accepting connections.
1795
1796 This method is idempotent, so it can be called when
1797 the server is already serving.
1798
1799 The *start_serving* keyword-only parameter to
1800 :meth:`loop.create_server` and
1801 :meth:`asyncio.start_server` allows creating a Server object
1802 that is not accepting connections initially. In this case
1803 ``Server.start_serving()``, or :meth:`Server.serve_forever` can be used
1804 to make the Server start accepting connections.
1805
1806 .. versionadded:: 3.7
1807
1808 .. method:: serve_forever()
1809 :async:
1810
1811 Start accepting connections until the coroutine is cancelled.
1812 Cancellation of ``serve_forever`` task causes the server
1813 to be closed.
1814
1815 This method can be called if the server is already accepting
1816 connections. Only one ``serve_forever`` task can exist per
1817 one *Server* object.
1818
1819 Example::
1820
1821 async def client_connected(reader, writer):
1822 # Communicate with the client with
1823 # reader/writer streams. For example:
1824 await reader.readline()
1825
1826 async def main(host, port):
1827 srv = await asyncio.start_server(
1828 client_connected, host, port)
1829 await srv.serve_forever()
1830
1831 asyncio.run(main('127.0.0.1', 0))
1832
1833 .. versionadded:: 3.7
1834
1835 .. method:: is_serving()
1836
1837 Return ``True`` if the server is accepting new connections.
1838
1839 .. versionadded:: 3.7
1840
1841 .. method:: wait_closed()
1842 :async:
1843
1844 Wait until the :meth:`close` method completes and all active
1845 connections have finished.
1846
1847 .. attribute:: sockets
1848
1849 List of socket-like objects, ``asyncio.trsock.TransportSocket``, which
1850 the server is listening on.
1851
1852 .. versionchanged:: 3.7
1853 Prior to Python 3.7 ``Server.sockets`` used to return an
1854 internal list of server sockets directly. In 3.7 a copy
1855 of that list is returned.
1856
1857
1858 .. _asyncio-event-loops:
1859 .. _asyncio-event-loop-implementations:
1860
1861 Event loop implementations
1862 ==========================
1863
1864 asyncio ships with two different event loop implementations:
1865 :class:`SelectorEventLoop` and :class:`ProactorEventLoop`.
1866
1867 By default asyncio is configured to use :class:`EventLoop`.
1868
1869
1870 .. class:: SelectorEventLoop
1871
1872 A subclass of :class:`AbstractEventLoop` based on the
1873 :mod:`selectors` module.
1874
1875 Uses the most efficient *selector* available for the given
1876 platform. It is also possible to manually configure the
1877 exact selector implementation to be used::
1878
1879 import asyncio
1880 import selectors
1881
1882 async def main():
1883 ...
1884
1885 loop_factory = lambda: asyncio.SelectorEventLoop(selectors.SelectSelector())
1886 asyncio.run(main(), loop_factory=loop_factory)
1887
1888
1889 .. availability:: Unix, Windows.
1890
1891
1892 .. class:: ProactorEventLoop
1893
1894 A subclass of :class:`AbstractEventLoop` for Windows that uses "I/O Completion Ports" (IOCP).
1895
1896 .. availability:: Windows.
1897
1898 .. seealso::
1899
1900 `MSDN documentation on I/O Completion Ports
1901 <https://learn.microsoft.com/windows/win32/fileio/i-o-completion-ports>`_.
1902
1903 .. class:: EventLoop
1904
1905 An alias to the most efficient available subclass of :class:`AbstractEventLoop` for the given
1906 platform.
1907
1908 It is an alias to :class:`SelectorEventLoop` on Unix and :class:`ProactorEventLoop` on Windows.
1909
1910 .. versionadded:: 3.13
1911
1912 .. class:: AbstractEventLoop
1913
1914 Abstract base class for asyncio-compliant event loops.
1915
1916 The :ref:`asyncio-event-loop-methods` section lists all
1917 methods that an alternative implementation of ``AbstractEventLoop``
1918 should have defined.
1919
1920
1921 Examples
1922 ========
1923
1924 Note that all examples in this section **purposefully** show how
1925 to use the low-level event loop APIs, such as :meth:`loop.run_forever`
1926 and :meth:`loop.call_soon`. Modern asyncio applications rarely
1927 need to be written this way; consider using the high-level functions
1928 like :func:`asyncio.run`.
1929
1930
1931 .. _asyncio_example_lowlevel_helloworld:
1932
1933 Hello World with call_soon()
1934 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1935
1936 An example using the :meth:`loop.call_soon` method to schedule a
1937 callback. The callback displays ``"Hello World"`` and then stops the
1938 event loop::
1939
1940 import asyncio
1941
1942 def hello_world(loop):
1943 """A callback to print 'Hello World' and stop the event loop"""
1944 print('Hello World')
1945 loop.stop()
1946
1947 loop = asyncio.new_event_loop()
1948
1949 # Schedule a call to hello_world()
1950 loop.call_soon(hello_world, loop)
1951
1952 # Blocking call interrupted by loop.stop()
1953 try:
1954 loop.run_forever()
1955 finally:
1956 loop.close()
1957
1958 .. seealso::
1959
1960 A similar :ref:`Hello World <coroutine>`
1961 example created with a coroutine and the :func:`run` function.
1962
1963
1964 .. _asyncio_example_call_later:
1965
1966 Display the current date with call_later()
1967 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1968
1969 An example of a callback displaying the current date every second. The
1970 callback uses the :meth:`loop.call_later` method to reschedule itself
1971 after 5 seconds, and then stops the event loop::
1972
1973 import asyncio
1974 import datetime as dt
1975
1976 def display_date(end_time, loop):
1977 print(dt.datetime.now())
1978 if (loop.time() + 1.0) < end_time:
1979 loop.call_later(1, display_date, end_time, loop)
1980 else:
1981 loop.stop()
1982
1983 loop = asyncio.new_event_loop()
1984
1985 # Schedule the first call to display_date()
1986 end_time = loop.time() + 5.0
1987 loop.call_soon(display_date, end_time, loop)
1988
1989 # Blocking call interrupted by loop.stop()
1990 try:
1991 loop.run_forever()
1992 finally:
1993 loop.close()
1994
1995 .. seealso::
1996
1997 A similar :ref:`current date <asyncio_example_sleep>` example
1998 created with a coroutine and the :func:`run` function.
1999
2000
2001 .. _asyncio_example_watch_fd:
2002
2003 Watch a file descriptor for read events
2004 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2005
2006 Wait until a file descriptor received some data using the
2007 :meth:`loop.add_reader` method and then close the event loop::
2008
2009 import asyncio
2010 from socket import socketpair
2011
2012 # Create a pair of connected file descriptors
2013 rsock, wsock = socketpair()
2014
2015 loop = asyncio.new_event_loop()
2016
2017 def reader():
2018 data = rsock.recv(100)
2019 print("Received:", data.decode())
2020
2021 # We are done: unregister the file descriptor
2022 loop.remove_reader(rsock)
2023
2024 # Stop the event loop
2025 loop.stop()
2026
2027 # Register the file descriptor for read event
2028 loop.add_reader(rsock, reader)
2029
2030 # Simulate the reception of data from the network
2031 loop.call_soon(wsock.send, 'abc'.encode())
2032
2033 try:
2034 # Run the event loop
2035 loop.run_forever()
2036 finally:
2037 # We are done. Close sockets and the event loop.
2038 rsock.close()
2039 wsock.close()
2040 loop.close()
2041
2042 .. seealso::
2043
2044 * A similar :ref:`example <asyncio_example_create_connection>`
2045 using transports, protocols, and the
2046 :meth:`loop.create_connection` method.
2047
2048 * Another similar :ref:`example <asyncio_example_create_connection-streams>`
2049 using the high-level :func:`asyncio.open_connection` function
2050 and streams.
2051
2052
2053 .. _asyncio_example_unix_signals:
2054
2055 Set signal handlers for SIGINT and SIGTERM
2056 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2057
2058 (This ``signal`` example only works on Unix.)
2059
2060 Register handlers for signals :const:`~signal.SIGINT` and :const:`~signal.SIGTERM`
2061 using the :meth:`loop.add_signal_handler` method::
2062
2063 import asyncio
2064 import functools
2065 import os
2066 import signal
2067
2068 def ask_exit(signame, loop):
2069 print("got signal %s: exit" % signame)
2070 loop.stop()
2071
2072 async def main():
2073 loop = asyncio.get_running_loop()
2074
2075 for signame in {'SIGINT', 'SIGTERM'}:
2076 loop.add_signal_handler(
2077 getattr(signal, signame),
2078 functools.partial(ask_exit, signame, loop))
2079
2080 await asyncio.sleep(3600)
2081
2082 print("Event loop running for 1 hour, press Ctrl+C to interrupt.")
2083 print(f"pid {os.getpid()}: send SIGINT or SIGTERM to exit.")
2084
2085 asyncio.run(main())