gh-145342: Adapt guest mode to current main and fix docs CI

- test_guest: use asyncio.set_event_loop(None) in tearDownModule; the
  event loop policy system was removed on main.
- Docs: de-duplicate the poll_events/process_events/process_ready
  reference entries (keep asyncio-eventloop.rst as the canonical
  location), fix cross-references to the loop.* targets, bump
  versionadded to 3.16, and add a What's New entry.

Author: congzhangzh

Doc/library/asyncio-eventloop.rst

@@ -210,27 +210,40 @@ Running and stopping the loop
 Decomposing event loop iteration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The following methods decompose a single :meth:`~asyncio.BaseEventLoop._run_once`
-iteration into independently callable steps.  They are used internally by
-:func:`asyncio.start_guest_run`; see :ref:`asyncio-guest` for full documentation.
+The following methods decompose a single iteration of the event loop
+into independently callable steps.  They are used internally by
+:func:`asyncio.start_guest_run`; see :ref:`asyncio-guest` for full
+documentation.
 
 .. method:: loop.poll_events()
 
-   Poll for I/O events and return the raw event list.
+   Poll for I/O events without processing them.
 
-   .. versionadded:: 3.15
+   Cleans up cancelled scheduled handles, computes an appropriate
+   timeout from the scheduled callbacks, and calls the underlying
+   selector.  Returns the raw event list.
+
+   .. versionadded:: 3.16
 
 .. method:: loop.process_events(event_list)
 
    Process I/O events returned by :meth:`poll_events`.
 
-   .. versionadded:: 3.15
+   Delegates to the selector-specific event processing that turns raw
+   selector events into ready callbacks.
+
+   .. versionadded:: 3.16
 
 .. method:: loop.process_ready()
 
    Process expired timers and execute ready callbacks.
 
-   .. versionadded:: 3.15
+   Moves scheduled callbacks whose deadline has passed into the ready
+   queue, then runs all callbacks that were ready at call time.
+   Callbacks enqueued *by* running callbacks are left for the next
+   iteration.
+
+   .. versionadded:: 3.16
 
 Scheduling callbacks
 ^^^^^^^^^^^^^^^^^^^^

Doc/library/asyncio-guest.rst

@@ -22,9 +22,11 @@ replacing the host loop, asyncio piggybacks on it:
   When I/O events arrive it hands them back to the host thread via a
   thread-safe callback.  The thread is not a daemon thread; it is joined
   when the guest run finishes.
-* The host thread then runs :meth:`~asyncio.BaseEventLoop.process_events`
-  and :meth:`~asyncio.BaseEventLoop.process_ready` to advance the asyncio
-  event loop by one step, then signals the I/O thread to poll again.
+* The host thread then runs
+  :meth:`loop.process_events() <asyncio.loop.process_events>` and
+  :meth:`loop.process_ready() <asyncio.loop.process_ready>` to advance
+  the asyncio event loop by one step, then signals the I/O thread to
+  poll again.
 
 Exactly one of the two threads touches the event loop at any moment, so
 neither the host loop nor the asyncio loop starves the other.
@@ -74,7 +76,7 @@ example that embeds asyncio inside ``tkinter.mainloop()`` using
    This wakes the I/O thread from its selector wait so cancellation is
    processed promptly.
 
-   .. versionadded:: 3.15
+   .. versionadded:: 3.16
 
 .. _asyncio-guest-lifecycle:
 
@@ -128,40 +130,10 @@ Host Requirements
 
 .. rubric:: Low-level Event Loop Methods
 
