Merge branch 'python:main' into main

Author: Santhosh-I

.github/workflows/build.yml

@@ -361,23 +361,14 @@ jobs:
     needs: build-context
     if: needs.build-context.outputs.run-ios == 'true'
     timeout-minutes: 60
-    runs-on: macos-14
+    runs-on: macos-26
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
 
-      # GitHub recommends explicitly selecting the desired Xcode version:
-      # https://github.com/actions/runner-images/issues/12541#issuecomment-3083850140
-      # This became a necessity as a result of
-      # https://github.com/actions/runner-images/issues/12541 and
-      # https://github.com/actions/runner-images/issues/12751.
-      - name: Select Xcode version
-        run: |
-          sudo xcode-select --switch /Applications/Xcode_15.4.app
-
       - name: Build and test
-        run: python3 Platforms/Apple ci iOS --fast-ci --simulator 'iPhone SE (3rd generation),OS=17.5'
+        run: python3 Platforms/Apple ci iOS --fast-ci
 
   build-emscripten:
     name: 'Emscripten'
@@ -554,6 +545,7 @@ jobs:
         - Thread
         free-threading:
         - false
+        - true
         sanitizer:
         - TSan
         include:
@@ -565,17 +557,6 @@ jobs:
       sanitizer: ${{ matrix.sanitizer }}
       free-threading: ${{ matrix.free-threading }}
 
-  # XXX: Temporarily allow this job to fail to not block PRs.
-  build-san-free-threading:
-    # ${{ '' } is a hack to nest jobs under the same sidebar category.
-    name: Sanitizers${{ '' }}  # zizmor: ignore[obfuscation]
-    needs: build-context
-    if: needs.build-context.outputs.run-ubuntu == 'true'
-    uses: ./.github/workflows/reusable-san.yml
-    with:
-      sanitizer: TSan
-      free-threading: true
-
   cross-build-linux:
     name: Cross build Linux
     runs-on: ubuntu-26.04
@@ -679,7 +660,6 @@ jobs:
     - test-hypothesis
     - build-asan
     - build-san
-    - build-san-free-threading
     - cross-build-linux
     - cifuzz
     if: always()
@@ -691,7 +671,6 @@ jobs:
         allowed-failures: >-
           build-android,
           build-emscripten,
-          build-san-free-threading,
           build-windows-msi,
           build-ubuntu-ssltests,
           test-hypothesis,

Doc/c-api/float.rst

@@ -233,9 +233,6 @@ most likely :exc:`OverflowError`).
 
    Pack a C double as the IEEE 754 binary64 double precision format.
 
-   .. impl-detail::
-      This function always succeeds in CPython.
-
 
 Unpack functions
 ^^^^^^^^^^^^^^^^
@@ -251,9 +248,6 @@ Return value: The unpacked double.  On error, this is ``-1.0`` and
 :c:func:`PyErr_Occurred` is true (and an exception is set, most likely
 :exc:`OverflowError`).
 
-.. impl-detail::
-    These functions always succeed in CPython.
-
 .. c:function:: double PyFloat_Unpack2(const char *p, int le)
 
    Unpack the IEEE 754 binary16 half-precision format as a C double.

Doc/deprecations/pending-removal-in-3.19.rst

@@ -40,3 +40,11 @@ Pending removal in Python 3.19
     Before Python 3.14, this property was used to implement the corresponding
     ``read()`` and ``readline()`` methods for :class:`~imaplib.IMAP4` but this
     is no longer the case since then.
+
+* :mod:`tkinter`:
+
+  * :func:`tkinter.filedialog.askopenfiles` has been deprecated since Python
+    3.16.  Iterate over the names returned by
+    :func:`~tkinter.filedialog.askopenfilenames` and open them one by one
+    instead.
+    (Contributed by Serhiy Storchaka in :gh:`152638`.)

Doc/library/asyncio-eventloop.rst

