Merge branch 'main' into gh-127794

Author: srinivasreddy

Doc/c-api/object.rst

@@ -111,7 +111,8 @@ Object Protocol
    .. note::
 
       Exceptions that occur when this calls :meth:`~object.__getattr__` and
-      :meth:`~object.__getattribute__` methods are silently ignored.
+      :meth:`~object.__getattribute__` methods aren't propagated,
+      but instead given to :func:`sys.unraisablehook`.
       For proper error handling, use :c:func:`PyObject_HasAttrWithError`,
       :c:func:`PyObject_GetOptionalAttr` or :c:func:`PyObject_GetAttr` instead.
 

Doc/c-api/typeobj.rst

@@ -1023,6 +1023,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the
    :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields in the subtype exist and have
    ``NULL`` values.
+
    .. XXX are most flag bits *really* inherited individually?
 
    **Default:**

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``

Doc/library/asyncio-eventloop.rst

@@ -62,10 +62,21 @@ 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.
 
+   .. deprecated:: next
+      The :func:`set_event_loop` function is deprecated and will be removed
+      in Python 3.16.
+
 .. function:: new_event_loop()
 
    Create and return a new event loop object.
@@ -1777,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.

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.
@@ -87,6 +95,10 @@ The abstract event loop policy base class is defined as follows:
 
       This method should never return ``None``.
 
+   .. deprecated:: next
+      The :class:`AbstractEventLoopPolicy` class is deprecated and
+      will be removed in Python 3.16.
+
 
 .. _asyncio-policy-builtin:
 
@@ -109,6 +121,10 @@ asyncio ships with the following built-in policies:
       The :meth:`get_event_loop` method of the default asyncio policy now
       raises a :exc:`RuntimeError` if there is no set event loop.
 
+   .. deprecated:: next
+      The :class:`DefaultEventLoopPolicy` class is deprecated and
+      will be removed in Python 3.16.
+
 
 .. class:: WindowsSelectorEventLoopPolicy
 
@@ -117,6 +133,10 @@ asyncio ships with the following built-in policies:
 
    .. availability:: Windows.
 
+   .. deprecated:: next
+      The :class:`WindowsSelectorEventLoopPolicy` class is deprecated and
+      will be removed in Python 3.16.
+
 
 .. class:: WindowsProactorEventLoopPolicy
 
@@ -125,6 +145,10 @@ asyncio ships with the following built-in policies:
 
    .. availability:: Windows.
 
+   .. deprecated:: next
+      The :class:`WindowsProactorEventLoopPolicy` class is deprecated and
+      will be removed in Python 3.16.
+
 
 .. _asyncio-custom-policies:
 

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
 ======================

Doc/library/asyncio-task.rst

@@ -1067,14 +1067,59 @@ Scheduling From Other Threads
    This function is meant to be called from a different OS thread
    than the one where the event loop is running.  Example::
 
-     # Create a coroutine
-     coro = asyncio.sleep(1, result=3)
-
-     # Submit the coroutine to a given loop
-     future = asyncio.run_coroutine_threadsafe(coro, loop)
-
-     # Wait for the result with an optional timeout argument
-     assert future.result(timeout) == 3
+     def in_thread(loop: asyncio.AbstractEventLoop) -> None:
+         # Run some blocking IO
+         pathlib.Path("example.txt").write_text("hello world", encoding="utf8")
+
+         # Create a coroutine
+         coro = asyncio.sleep(1, result=3)
+
+         # Submit the coroutine to a given loop
+         future = asyncio.run_coroutine_threadsafe(coro, loop)
+
+         # Wait for the result with an optional timeout argument
+         assert future.result(timeout=2) == 3
+
+     async def amain() -> None:
+         # Get the running loop
+         loop = asyncio.get_running_loop()
+
+         # Run something in a thread
+         await asyncio.to_thread(in_thread, loop)
+
+   It's also possible to run the other way around.  Example::
+
+     @contextlib.contextmanager
+     def loop_in_thread() -> Generator[asyncio.AbstractEventLoop]:
+         loop_fut = concurrent.futures.Future[asyncio.AbstractEventLoop]()
+         stop_event = asyncio.Event()
+
+         async def main() -> None:
+             loop_fut.set_result(asyncio.get_running_loop())
+             await stop_event.wait()
+
+         with concurrent.futures.ThreadPoolExecutor(1) as tpe:
+             complete_fut = tpe.submit(asyncio.run, main())
+             for fut in concurrent.futures.as_completed((loop_fut, complete_fut)):
+                 if fut is loop_fut:
+                     loop = loop_fut.result()
+                     try:
+                         yield loop
+                     finally:
+                         loop.call_soon_threadsafe(stop_event.set)
+                 else:
+                     fut.result()
+
+     # Create a loop in another thread
+     with loop_in_thread() as loop:
+         # Create a coroutine
+         coro = asyncio.sleep(1, result=3)
+
+         # Submit the coroutine to a given loop
+         future = asyncio.run_coroutine_threadsafe(coro, loop)
+
+         # Wait for the result with an optional timeout argument
+         assert future.result(timeout=2) == 3
 
    If an exception is raised in the coroutine, the returned Future
    will be notified.  It can also be used to cancel the task in

Doc/library/calendar.rst

@@ -138,6 +138,14 @@ interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
 
    :class:`TextCalendar` instances have the following methods:
 
+   .. method:: formatweek(theweek, w=0)
+
+      Return a single week in a string with no newline. If *w* is provided, it
+      specifies the width of the date columns, which are centered. Depends
+      on the first weekday as specified in the constructor or set by the
+      :meth:`setfirstweekday` method.
+
+
    .. method:: formatmonth(theyear, themonth, w=0, l=0)
 
       Return a month's calendar in a multi-line string. If *w* is provided, it

Doc/library/socket.rst

@@ -674,6 +674,14 @@ Constants
 
   .. availability:: Linux >= 3.9
 
+.. data:: SO_REUSEPORT_LB
+
+   Constant to enable duplicate address and port bindings with load balancing.
+
+  .. versionadded:: next
+
+  .. availability:: FreeBSD >= 12.0
+
 .. data:: AF_HYPERV
           HV_PROTOCOL_RAW
           HVSOCKET_CONNECT_TIMEOUT

Doc/library/ssl.rst

@@ -934,6 +934,12 @@ Constants
 
    .. versionadded:: 3.13
 
+.. data:: HAS_PHA
+
+   Whether the OpenSSL library has built-in support for TLS-PHA.
+
+   .. versionadded:: next
+
 .. data:: CHANNEL_BINDING_TYPES
 
    List of supported TLS channel binding types.  Strings in this list