-The following three methods on :class:`BaseEventLoop` are used internally by
-:func:`start_guest_run`.  They decompose :meth:`~BaseEventLoop._run_once`
-into independently callable steps and are documented here for completeness.
-
-.. method:: loop.poll_events()
-
-   Poll for I/O events without processing them.
-
-   Cleans up cancelled scheduled handles, computes an appropriate timeout
-   from the scheduled callbacks, and calls the underlying selector.  Returns
-   the raw event list.
-
-   Together with :meth:`~BaseEventLoop.process_events` and
-   :meth:`~BaseEventLoop.process_ready`, this method decomposes
-   :meth:`~BaseEventLoop._run_once` into independently callable steps so that
-   an external event loop can drive asyncio (see :func:`start_guest_run`).
-
-   .. versionadded:: 3.15
-
-.. method:: loop.process_events(event_list)
-
-   Process I/O events returned by :meth:`~BaseEventLoop.poll_events`.
-
-   Delegates to the selector-specific ``_process_events`` implementation
-   which turns raw selector events into ready callbacks.
-
-   .. versionadded:: 3.15
-
-.. method:: loop.process_ready()
-
-   Process expired timers and execute ready callbacks.
-
-   Moves scheduled callbacks whose deadline has passed into the ready queue,
-   then runs all callbacks that were ready at call time.  Callbacks enqueued
-   *by* running callbacks are left for the next iteration.
-
-   .. versionadded:: 3.15
+:func:`start_guest_run` drives the loop through three low-level methods
+-- :meth:`loop.poll_events() <asyncio.loop.poll_events>`,
+:meth:`loop.process_events() <asyncio.loop.process_events>`, and
+:meth:`loop.process_ready() <asyncio.loop.process_ready>` -- which
+decompose a single iteration of the event loop into independently
+callable steps.  See :ref:`asyncio-event-loop` for their reference
+documentation.

Doc/whatsnew/3.16.rst

@@ -109,6 +109,11 @@ asyncio
   socket file created for *path*.
   (Contributed by Sam Bull in :gh:`94984`.)
 
+* Add :func:`asyncio.start_guest_run` to run asyncio cooperatively inside
+  a host event loop, such as a GUI toolkit's main loop, that owns the
+  thread.  See :ref:`asyncio-guest`.
+  (Contributed by Cong Zhang in :gh:`145342`.)
+
 
 codecs
 ------

Lib/asyncio/base_events.py

@@ -2005,7 +2005,7 @@ def poll_events(self):
         independently callable steps so that an external event loop can
         drive asyncio (see :func:`asyncio.start_guest_run`).
 
-        .. versionadded:: 3.15
+        .. versionadded:: 3.16
         """
         sched_count = len(self._scheduled)
         if (sched_count > _MIN_SCHEDULED_TIMER_HANDLES and
@@ -2050,7 +2050,7 @@ def process_events(self, event_list):
         implementation which turns raw selector events into ready
         callbacks.
 
-        .. versionadded:: 3.15
+        .. versionadded:: 3.16
         """
         self._process_events(event_list)
 
@@ -2062,7 +2062,7 @@ def process_ready(self):
         time.  Callbacks enqueued *by* running callbacks are left for
         the next iteration.
 
-        .. versionadded:: 3.15
+        .. versionadded:: 3.16
         """
         # Handle 'later' callbacks that are ready.
         now = self.time()

Lib/test/test_asyncio/test_guest.py

@@ -15,7 +15,7 @@
 
 
 def tearDownModule():
-    asyncio.events._set_event_loop_policy(None)
+    asyncio.set_event_loop(None)
 
 
 class MockHost:

Misc/NEWS.d/next/Library/2026-02-28-14-00-00.gh-issue-145342.GuestMode.rst

@@ -3,10 +3,10 @@ inside a host event loop (e.g. Tkinter, Qt, GTK). The host loop retains
 control of its thread while asyncio I/O polling runs in a background
 non-daemon thread that is joined when the run finishes. In guest mode the
 host owns signal handling: the loop never touches
-:func:`signal.set_wakeup_fd` and :meth:`loop.add_signal_handler` raises
-:exc:`RuntimeError`. Also adds three low-level
-:class:`~asyncio.BaseEventLoop` methods --
-:meth:`~asyncio.BaseEventLoop.poll_events`,
-:meth:`~asyncio.BaseEventLoop.process_events`, and
-:meth:`~asyncio.BaseEventLoop.process_ready` -- that decompose
-:meth:`~asyncio.BaseEventLoop._run_once` into independently callable steps.
+:func:`signal.set_wakeup_fd` and :meth:`loop.add_signal_handler
+<asyncio.loop.add_signal_handler>` raises :exc:`RuntimeError`. Also adds
+three low-level event loop methods -- :meth:`loop.poll_events
+<asyncio.loop.poll_events>`, :meth:`loop.process_events
+<asyncio.loop.process_events>`, and :meth:`loop.process_ready
+<asyncio.loop.process_ready>` -- that decompose a single iteration of the
+event loop into independently callable steps.