Debian Codegraph @

Doc/library/asyncio.rst

raw
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/`.