From 23742509c65833a346a194d86840a8def2e413de Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Tue, 27 Sep 2022 16:22:11 -0500 Subject: [PATCH 1/3] Update asycio policy doc intro paragraphs to be more clear and accurate --- Doc/library/asyncio-policy.rst | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/Doc/library/asyncio-policy.rst b/Doc/library/asyncio-policy.rst index ef6a0588506b52..500d6a849c2a96 100644 --- a/Doc/library/asyncio-policy.rst +++ b/Doc/library/asyncio-policy.rst @@ -7,17 +7,18 @@ Policies ======== -An event loop policy is a global per-process object that controls -the management of the event loop. Each event loop has a default -policy, which can be changed and customized using the policy API. - -A policy defines the notion of *context* and manages a -separate event loop per context. The default policy -defines *context* to be the current thread. - -By using a custom event loop policy, the behavior of -:func:`get_event_loop`, :func:`set_event_loop`, and -:func:`new_event_loop` functions can be customized. +An event loop policy is a global (per-interpreter) object +used to get and set the current event loop, as well as create new event loops. +The default policy can be replaced with built-in alternatives +to use different event loop implementations, +or substituted by a custom policy class that can override these behaviors. + +The policy object gets and sets a separate event loop per *context*. +This is per-thread by default, +though custom policies could define *context* differently. + +Custom event loop policies can control the behavior of +:func:`get_event_loop`, :func:`set_event_loop`, and :func:`new_event_loop`. Policy objects should implement the APIs defined in the :class:`AbstractEventLoopPolicy` abstract base class. From cff4ed883e252224f1b848dad7f563b490203015 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Tue, 27 Sep 2022 16:26:01 -0500 Subject: [PATCH 2/3] Link the relevant async policy doc sections when mentioned in the intro --- Doc/library/asyncio-policy.rst | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/Doc/library/asyncio-policy.rst b/Doc/library/asyncio-policy.rst index 500d6a849c2a96..abca29e2fb00f5 100644 --- a/Doc/library/asyncio-policy.rst +++ b/Doc/library/asyncio-policy.rst @@ -8,12 +8,16 @@ Policies ======== An event loop policy is a global (per-interpreter) object -used to get and set the current event loop, as well as create new event loops. -The default policy can be replaced with built-in alternatives +used to get and set the current event loop, +as well as create new event loops. +The default policy can be :ref:`replaced ` with +:ref:`built-in alternatives ` to use different event loop implementations, -or substituted by a custom policy class that can override these behaviors. +or substituted by a :ref:`custom policy ` +that can override these behaviors. -The policy object gets and sets a separate event loop per *context*. +The :ref:`policy object ` +gets and sets a separate event loop per *context*. This is per-thread by default, though custom policies could define *context* differently. @@ -24,6 +28,8 @@ Policy objects should implement the APIs defined in the :class:`AbstractEventLoopPolicy` abstract base class. +.. _asyncio-policy-get-set: + Getting and Setting the Policy ============================== @@ -41,6 +47,8 @@ for the current process: If *policy* is set to ``None``, the default policy is restored. +.. _asyncio-policy-objects: + Policy Objects ============== @@ -87,6 +95,8 @@ The abstract event loop policy base class is defined as follows: This function is Unix specific. +.. _asyncio-policy-builtin: + asyncio ships with the following built-in policies: @@ -118,6 +128,7 @@ asyncio ships with the following built-in policies: .. availability:: Windows. + .. _asyncio-watchers: Process Watchers @@ -271,6 +282,8 @@ implementation used by the asyncio event loop: .. versionadded:: 3.9 +.. _asyncio-custom-policies: + Custom Policies =============== From c7e411768d9c44726ee8a4bb1417d0b6e6378800 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Tue, 27 Sep 2022 16:44:11 -0500 Subject: [PATCH 3/3] Point asycio-event-loop ref to top-level summary & use in policy doc --- Doc/library/asyncio-dev.rst | 2 +- Doc/library/asyncio-eventloop.rst | 7 +++++-- Doc/library/asyncio-llapi-index.rst | 2 +- Doc/library/asyncio-policy.rst | 2 +- 4 files changed, 8 insertions(+), 5 deletions(-) diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst index 9676a352f4b24e..14f2c3533c9712 100644 --- a/Doc/library/asyncio-dev.rst +++ b/Doc/library/asyncio-dev.rst @@ -109,7 +109,7 @@ that the event loop runs in. There is currently no way to schedule coroutines or callbacks directly from a different process (such as one started with -:mod:`multiprocessing`). The :ref:`Event Loop Methods ` +:mod:`multiprocessing`). The :ref:`asyncio-event-loop-methods` section lists APIs that can read from pipes and watch file descriptors without blocking the event loop. In addition, asyncio's :ref:`Subprocess ` APIs provide a way to start a diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index ef0f6fc8e68cd4..b61ffd5a323edb 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -1,6 +1,8 @@ .. currentmodule:: asyncio +.. _asyncio-event-loop: + ========== Event Loop ========== @@ -92,7 +94,7 @@ This documentation page contains the following sections: loop APIs. -.. _asyncio-event-loop: +.. _asyncio-event-loop-methods: Event Loop Methods ================== @@ -1598,6 +1600,7 @@ Do not instantiate the class directly. .. _asyncio-event-loops: +.. _asyncio-event-loop-implementations: Event Loop Implementations ========================== @@ -1644,7 +1647,7 @@ on Unix and :class:`ProactorEventLoop` on Windows. Abstract base class for asyncio-compliant event loops. - The :ref:`Event Loop Methods ` section lists all + The :ref:`asyncio-event-loop-methods` section lists all methods that an alternative implementation of ``AbstractEventLoop`` should have defined. diff --git a/Doc/library/asyncio-llapi-index.rst b/Doc/library/asyncio-llapi-index.rst index 3cec4c69f86ea7..b7ad888a7b67ab 100644 --- a/Doc/library/asyncio-llapi-index.rst +++ b/Doc/library/asyncio-llapi-index.rst @@ -37,7 +37,7 @@ Event Loop Methods ================== See also the main documentation section about the -:ref:`event loop methods `. +:ref:`asyncio-event-loop-methods`. .. rubric:: Lifecycle .. list-table:: diff --git a/Doc/library/asyncio-policy.rst b/Doc/library/asyncio-policy.rst index abca29e2fb00f5..a73e99510f0b4e 100644 --- a/Doc/library/asyncio-policy.rst +++ b/Doc/library/asyncio-policy.rst @@ -8,7 +8,7 @@ Policies ======== An event loop policy is a global (per-interpreter) object -used to get and set the current event loop, +used to get and set the current :ref:`event loop `, as well as create new event loops. The default policy can be :ref:`replaced ` with :ref:`built-in alternatives `