Merge remote-tracking branch 'upstream/main' into 3.15-whatsnew

Author: hugovk

.github/workflows/mypy.yml

@@ -71,7 +71,8 @@ jobs:
           persist-credentials: false
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
-          python-version: "3.13"
+          python-version: "3.15"
+          allow-prereleases: true
           cache: pip
           cache-dependency-path: Tools/requirements-dev.txt
       - run: pip install -r Tools/requirements-dev.txt

.readthedocs.yml

@@ -12,23 +12,47 @@ build:
   tools:
     python: "3"
 
-  commands:
-    # https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition
-    #
-    # Cancel building pull requests when there aren't changes in the Doc directory.
-    #
-    # If there are no changes (git diff exits with 0) we force the command to return with 183.
-    # This is a special exit code on Read the Docs that will cancel the build immediately.
-    - |
-      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && [ "$(git diff --quiet origin/main -- Doc/ .readthedocs.yml; echo $?)" -eq 0 ];
-      then
-        echo "No changes to Doc/ - exiting the build.";
-        exit 183;
-      fi
-
-    - asdf plugin add uv
-    - asdf install uv latest
-    - asdf global uv latest
-    - make -C Doc venv html
-    - mkdir _readthedocs
-    - mv Doc/build/html _readthedocs/html
+  jobs:
+    post_checkout:
+      # https://docs.readthedocs.com/platform/stable/guides/build/skip-build.html#skip-builds-based-on-conditions
+      #
+      # Cancel building pull requests when there aren't changes in the Doc
+      # directory or RTD configuration, or if we can't cleanly merge the base
+      # branch.
+      - |
+        set -eEux;
+        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ];
+        then
+          base_branch=main;
+          git fetch --depth=50 origin $base_branch:origin-$base_branch;
+          for attempt in $(seq 10);
+          do
+            if ! git merge-base HEAD origin-$base_branch;
+            then
+              git fetch --deepen=50 origin $base_branch;
+            else
+              break;
+            fi;
+          done;
+          if ! git -c "user.name=rtd" -c "user.email=no-reply@readthedocs.org" merge --no-stat --no-edit origin-$base_branch;
+          then
+            echo "Unsuccessful merge with '$base_branch' branch, skipping the build";
+            exit 183;
+          fi;
+          if git diff --exit-code --stat origin-$base_branch -- Doc/ .readthedocs.yml;
+          then
+            echo "No changes to Doc/ - skipping the build.";
+            exit 183;
+          fi;
+        fi;
+    create_environment:
+      - echo "Skipping default environment creation"
+    install:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    build:
+      html:
+        - make -C Doc venv html
+        - mkdir -p "$READTHEDOCS_OUTPUT"
+        - mv Doc/build/html "$READTHEDOCS_OUTPUT/"

Doc/c-api/exceptions.rst

@@ -1348,3 +1348,67 @@ Tracebacks
 
    This function returns ``0`` on success, and returns ``-1`` with an
    exception set on failure.
