From c644efcb7ca96aadaff9e8a0cc0a959482111532 Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Tue, 8 Oct 2019 04:04:54 -0400 Subject: [PATCH 1/6] Docs: Add asyncio source code links --- Doc/library/asyncio-eventloop.rst | 7 +++++-- Doc/library/asyncio-exceptions.rst | 3 +++ Doc/library/asyncio-future.rst | 5 +++++ Doc/library/asyncio-platforms.rst | 6 ++++++ Doc/library/asyncio-protocol.rst | 8 ++++++++ Doc/library/asyncio-queue.rst | 4 ++++ Doc/library/asyncio-stream.rst | 4 ++++ Doc/library/asyncio-subprocess.rst | 5 +++++ Doc/library/asyncio-sync.rst | 4 ++++ Doc/library/asyncio-task.rst | 15 ++++++++++++--- Doc/library/asyncio.rst | 4 +++- 11 files changed, 59 insertions(+), 6 deletions(-) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 045787e0ce7875..15965a8d71beb4 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -1,10 +1,15 @@ .. currentmodule:: asyncio +.. _asyncio-event-loop: ========== Event Loop ========== +**Source code:** :source:`Lib/asyncio/events.py`, +:source:`Lib/asyncio/base_events.py` + +------------------------------------ .. rubric:: Preface @@ -81,8 +86,6 @@ This documentation page contains the following sections: loop APIs. -.. _asyncio-event-loop: - Event Loop Methods ================== diff --git a/Doc/library/asyncio-exceptions.rst b/Doc/library/asyncio-exceptions.rst index b1e6ecfda15ead..7166d5c4bd88f9 100644 --- a/Doc/library/asyncio-exceptions.rst +++ b/Doc/library/asyncio-exceptions.rst @@ -7,6 +7,9 @@ Exceptions ========== +**Source code:** :source:`Lib/asyncio/exceptions.py` + +---------------------------------------------------- .. exception:: TimeoutError diff --git a/Doc/library/asyncio-future.rst b/Doc/library/asyncio-future.rst index c069471b519be9..832d58119b7b07 100644 --- a/Doc/library/asyncio-future.rst +++ b/Doc/library/asyncio-future.rst @@ -7,6 +7,11 @@ Futures ======= +**Source code:** :source:`Lib/asyncio/futures.py`, +:source:`Lib/asyncio/base_futures.py` + +------------------------------------- + *Future* objects are used to bridge **low-level callback-based code** with high-level async/await code. diff --git a/Doc/library/asyncio-platforms.rst b/Doc/library/asyncio-platforms.rst index 7e4a70f91c6ed5..390ee1969d096f 100644 --- a/Doc/library/asyncio-platforms.rst +++ b/Doc/library/asyncio-platforms.rst @@ -23,6 +23,12 @@ All Platforms Windows ======= +**Source code:** :source:`Lib/asyncio/proactor_events.py`, +:source:`Lib/asyncio/windows_events.py`, +:source:`Lib/asyncio/windows_utils.py` + +-------------------------------------- + .. versionchanged:: 3.8 On Windows, :class:`ProactorEventLoop` is now the default event loop. diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst index 67ca121081684f..ffac9018127c66 100644 --- a/Doc/library/asyncio-protocol.rst +++ b/Doc/library/asyncio-protocol.rst @@ -69,6 +69,10 @@ This documentation page contains the following sections: Transports ========== +**Source code:** :source:`Lib/asyncio/transports.py` + +---------------------------------------------------- + Transports are classes provided by :mod:`asyncio` in order to abstract various kinds of communication channels. @@ -431,6 +435,10 @@ Subprocess Transports Protocols ========= +**Source code:** :source:`Lib/asyncio/protocols.py` + +--------------------------------------------------- + asyncio provides a set of abstract base classes that should be used to implement network protocols. Those classes are meant to be used together with :ref:`transports `. diff --git a/Doc/library/asyncio-queue.rst b/Doc/library/asyncio-queue.rst index e7775da54f5891..524560b691d720 100644 --- a/Doc/library/asyncio-queue.rst +++ b/Doc/library/asyncio-queue.rst @@ -6,6 +6,10 @@ Queues ====== +**Source code:** :source:`Lib/asyncio/queues.py` + +------------------------------------------------ + asyncio queues are designed to be similar to classes of the :mod:`queue` module. Although asyncio queues are not thread-safe, they are designed to be used specifically in async/await code. diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index 471e6e9099c2c4..bb899714a0ec06 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -6,6 +6,10 @@ Streams ======= +**Source code:** :source:`Lib/asyncio/streams.py` + +------------------------------------------------- + Streams are high-level async/await-ready primitives to work with network connections. Streams allow sending and receiving data without using callbacks or low-level protocols and transports. diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst index bd92257c82efa2..1d87d2f8005ec6 100644 --- a/Doc/library/asyncio-subprocess.rst +++ b/Doc/library/asyncio-subprocess.rst @@ -6,6 +6,11 @@ Subprocesses ============ +**Source code:** :source:`Lib/asyncio/subprocess.py`, +:source:`Lib/asyncio/base_subprocess.py` + +---------------------------------------- + This section describes high-level async/await asyncio APIs to create and manage subprocesses. diff --git a/Doc/library/asyncio-sync.rst b/Doc/library/asyncio-sync.rst index cc8c29dc3b6bc5..f080b03bc7c51c 100644 --- a/Doc/library/asyncio-sync.rst +++ b/Doc/library/asyncio-sync.rst @@ -6,6 +6,10 @@ Synchronization Primitives ========================== +**Source code:** :source:`Lib/asyncio/locks.py` + +----------------------------------------------- + asyncio synchronization primitives are designed to be similar to those of the :mod:`threading` module with two important caveats: diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 155887a3ab3af9..7f31e2fe923e15 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -18,9 +18,9 @@ and Tasks. Coroutines ========== -Coroutines declared with async/await syntax is the preferred way of -writing asyncio applications. For example, the following snippet -of code (requires Python 3.7+) prints "hello", waits 1 second, +:term:`Coroutines ` declared with the async/await syntax is the +preferred way of writing asyncio applications. For example, the following +snippet of code (requires Python 3.7+) prints "hello", waits 1 second, and then prints "world":: >>> import asyncio @@ -210,6 +210,10 @@ is :meth:`loop.run_in_executor`. Running an asyncio Program ========================== +**Source code:** :source:`Lib/asyncio/runners.py` + +------------------------------------------------- + .. function:: run(coro, \*, debug=False) Execute the :term:`coroutine` *coro* and return the result. @@ -243,6 +247,11 @@ Running an asyncio Program Creating Tasks ============== +**Source code:** :source:`Lib/asyncio/tasks.py`, +:source:`Lib/asyncio/base_tasks.py` + +----------------------------------- + .. function:: create_task(coro, \*, name=None) Wrap the *coro* :ref:`coroutine ` into a :class:`Task` diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst index 6990adb21e3603..b6f0a40334a8d8 100644 --- a/Doc/library/asyncio.rst +++ b/Doc/library/asyncio.rst @@ -4,7 +4,9 @@ .. module:: asyncio :synopsis: Asynchronous I/O. --------------- +**Source code:** :source:`Lib/asyncio/` + +--------------------------------------- .. sidebar:: Hello World! From 19f495c633101118bbd4b5129103b5e6e2e1118a Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Tue, 8 Oct 2019 12:32:03 -0400 Subject: [PATCH 2/6] Revert asyncio-event-loop ref --- Doc/library/asyncio-eventloop.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 15965a8d71beb4..240d814f13dea9 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -1,6 +1,5 @@ .. currentmodule:: asyncio -.. _asyncio-event-loop: ========== Event Loop @@ -86,6 +85,8 @@ This documentation page contains the following sections: loop APIs. +.. _asyncio-event-loop: + Event Loop Methods ================== From 8465b7e29238ab8a9cc26b65c5ba80dcfb13c6f2 Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Thu, 10 Oct 2019 17:16:10 -0400 Subject: [PATCH 3/6] Move Lib/asyncio source link --- Doc/library/asyncio.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst index b6f0a40334a8d8..40e4e970e585af 100644 --- a/Doc/library/asyncio.rst +++ b/Doc/library/asyncio.rst @@ -4,10 +4,6 @@ .. module:: asyncio :synopsis: Asynchronous I/O. -**Source code:** :source:`Lib/asyncio/` - ---------------------------------------- - .. sidebar:: Hello World! :: @@ -93,3 +89,5 @@ Additionally, there are **low-level** APIs for asyncio-api-index.rst asyncio-llapi-index.rst asyncio-dev.rst + +.. note:: The source code for asyncio can be found in :source:`Lib/asyncio/`. From 91664afaa8d60d9724b72d11f6cf241f4b503340 Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Thu, 10 Oct 2019 17:20:11 -0400 Subject: [PATCH 4/6] Remove tasks and base_tasks source links --- Doc/library/asyncio-task.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 7f31e2fe923e15..018e936cee942f 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -247,11 +247,6 @@ Running an asyncio Program Creating Tasks ============== -**Source code:** :source:`Lib/asyncio/tasks.py`, -:source:`Lib/asyncio/base_tasks.py` - ------------------------------------ - .. function:: create_task(coro, \*, name=None) Wrap the *coro* :ref:`coroutine ` into a :class:`Task` From e5dcdb522a07ed4b304e3651658b2c016dfadb18 Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Thu, 10 Oct 2019 17:40:43 -0400 Subject: [PATCH 5/6] Move asyncio.run source link --- Doc/library/asyncio-task.rst | 8 ++++---- Doc/library/asyncio.rst | 5 ++++- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 018e936cee942f..e428b24e3174ba 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -210,10 +210,6 @@ is :meth:`loop.run_in_executor`. Running an asyncio Program ========================== -**Source code:** :source:`Lib/asyncio/runners.py` - -------------------------------------------------- - .. function:: run(coro, \*, debug=False) Execute the :term:`coroutine` *coro* and return the result. @@ -244,6 +240,10 @@ Running an asyncio Program .. versionchanged:: 3.9 Updated to use :meth:`loop.shutdown_default_executor`. +.. note:: + The source code for ``asyncio.run()`` can be found in + :source:`Lib/asyncio/runners.py`. + Creating Tasks ============== diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst index 40e4e970e585af..94a853259d3483 100644 --- a/Doc/library/asyncio.rst +++ b/Doc/library/asyncio.rst @@ -4,6 +4,8 @@ .. module:: asyncio :synopsis: Asynchronous I/O. +------------------------------- + .. sidebar:: Hello World! :: @@ -90,4 +92,5 @@ Additionally, there are **low-level** APIs for asyncio-llapi-index.rst asyncio-dev.rst -.. note:: The source code for asyncio can be found in :source:`Lib/asyncio/`. +.. note:: + The source code for asyncio can be found in :source:`Lib/asyncio/`. From eaddd031e474e7587e467b2d04880adae09edacd Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Thu, 10 Oct 2019 18:32:09 -0400 Subject: [PATCH 6/6] Fix indentation for asyncio.run note --- Doc/library/asyncio-task.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index e428b24e3174ba..d992b0011dc660 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -240,9 +240,9 @@ Running an asyncio Program .. versionchanged:: 3.9 Updated to use :meth:`loop.shutdown_default_executor`. -.. note:: - The source code for ``asyncio.run()`` can be found in - :source:`Lib/asyncio/runners.py`. + .. note:: + The source code for ``asyncio.run()`` can be found in + :source:`Lib/asyncio/runners.py`. Creating Tasks ==============