| 1 |
:mod:`!asyncio` --- Asynchronous I/O |
| 2 |
==================================== |
| 3 |
|
| 4 |
.. module:: asyncio |
| 5 |
:synopsis: Asynchronous I/O. |
| 6 |
|
| 7 |
------------------------------- |
| 8 |
|
| 9 |
.. sidebar:: Hello World! |
| 10 |
|
| 11 |
:: |
| 12 |
|
| 13 |
import asyncio |
| 14 |
|
| 15 |
async def main(): |
| 16 |
print('Hello ...') |
| 17 |
await asyncio.sleep(1) |
| 18 |
print('... World!') |
| 19 |
|
| 20 |
asyncio.run(main()) |
| 21 |
|
| 22 |
asyncio is a library to write **concurrent** code using |
| 23 |
the **async/await** syntax. |
| 24 |
|
| 25 |
asyncio is used as a foundation for multiple Python asynchronous |
| 26 |
frameworks that provide high-performance network and web-servers, |
| 27 |
database connection libraries, distributed task queues, etc. |
| 28 |
|
| 29 |
asyncio is often a perfect fit for IO-bound and high-level |
| 30 |
**structured** network code. |
| 31 |
|
| 32 |
.. seealso:: |
| 33 |
|
| 34 |
:ref:`a-conceptual-overview-of-asyncio` |
| 35 |
Explanation of the fundamentals of asyncio. |
| 36 |
|
| 37 |
asyncio provides a set of **high-level** APIs to: |
| 38 |
|
| 39 |
* :ref:`run Python coroutines <coroutine>` concurrently and |
| 40 |
have full control over their execution; |
| 41 |
|
| 42 |
* perform :ref:`network IO and IPC <asyncio-streams>`; |
| 43 |
|
| 44 |
* control :ref:`subprocesses <asyncio-subprocess>`; |
| 45 |
|
| 46 |
* distribute tasks via :ref:`queues <asyncio-queues>`; |
| 47 |
|
| 48 |
* :ref:`synchronize <asyncio-sync>` concurrent code; |
| 49 |
|
| 50 |
Additionally, there are **low-level** APIs for |
| 51 |
*library and framework developers* to: |
| 52 |
|
| 53 |
* create and manage :ref:`event loops <asyncio-event-loop>`, which |
| 54 |
provide asynchronous APIs for :ref:`networking <loop_create_server>`, |
| 55 |
running :ref:`subprocesses <loop_subprocess_exec>`, |
| 56 |
handling :ref:`OS signals <loop_add_signal_handler>`, etc; |
| 57 |
|
| 58 |
* implement efficient protocols using |
| 59 |
:ref:`transports <asyncio-transports-protocols>`; |
| 60 |
|
| 61 |
* :ref:`bridge <asyncio-futures>` callback-based libraries and code |
| 62 |
with async/await syntax. |
| 63 |
|
| 64 |
.. include:: ../includes/wasm-notavail.rst |
| 65 |
|
| 66 |
.. _asyncio-cli: |
| 67 |
|
| 68 |
.. rubric:: asyncio REPL |
| 69 |
|
| 70 |
You can experiment with an ``asyncio`` concurrent context in the :term:`REPL`: |
| 71 |
|
| 72 |
.. code-block:: pycon |
| 73 |
|
| 74 |
$ python -m asyncio |
| 75 |
asyncio REPL ... |
| 76 |
Use "await" directly instead of "asyncio.run()". |
| 77 |
Type "help", "copyright", "credits" or "license" for more information. |
| 78 |
>>> import asyncio |
| 79 |
>>> await asyncio.sleep(10, result='hello') |
| 80 |
'hello' |
| 81 |
|
| 82 |
This REPL provides limited compatibility with :envvar:`PYTHON_BASIC_REPL`. |
| 83 |
It is recommended that the default REPL is used |
| 84 |
for full functionality and the latest features. |
| 85 |
|
| 86 |
.. audit-event:: cpython.run_stdin "" "" |
| 87 |
|
| 88 |
.. versionchanged:: 3.12.5 (also 3.11.10, 3.10.15, 3.9.20, and 3.8.20) |
| 89 |
Emits audit events. |
| 90 |
|
| 91 |
.. versionchanged:: 3.13 |
| 92 |
Uses PyREPL if possible, in which case :envvar:`PYTHONSTARTUP` is |
| 93 |
also executed. Emits audit events. |
| 94 |
|
| 95 |
.. We use the "rubric" directive here to avoid creating |
| 96 |
the "Reference" subsection in the TOC. |
| 97 |
|
| 98 |
.. rubric:: Reference |
| 99 |
|
| 100 |
.. toctree:: |
| 101 |
:caption: High-level APIs |
| 102 |
:maxdepth: 1 |
| 103 |
|
| 104 |
asyncio-runner.rst |
| 105 |
asyncio-task.rst |
| 106 |
asyncio-stream.rst |
| 107 |
asyncio-sync.rst |
| 108 |
asyncio-subprocess.rst |
| 109 |
asyncio-queue.rst |
| 110 |
asyncio-exceptions.rst |
| 111 |
asyncio-graph.rst |
| 112 |
|
| 113 |
.. toctree:: |
| 114 |
:caption: Low-level APIs |
| 115 |
:maxdepth: 1 |
| 116 |
|
| 117 |
asyncio-eventloop.rst |
| 118 |
asyncio-future.rst |
| 119 |
asyncio-protocol.rst |
| 120 |
asyncio-policy.rst |
| 121 |
asyncio-platforms.rst |
| 122 |
asyncio-extending.rst |
| 123 |
|
| 124 |
.. toctree:: |
| 125 |
:caption: Guides and Tutorials |
| 126 |
:maxdepth: 1 |
| 127 |
|
| 128 |
asyncio-api-index.rst |
| 129 |
asyncio-llapi-index.rst |
| 130 |
asyncio-dev.rst |
| 131 |
|
| 132 |
.. note:: |
| 133 |
The source code for asyncio can be found in :source:`Lib/asyncio/`. |