From 034a785980d9142a2b00644a5dc35d1cb06d75ce Mon Sep 17 00:00:00 2001 From: Yury Selivanov Date: Fri, 14 Sep 2018 14:32:55 -0700 Subject: [PATCH 1/3] bpo-33649: Refresh asyncio docs landing page --- Doc/library/asyncio-future.rst | 2 ++ Doc/library/asyncio.rst | 49 +++++++++++++++++----------------- 2 files changed, 26 insertions(+), 25 deletions(-) diff --git a/Doc/library/asyncio-future.rst b/Doc/library/asyncio-future.rst index 2c41c1c2165c5f..ff04339d8580a9 100644 --- a/Doc/library/asyncio-future.rst +++ b/Doc/library/asyncio-future.rst @@ -1,6 +1,8 @@ .. currentmodule:: asyncio +.. _asyncio-futures: + ======= Futures ======= diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst index 2c8ccbb390f01b..b4231468a3e801 100644 --- a/Doc/library/asyncio.rst +++ b/Doc/library/asyncio.rst @@ -6,41 +6,40 @@ -------------- -.. TODO: rewrite the introduction section +asyncio is a library to write **concurrent** code using +**async/await** syntax. -This module provides infrastructure for writing single-threaded concurrent -code using coroutines, multiplexing I/O access over sockets and other -resources, running network clients and servers, and other related primitives. -Here is a more detailed list of the package contents: +asyncio is used as a foundation for multiple Python asynchronous +frameworks that provide high-performance network and web-servers, +database connection libraries, distributed task queues, etc. -* a pluggable :ref:`event loop ` with various system-specific - implementations; +asyncio is often a perfect fit for IO-bound and high-level +**structured** network code. -* :ref:`transport ` and :ref:`protocol ` abstractions - (similar to those in `Twisted `_); +asyncio provides a set of **high-level** APIs to: -* concrete support for TCP, UDP, SSL, subprocess pipes, delayed calls, and - others (some may be system-dependent); +* :ref:`run Python coroutines ` concurrently and + have full control over their execution; -* a :class:`Future` class that mimics the one in the :mod:`concurrent.futures` - module, but adapted for use with the event loop; +* perform :ref:`network IO and IPC `; -* coroutines and tasks based on ``yield from`` (:PEP:`380`), to help write - concurrent code in a sequential fashion; +* control :ref:`subprocesses `; -* cancellation support for :class:`Future`\s and coroutines; +* distribute tasks via :ref:`queues `; -* :ref:`synchronization primitives ` for use between coroutines in - a single thread, mimicking those in the :mod:`threading` module; +* :ref:`synchronize ` concurrent code; -* an interface for passing work off to a threadpool, for times when - you absolutely, positively have to use a library that makes blocking - I/O calls. +as well as **low-level** APIs to: -Asynchronous programming is more complex than classical "sequential" -programming: see the :ref:`Develop with asyncio ` page which lists -common traps and explains how to avoid them. :ref:`Enable the debug mode -` during development to detect common issues. +* create and manage :ref:`event loops `, which + provide asynchronous APIs for networking, subprocesses, OS signals, + etc; + +* implement efficient protocols using + :ref:`transports `; + +* :ref:`bridge ` callback-based libraries and code + with async/await syntax. High-level APIs: From a1ac1563e262a7e34fec685842177afb73461154 Mon Sep 17 00:00:00 2001 From: Yury Selivanov Date: Fri, 14 Sep 2018 14:40:24 -0700 Subject: [PATCH 2/3] Fixes --- Doc/library/asyncio-queue.rst | 1 + Doc/library/asyncio.rst | 10 +++++++--- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/Doc/library/asyncio-queue.rst b/Doc/library/asyncio-queue.rst index a910dc73ab26df..fcad751fe19d4b 100644 --- a/Doc/library/asyncio-queue.rst +++ b/Doc/library/asyncio-queue.rst @@ -1,5 +1,6 @@ .. currentmodule:: asyncio +.. _asyncio-queues: ====== Queues diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst index b4231468a3e801..bdbf809cbefa9c 100644 --- a/Doc/library/asyncio.rst +++ b/Doc/library/asyncio.rst @@ -41,7 +41,11 @@ as well as **low-level** APIs to: * :ref:`bridge ` callback-based libraries and code with async/await syntax. -High-level APIs: + +Contents +-------- + +.. rubric:: High-level APIs .. toctree:: :maxdepth: 1 @@ -53,7 +57,7 @@ High-level APIs: asyncio-queue.rst asyncio-exceptions.rst -Low-level APIs: +.. rubric:: Low-level APIs .. toctree:: :maxdepth: 1 @@ -64,7 +68,7 @@ Low-level APIs: asyncio-policy.rst asyncio-platforms.rst -Guides and Tutorials: +.. rubric:: Guides and Tutorials .. toctree:: :maxdepth: 1 From 49f355bb686d26a112fe3d95eda0b79f28794a12 Mon Sep 17 00:00:00 2001 From: Yury Selivanov Date: Fri, 14 Sep 2018 14:43:02 -0700 Subject: [PATCH 3/3] Feedback --- Doc/library/asyncio.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst index bdbf809cbefa9c..c1b04086c35f08 100644 --- a/Doc/library/asyncio.rst +++ b/Doc/library/asyncio.rst @@ -29,7 +29,7 @@ asyncio provides a set of **high-level** APIs to: * :ref:`synchronize ` concurrent code; -as well as **low-level** APIs to: +as well as **low-level** APIs for *library and framework developers* to: * create and manage :ref:`event loops `, which provide asynchronous APIs for networking, subprocesses, OS signals,