@@ -1145,12 +1145,21 @@ convenient.
 
    *sock* must be a non-blocking socket.
 
+   With :class:`SelectorEventLoop`, *address* does not need to be resolved:
+   for :const:`~socket.AF_INET` and :const:`~socket.AF_INET6` sockets,
+   ``sock_connect`` first checks whether *address* is already resolved by
+   calling :func:`socket.inet_pton`, and uses :meth:`loop.getaddrinfo` to
+   resolve it if it is not.
+
+   :class:`ProactorEventLoop`, the default event loop on Windows, does not
+   resolve *address*.  The host must already be a numeric IP address; passing
+   a host name raises :exc:`OSError`.  Resolve the address with
+   :meth:`loop.getaddrinfo` first, or use :meth:`loop.create_connection`,
+   which resolves the address on every platform.
+
    .. versionchanged:: 3.5.2
-      ``address`` no longer needs to be resolved.  ``sock_connect``
-      will try to check if the *address* is already resolved by calling
-      :func:`socket.inet_pton`.  If not,
-      :meth:`loop.getaddrinfo` will be used to resolve the
-      *address*.
+      With :class:`SelectorEventLoop`, ``address`` no longer needs to be
+      resolved.
 
    .. seealso::
 
@@ -1254,7 +1263,9 @@ Working with pipes
    *protocol_factory* must be a callable returning an
    :ref:`asyncio protocol <asyncio-protocol>` implementation.
 
-   *pipe* is a :term:`file-like object <file object>`.
+   *pipe* is a :term:`file-like object <file object>`.  See
+   :ref:`Supported pipe objects <asyncio-pipe-objects>` for the objects
+   supported as *pipe*.
 
    Return pair ``(transport, protocol)``, where *transport* supports
    the :class:`ReadTransport` interface and *protocol* is an object
@@ -1271,7 +1282,9 @@ Working with pipes
    *protocol_factory* must be a callable returning an
    :ref:`asyncio protocol <asyncio-protocol>` implementation.
 
-   *pipe* is :term:`file-like object <file object>`.
+   *pipe* is a :term:`file-like object <file object>`.  See
+   :ref:`Supported pipe objects <asyncio-pipe-objects>` for the objects
+   supported as *pipe*.
 
    Return pair ``(transport, protocol)``, where *transport* supports
    :class:`WriteTransport` interface and *protocol* is an object
@@ -1280,6 +1293,33 @@ Working with pipes
    With :class:`SelectorEventLoop` event loop, the *pipe* is set to
    non-blocking mode.
 
+.. _asyncio-pipe-objects:
+
+.. rubric:: Supported pipe objects
+
+These methods only work with objects the operating system can poll for
+readiness or perform overlapped I/O on.  Regular files on disk are **not**
+supported on any platform.  There is no asynchronous file I/O in asyncio;
+use :meth:`loop.run_in_executor` to read and write regular files without
+blocking the event loop.
+
+On Unix, with :class:`SelectorEventLoop`, *pipe* must wrap one of the
+following:
+
+* a pipe, such as an end of an :func:`os.pipe` pair or a FIFO created with
+  :func:`os.mkfifo`;
+* a socket;
+* a character device, such as a terminal.
+
+On Windows, where only :class:`ProactorEventLoop` implements these methods,
+*pipe* must wrap a handle opened for overlapped I/O (that is, created with the
+``FILE_FLAG_OVERLAPPED`` flag), since the handle has to be associated with an
+I/O completion port.  Handles that were not opened for overlapped I/O are
+rejected.  In particular, the standard streams (:data:`sys.stdin`,
+:data:`sys.stdout` and :data:`sys.stderr`), console handles, and the pipes
+created by :func:`os.pipe` are **not** opened for overlapped I/O and therefore
+cannot be used with these methods.
+
 .. note::
 
    :class:`SelectorEventLoop` does not support the above methods on

Doc/library/asyncio-platforms.rst