+
+.. c:function:: const char* PyUnstable_DumpTraceback(int fd, PyThreadState *tstate)
+
+   Write a trace of the Python stack in *tstate* into the file *fd*.  The format
+   looks like::
+
+      Traceback (most recent call first):
+        File "xxx", line xxx in <xxx>
+        File "xxx", line xxx in <xxx>
+        ...
+        File "xxx", line xxx in <xxx>
+
+   This function is meant to debug situations such as segfaults, fatal errors,
+   and similar. The file and function names it outputs are encoded to ASCII with
+   backslashreplace and truncated to 500 characters. It writes only the first
+   100 frames; further frames are truncated with the line ``...``.
+
+   This function will return ``NULL`` on success, or an error message on error.
+
+   This function is intended for use in crash scenarios such as signal handlers
+   for SIGSEGV, where the interpreter may be in an inconsistent state. Given
+   that it reads interpreter data structures that may be partially modified, the
+   function might produce incomplete output or it may even crash itself.
+
+   The caller does not need to hold an :term:`attached thread state`, nor does
+   *tstate* need to be attached.
+
+   .. versionadded:: next
+
+.. c:function:: const char* PyUnstable_DumpTracebackThreads(int fd, PyInterpreterState *interp, PyThreadState *current_tstate, Py_ssize_t max_threads)
+
+   Write the traces of all Python threads in *interp* into the file *fd*.
+
+   If *interp* is ``NULL`` then this function will try to identify the current
+   interpreter using thread-specific storage. If it cannot, it will return an
+   error.
+
+   If *current_tstate* is not ``NULL`` then it will be used to identify what the
+   current thread is in the written output. If it is ``NULL`` then this function
+   will identify the current thread using thread-specific storage. It is not an
+   error if the function is unable to get the current Python thread state.
+
+   This function will return ``NULL`` on success, or an error message on error.
+
+   This function is meant to debug debug situations such as segfaults, fatal
+   errors, and similar. It calls :c:func:`PyUnstable_DumpTraceback` for each
+   thread. It only writes the tracebacks of the first *max_threads* threads,
+   further output is truncated with the line ``...``. If *max_threads* is 0, the
+   function will use a default value of 100 for the argument.
+
+   This function is intended for use in crash scenarios such as signal handlers
+   for SIGSEGV, where the interpreter may be in an inconsistent state. Given
+   that it reads interpreter data structures that may be partially modified, the
+   function might produce incomplete output or it may even crash itself.
+
+   The caller does not need to hold an :term:`attached thread state`, nor does
+   *current_tstate* need to be attached.
+
+   .. warning::
+      On the :term:`free-threaded build`, this function is not thread-safe. If
+      another thread deletes its :term:`thread state` while this function is being
+      called, the process will likely crash.
+
+   .. versionadded:: next

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

@@ -37,6 +37,11 @@ Pending removal in Python 3.17
     is deprecated and scheduled for removal in Python 3.17.
     (Contributed by Stan Ulbrych in :gh:`136702`.)
 
+* :mod:`webbrowser`:
+
+  - :class:`!webbrowser.MacOSXOSAScript` is deprecated in favour of
+    :class:`!webbrowser.MacOS`. (:gh:`137586`)
+
 * :mod:`typing`:
 
   - Before Python 3.14, old-style unions were implemented using the private class

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

@@ -31,3 +31,12 @@ Pending removal in Python 3.19
   * :meth:`http.cookies.BaseCookie.js_output` is deprecated and will be
     removed in Python 3.19.
 
+* :mod:`imaplib`:
+
+  * Altering :attr:`IMAP4.file <imaplib.IMAP4.file>` is now deprecated
+    and slated for removal in Python 3.19. This property is now unused
+    and changing its value does not automatically close the current file.
+
+    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.

Doc/howto/perf_profiling.rst

@@ -218,8 +218,8 @@ How to obtain the best results
 ------------------------------
 
 For best results, keep frame pointers enabled. On supported GCC-compatible
-toolchains, CPython builds itself with ``-fno-omit-frame-pointer`` and, when
-available, ``-mno-omit-leaf-frame-pointer`` by default. These flags allow
+toolchains, CPython builds itself with ``-fno-omit-frame-pointer`` and similar
+flags (see :option:`--without-frame-pointers` for details). These flags allow
 profilers to unwind using only the frame pointer and not on DWARF debug
 information. This is because as the code that is interposed to allow ``perf``
 support is dynamically generated it doesn't have any DWARF debugging information

Doc/library/imaplib.rst

@@ -695,6 +695,16 @@ The following attributes are defined on instances of :class:`IMAP4`:
    .. versionadded:: 3.5
 
 
+.. property:: IMAP4.file
+
+   Internal :class:`~io.BufferedReader` associated with the underlying socket.
+   This property is documented for legacy purposes but not part of the public
+   interface. The caller is responsible to ensure that the current file is
+   closed before changing it.
+
+   .. deprecated-removed:: next 3.19
+
+
 .. _imap4-example:
 
 IMAP4 Example

Doc/library/webbrowser.rst

@@ -172,13 +172,15 @@ for the controller classes, all defined in this module.
 +------------------------+-----------------------------------------+-------+
 | ``'windows-default'``  | ``WindowsDefault``                      | \(2)  |
 +------------------------+-----------------------------------------+-------+
