| 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()) |