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
22asyncio is a library to write **concurrent** code using
23the **async/await** syntax.
24
25asyncio is used as a foundation for multiple Python asynchronous
26frameworks that provide high-performance network and web-servers,
27database connection libraries, distributed task queues, etc.
28
29asyncio is often a perfect fit for IO-bound and high-level
30**structured** network code.
31
32asyncio provides a set of **high-level** APIs to:
33
34* :ref:`run Python coroutines <coroutine>` concurrently and
35  have full control over their execution;
36
37* perform :ref:`network IO and IPC <asyncio-streams>`;
38
39* control :ref:`subprocesses <asyncio-subprocess>`;
40
41* distribute tasks via :ref:`queues <asyncio-queues>`;
42
43* :ref:`synchronize <asyncio-sync>` concurrent code;
44
45Additionally, there are **low-level** APIs for
46*library and framework developers* to:
47
48* create and manage :ref:`event loops <asyncio-event-loop>`, which
49  provide asynchronous APIs for :meth:`networking <loop.create_server>`,
50  running :meth:`subprocesses <loop.subprocess_exec>`,
51  handling :meth:`OS signals <loop.add_signal_handler>`, etc;
52
53* implement efficient protocols using
54  :ref:`transports <asyncio-transports-protocols>`;
55
56* :ref:`bridge <asyncio-futures>` callback-based libraries and code
57  with async/await syntax.
58
59You can experiment with an ``asyncio`` concurrent context in the REPL:
60
61.. code-block:: pycon
62
63   $ python -m asyncio
64   asyncio REPL ...
65   Use "await" directly instead of "asyncio.run()".
66   Type "help", "copyright", "credits" or "license" for more information.
67   >>> import asyncio
68   >>> await asyncio.sleep(10, result='hello')
69   'hello'
70
71.. include:: ../includes/wasm-notavail.rst
72
73.. We use the "rubric" directive here to avoid creating
74   the "Reference" subsection in the TOC.
75
76.. rubric:: Reference
77
78.. toctree::
79   :caption: High-level APIs
80   :maxdepth: 1
81
82   asyncio-runner.rst
83   asyncio-task.rst
84   asyncio-stream.rst
85   asyncio-sync.rst
86   asyncio-subprocess.rst
87   asyncio-queue.rst
88   asyncio-exceptions.rst
89
90.. toctree::
91   :caption: Low-level APIs
92   :maxdepth: 1
93
94   asyncio-eventloop.rst
95   asyncio-future.rst
96   asyncio-protocol.rst
97   asyncio-policy.rst
98   asyncio-platforms.rst
99   asyncio-extending.rst
100
101.. toctree::
102   :caption: Guides and Tutorials
103   :maxdepth: 1
104
105   asyncio-api-index.rst
106   asyncio-llapi-index.rst
107   asyncio-dev.rst
108
109.. note::
110   The source code for asyncio can be found in :source:`Lib/asyncio/`.
111