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