From 64173cd6f2d8dc95c6f8b67912d0edd1c1b707d5 Mon Sep 17 00:00:00 2001
From: Kumar Aditya <kumaraditya@python.org>
Date: Fri, 27 Dec 2024 20:43:41 +0530
Subject: [PATCH] gh-127949: make deprecation of policy system more prominent
 (#128290)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
---
 Doc/deprecations/pending-removal-in-3.16.rst | 27 +++++++++++++++++++-
 Doc/library/asyncio-eventloop.rst            | 16 ++++++++----
 Doc/library/asyncio-runner.rst               |  6 +++++
 3 files changed, 43 insertions(+), 6 deletions(-)

diff --git a/Doc/deprecations/pending-removal-in-3.16.rst b/Doc/deprecations/pending-removal-in-3.16.rst
index 6f6954b783a1ae..f2b818f14c63cd 100644
--- a/Doc/deprecations/pending-removal-in-3.16.rst
+++ b/Doc/deprecations/pending-removal-in-3.16.rst
@@ -19,10 +19,35 @@ Pending removal in Python 3.16
 * :mod:`asyncio`:
 
   * :func:`!asyncio.iscoroutinefunction` is deprecated
-    and will be removed in Python 3.16,
+    and will be removed in Python 3.16;
     use :func:`inspect.iscoroutinefunction` instead.
     (Contributed by Jiahao Li and Kumar Aditya in :gh:`122875`.)
 
+  * :mod:`asyncio` policy system is deprecated and will be removed in Python 3.16.
+    In particular, the following classes and functions are deprecated:
+
+    * :class:`asyncio.AbstractEventLoopPolicy`
+    * :class:`asyncio.DefaultEventLoopPolicy`
+    * :class:`asyncio.WindowsSelectorEventLoopPolicy`
+    * :class:`asyncio.WindowsProactorEventLoopPolicy`
+    * :func:`asyncio.get_event_loop_policy`
+    * :func:`asyncio.set_event_loop_policy`
+    * :func:`asyncio.set_event_loop`
+
+    Users should use :func:`asyncio.run` or :class:`asyncio.Runner` with
+    *loop_factory* to use the desired event loop implementation.
+
+    For example, to use :class:`asyncio.SelectorEventLoop` on Windows::
+
+      import asyncio
+
+      async def main():
+          ...
+
+      asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)
+
+    (Contributed by Kumar Aditya in :gh:`127949`.)
+
 * :mod:`builtins`:
 
   * Bitwise inversion on boolean types, ``~True`` or ``~False``
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index 29f843123f8560..ccb362d8c31ddf 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -62,6 +62,13 @@ an event loop:
    .. versionchanged:: 3.14
       Raises a :exc:`RuntimeError` if there is no current event loop.
 
+   .. note::
+
+      The :mod:`!asyncio` policy system is deprecated and will be removed
+      in Python 3.16; from there on, this function will always return the
+      running event loop.
+
+
 .. function:: set_event_loop(loop)
 
    Set *loop* as the current event loop for the current OS thread.
@@ -1781,12 +1788,11 @@ By default asyncio is configured to use :class:`EventLoop`.
       import asyncio
       import selectors
 
-      class MyPolicy(asyncio.DefaultEventLoopPolicy):
-         def new_event_loop(self):
-            selector = selectors.SelectSelector()
-            return asyncio.SelectorEventLoop(selector)
+      async def main():
+         ...
 
-      asyncio.set_event_loop_policy(MyPolicy())
+      loop_factory = lambda: asyncio.SelectorEventLoop(selectors.SelectSelector())
+      asyncio.run(main(), loop_factory=loop_factory)
 
 
    .. availability:: Unix, Windows.
diff --git a/Doc/library/asyncio-runner.rst b/Doc/library/asyncio-runner.rst
index 28d5aaf3692baa..48d78099fd3ce7 100644
--- a/Doc/library/asyncio-runner.rst
+++ b/Doc/library/asyncio-runner.rst
@@ -76,6 +76,12 @@ Running an asyncio Program
 
       *coro* can be any awaitable object.
 
+   .. note::
+
+      The :mod:`!asyncio` policy system is deprecated and will be removed
+      in Python 3.16; from there on, an explicit *loop_factory* is needed
+      to configure the event loop.
+
 
 Runner context manager
 ======================