@@ -19,6 +19,11 @@ All Platforms
 * :meth:`loop.add_reader` and :meth:`loop.add_writer`
   cannot be used to monitor file I/O.
 
+* :meth:`loop.connect_read_pipe` and :meth:`loop.connect_write_pipe`
+  cannot be used with regular files.  See :ref:`Supported pipe objects
+  <asyncio-pipe-objects>` for the objects that are accepted on each
+  platform.
+
 
 Windows
 =======
@@ -62,6 +67,10 @@ All event loops on Windows do not support the following methods:
 * The :meth:`loop.add_reader` and :meth:`loop.add_writer`
   methods are not supported.
 
+* :meth:`loop.connect_read_pipe` and :meth:`loop.connect_write_pipe` only
+  accept a handle opened for overlapped I/O.
+  See :ref:`Supported pipe objects <asyncio-pipe-objects>` for which objects are supported.
+
 The resolution of the monotonic clock on Windows is usually around 15.6
 milliseconds.  The best resolution is 0.5 milliseconds. The resolution depends on the
 hardware (availability of `HPET

Doc/library/asyncio-queue.rst

@@ -71,6 +71,8 @@ Queue
       Return an item if one is immediately available, else raise
       :exc:`QueueEmpty`.
 
+      Raises :exc:`QueueShutDown` if the queue has been shut down and is empty.
+
    .. method:: join()
       :async:
 
@@ -96,6 +98,8 @@ Queue
 
       If no free slot is immediately available, raise :exc:`QueueFull`.
 
+      Raises :exc:`QueueShutDown` if the queue has been shut down.
+
    .. method:: qsize()
 
       Return the number of items in the queue.
@@ -188,8 +192,9 @@ Exceptions
 
 .. exception:: QueueShutDown
 
-   Exception raised when :meth:`~Queue.put` or :meth:`~Queue.get` is
-   called on a queue which has been shut down.
+   Exception raised when :meth:`~Queue.put`, :meth:`~Queue.put_nowait`,
+   :meth:`~Queue.get` or :meth:`~Queue.get_nowait` is called
+   on a queue which has been shut down.
 
    .. versionadded:: 3.13
 

Doc/library/asyncio-task.rst

@@ -924,6 +924,9 @@ Waiting primitives
    Unlike :func:`~asyncio.wait_for`, ``wait()`` does not cancel the
    futures when a timeout occurs.
 
+   If ``wait()`` is cancelled, the futures in *aws* are not cancelled
+   and continue to run.
+
    .. versionchanged:: 3.10
       Removed the *loop* parameter.
 
@@ -981,6 +984,10 @@ Waiting primitives
    are done. This is raised by the ``async for`` loop during asynchronous
    iteration or by the coroutines yielded during plain iteration.
 
+   ``as_completed()`` does not cancel the tasks running the supplied
+   awaitables: if a timeout occurs or the iteration is cancelled, the
+   remaining tasks continue to run.
+
    .. versionchanged:: 3.10
       Removed the *loop* parameter.
 

Doc/library/asyncio-tools.rst

@@ -24,7 +24,7 @@ The following commands inspect the process identified by ``PID``:
 
 The commands read the target process state without executing any code in it.
 They are only available on supported platforms and may require permission to
-inspect another process.  See the :ref:`permission-requirements <permission-requirements>` for details.
+inspect another process.  See the :ref:`permission requirements <permission-requirements>` for details.
 
 .. seealso::
 

Doc/library/codecs.rst

@@ -1087,6 +1087,18 @@ On Windows, ``cpXXX`` codecs are available for all code pages.
 But only codecs listed in the following table are guaranteed to exist on
 other platforms.
 
+On platforms that provide the C library's :manpage:`iconv(3)` function
+(such as those using the GNU C Library),
+every encoding known to ``iconv`` for which Python has no built-in codec
+is available as well.
+Such an encoding is looked up by its ``iconv`` name (for example ``cp1133``).
+Prefixing the name with ``iconv:`` forces the use of the ``iconv``-based codec
+even when a built-in codec of the same name exists (for example ``iconv:latin1``),
+which is mostly useful for testing.
+
+.. versionchanged:: next
+   Added support for encodings provided by the C library's ``iconv``.
+
 .. impl-detail::
 
    Some common encodings can bypass the codecs lookup machinery to

Doc/library/dialog.rst

@@ -163,15 +163,23 @@ cancelled it is the empty value documented for that function -- an empty
 string, an empty tuple, an empty list or ``None``.
 
 .. function:: askopenfile(mode="r", **options)
-              askopenfiles(mode="r", **options)
 
-   Create an :class:`Open` dialog.
-   :func:`askopenfile` returns the opened file object, or ``None`` if the
-   dialog is cancelled.
-   :func:`askopenfiles` returns a list of the opened file objects, or an empty
-   list if cancelled.
+   Create an :class:`Open` dialog and return the opened file object,
+   or ``None`` if the dialog is cancelled.
+   The file is opened in mode *mode* (read-only ``'r'`` by default).
+
+.. function:: askopenfiles(mode="r", **options)
+
+   Create an :class:`Open` dialog and return a list of the opened file objects,
+   or an empty list if cancelled.
    The files are opened in mode *mode* (read-only ``'r'`` by default).
 
+   .. deprecated-removed:: next 3.19
+      Opening several files at once is error-prone,
+      and the returned list cannot be used in a :keyword:`with` statement.
+      Iterate over the names returned by :func:`askopenfilenames`
+      and open them one by one instead.
+
 .. function:: asksaveasfile(mode="w", **options)
 
    Create a :class:`SaveAs` dialog and return the opened file object, or
@@ -201,19 +209,16 @@ string, an empty tuple, an empty list or ``None``.
 
 .. class:: Open(master=None, **options)
            SaveAs(master=None, **options)
+           Directory(master=None, **options)
 
-   The above two classes provide native dialog windows for saving and loading
-   files.
+   The above three classes provide native dialog windows for loading and saving
+   files and for selecting a directory.
 
 **Convenience classes**
 
 The below classes are used for creating file/directory windows from scratch.
 These do not emulate the native look-and-feel of the platform.
 
-.. class:: Directory(master=None, **options)
-
-   Create a dialog prompting the user to select a directory.
-
 .. note::  The *FileDialog* class should be subclassed for custom event
    handling and behaviour.
 
@@ -353,23 +358,25 @@ the classic (non-themed) Tk widgets.
 
 .. data:: DIALOG_ICON
 
-   The name of the default bitmap (``'questhead'``) displayed by a
-   :class:`Dialog`.
+   The name of a bitmap (``'questhead'``) suitable for use as the *bitmap*
+   of a :class:`Dialog`.
 
 .. class:: Dialog(master=None, cnf={}, **kw)
 
    Display a modal dialog box built from the classic (non-themed) Tk widgets
    and wait for the user to press one of its buttons.
-   The options, given through *cnf* or as keyword arguments, include *title*
-   (the window title), *text* (the message), *bitmap* (an icon,
-   :data:`DIALOG_ICON` by default), *default* (the index of the default button)
-   and *strings* (the sequence of button labels).
+   The options, given through *cnf* or as keyword arguments, are all required:
+   *title* (the window title), *text* (the message), *bitmap* (the name of a
+   bitmap icon, such as :data:`DIALOG_ICON`), *default* (the index of the
+   default button) and *strings* (the sequence of button labels).
    After construction, the :attr:`!num` attribute holds the index of the button
    the user pressed.
 
    .. method:: destroy()
 
-      Destroy the dialog window.
+      Do nothing.
+      The dialog window is destroyed automatically before the constructor
+      returns, so there is nothing left for this method to do.
 
 
 .. seealso::