From 3eb746a7b9122c7c3cfc3fbd41d9d079d8b02845 Mon Sep 17 00:00:00 2001
From: Kumar Aditya <kumaraditya@python.org>
Date: Thu, 26 Dec 2024 20:02:23 +0530
Subject: [PATCH] gh-127949: add docs for asyncio policy deprecation (#128269)

---
 Doc/library/asyncio-policy.rst |  8 ++++++++
 Doc/whatsnew/3.14.rst          | 34 ++++++++++++++++++++++++++++++----
 2 files changed, 38 insertions(+), 4 deletions(-)

diff --git a/Doc/library/asyncio-policy.rst b/Doc/library/asyncio-policy.rst
index ea7fe957da7c40..9f86234ce941d1 100644
--- a/Doc/library/asyncio-policy.rst
+++ b/Doc/library/asyncio-policy.rst
@@ -7,6 +7,14 @@
 Policies
 ========
 
+.. warning::
+
+   Policies are deprecated and will be removed in Python 3.16.
+   Users are encouraged to use the :func:`asyncio.run` function
+   or the :class:`asyncio.Runner` with *loop_factory* to use
+   the desired loop implementation.
+
+
 An event loop policy is a global object
 used to get and set the current :ref:`event loop <asyncio-event-loop>`,
 as well as create new event loops.
diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
index 0dcee56b7d233f..935c61c474e889 100644
--- a/Doc/whatsnew/3.14.rst
+++ b/Doc/whatsnew/3.14.rst
@@ -691,10 +691,36 @@ Deprecated
     (Contributed by Serhiy Storchaka in :gh:`58032`.)
 
 * :mod:`asyncio`:
-  :func:`!asyncio.iscoroutinefunction` is deprecated
-  and will be removed in Python 3.16,
-  use :func:`inspect.iscoroutinefunction` instead.
-  (Contributed by Jiahao Li and Kumar Aditya in :gh:`122875`.)
+
+  * :func:`!asyncio.iscoroutinefunction` is deprecated
+    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`:
   Passing a complex number as the *real* or *imag* argument in the