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 asyncio 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 
45 Additionally, 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 
59 You 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