66
77--------------
88
9- .. TODO: rewrite the introduction section
9+ asyncio is a library to write **concurrent ** code using
10+ **async/await ** syntax.
1011
11- This module provides infrastructure for writing single-threaded concurrent
12- code using coroutines, multiplexing I/O access over sockets and other
13- resources, running network clients and servers, and other related primitives.
14- Here is a more detailed list of the package contents:
12+ asyncio is used as a foundation for multiple Python asynchronous
13+ frameworks that provide high-performance network and web-servers,
14+ database connection libraries, distributed task queues, etc.
1515
16- * a pluggable :ref: ` event loop < asyncio-event-loop >` with various system-specific
17- implementations;
16+ asyncio is often a perfect fit for IO-bound and high-level
17+ ** structured ** network code.
1818
19- * :ref: `transport <asyncio-transport >` and :ref: `protocol <asyncio-protocol >` abstractions
20- (similar to those in `Twisted <https://twistedmatrix.com/trac/ >`_);
19+ asyncio provides a set of **high-level ** APIs to:
2120
22- * concrete support for TCP, UDP, SSL, subprocess pipes, delayed calls, and
23- others (some may be system-dependent) ;
21+ * :ref: ` run Python coroutines < coroutine >` concurrently and
22+ have full control over their execution ;
2423
25- * a :class: `Future ` class that mimics the one in the :mod: `concurrent.futures `
26- module, but adapted for use with the event loop;
24+ * perform :ref: `network IO and IPC <asyncio-streams >`;
2725
28- * coroutines and tasks based on ``yield from `` (:PEP: `380 `), to help write
29- concurrent code in a sequential fashion;
26+ * control :ref: `subprocesses <asyncio-subprocess >`;
3027
31- * cancellation support for :class: ` Future ` \s and coroutines ;
28+ * distribute tasks via :ref: ` queues < asyncio-queues >` ;
3229
33- * :ref: `synchronization primitives <asyncio-sync >` for use between coroutines in
34- a single thread, mimicking those in the :mod: `threading ` module;
30+ * :ref: `synchronize <asyncio-sync >` concurrent code;
3531
36- * an interface for passing work off to a threadpool, for times when
37- you absolutely, positively have to use a library that makes blocking
38- I/O calls.
32+ as well as **low-level ** APIs for *library and framework developers * to:
3933
40- Asynchronous programming is more complex than classical "sequential"
41- programming: see the :ref: `Develop with asyncio <asyncio-dev >` page which lists
42- common traps and explains how to avoid them. :ref: `Enable the debug mode
43- <asyncio-debug-mode>` during development to detect common issues.
34+ * create and manage :ref: `event loops <asyncio-event-loop >`, which
35+ provide asynchronous APIs for networking, subprocesses, OS signals,
36+ etc;
4437
45- High-level APIs:
38+ * implement efficient protocols using
39+ :ref: `transports <asyncio-transports-protocols >`;
40+
41+ * :ref: `bridge <asyncio-futures >` callback-based libraries and code
42+ with async/await syntax.
43+
44+
45+ Contents
46+ --------
47+
48+ .. rubric :: High-level APIs
4649
4750.. toctree ::
4851 :maxdepth: 1
@@ -54,7 +57,7 @@ High-level APIs:
5457 asyncio-queue.rst
5558 asyncio-exceptions.rst
5659
57- Low-level APIs:
60+ .. rubric :: Low-level APIs
5861
5962.. toctree ::
6063 :maxdepth: 1
@@ -65,7 +68,7 @@ Low-level APIs:
6568 asyncio-policy.rst
6669 asyncio-platforms.rst
6770
68- Guides and Tutorials:
71+ .. rubric :: Guides and Tutorials
6972
7073.. toctree ::
7174 :maxdepth: 1
0 commit comments