-| ``'macosx'``           | ``MacOSXOSAScript('default')``          | \(3)  |
+| ``'macos'``            | ``MacOS('default')``                    | \(3)  |
 +------------------------+-----------------------------------------+-------+
-| ``'safari'``           | ``MacOSXOSAScript('safari')``           | \(3)  |
+| ``'safari'``           | ``MacOS('safari')``                     | \(3)  |
 +------------------------+-----------------------------------------+-------+
-| ``'google-chrome'``    | ``Chrome('google-chrome')``             |       |
+| ``'chrome'``           | ``MacOS('google chrome')``              | \(3)  |
++------------------------+-----------------------------------------+-------+
+| ``'firefox'``          | ``MacOS('firefox')``                    | \(3)  |
 +------------------------+-----------------------------------------+-------+
-| ``'chrome'``           | ``Chrome('chrome')``                    |       |
+| ``'google-chrome'``    | ``Chrome('google-chrome')``             |       |
 +------------------------+-----------------------------------------+-------+
 | ``'chromium'``         | ``Chromium('chromium')``                |       |
 +------------------------+-----------------------------------------+-------+
@@ -221,6 +223,17 @@ Notes:
 .. versionchanged:: 3.13
    Support for iOS has been added.
 
+.. versionadded:: next
+   :class:`!MacOS` has been added as a replacement for :class:`!MacOSXOSAScript`,
+   opening browsers via :program:`/usr/bin/open` instead of :program:`osascript`.
+
+.. deprecated-removed:: next 3.17
+   :class:`!MacOSXOSAScript` is deprecated in favour of :class:`!MacOS`.
+   Using :program:`/usr/bin/open` instead of :program:`osascript` is a
+   security and usability improvement: :program:`osascript` may be blocked
+   on managed systems due to its abuse potential as a general-purpose
+   scripting interpreter.
+
 Here are some simple examples::
 
    url = 'https://docs.python.org/'

Doc/library/xml.rst

@@ -54,7 +54,19 @@ This module also defines utility functions.
    "!", "?", and "=" are forbidden.
    The name cannot start with a digit or a character like "-", ".", and "·".
 
-   ..versionadded:: next
+   .. versionadded:: next
+
+
+.. function:: is_valid_text(data)
+
+   Return ``True`` if the string is a sequence of legal XML 1.0 characters,
+   ``False`` otherwise.
+
+   Almost all characters are permitted in XML 1.0 documents, except C0 control
+   characters (excluding TAB, CR and LF), surrogate characters and special
+   Unicode characters U+FFFE and U+FFFF.
+
+   .. versionadded:: next
 
 
 .. _xml-security:

Doc/using/configure.rst

@@ -784,11 +784,19 @@ also be used to improve performance.
 
    Disable frame pointers, which are enabled by default (see :pep:`831`).
 
-   By default, the build appends ``-fno-omit-frame-pointer`` (and
-   ``-mno-omit-leaf-frame-pointer`` when the compiler supports it) to
-   ``BASECFLAGS`` so profilers, debuggers, and system tracing tools
-   (``perf``, ``eBPF``, ``dtrace``, ``gdb``) can walk the C call stack
-   without DWARF metadata. The flags propagate to third-party C
+   By default, the build appends flags to generate frame or backchain
+   pointers to ``BASECFLAGS``:
+
+   - ``-fno-omit-frame-pointer`` and/or ``-mno-omit-leaf-frame-pointer``
+     are added when the compiler supports them.
+   - ``-marm`` is added on 32-bit ARM when supported,
+   - on s390x platforms, when supported, ``-mbackchain`` is added *instead*.
+     of the above frame pointer flags.
+
+   Frame pointers enable profilers, debuggers, and system tracing tools
+   (``perf``, ``eBPF``, ``dtrace``, ``gdb``) to walk the C call stack
+   without DWARF metadata.
+   The flags propagate to third-party C
    extensions through :mod:`sysconfig`. On compilers that do not
    understand them, the build silently skips them.