Merge in the main branch

Author: encukou

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/library/functions.rst

@@ -1107,13 +1107,13 @@ are always available.  They are listed here in alphabetical order.
       *classinfo* can be a :ref:`types-union`.
 
 
-.. function:: issubclass(class, classinfo, /)
+.. function:: issubclass(cls, classinfo, /)
 
-   Return ``True`` if *class* is a subclass (direct, indirect, or :term:`virtual
+   Return ``True`` if *cls* is a subclass (direct, indirect, or :term:`virtual
    <abstract base class>`) of *classinfo*.  A
    class is considered a subclass of itself. *classinfo* may be a tuple of class
    objects (or recursively, other such tuples)
-   or a :ref:`types-union`, in which case return ``True`` if *class* is a
+   or a :ref:`types-union`, in which case return ``True`` if *cls* is a
    subclass of any entry in *classinfo*.  In any other case, a :exc:`TypeError`
    exception is raised.
 

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

@@ -788,15 +788,14 @@ also be used to improve performance.
    pointers to ``BASECFLAGS``:
 
    - ``-fno-omit-frame-pointer`` and/or ``-mno-omit-leaf-frame-pointer``
-     are added when the compiler supports them,
+     are added when the compiler supports them.
    - ``-marm`` and/or ``-mno-thumb`` is added on 32-bit ARM when supported,
-   - on s390x platforms, when supported, ``-mbackchain`` is added *instead*
-     of the above frame pointer flags
+   - 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
+   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.
 

Doc/whatsnew/3.15.rst

@@ -81,6 +81,7 @@ Summary -- Release highlights
   <whatsnew315-unpacking-in-comprehensions>`
 * :pep:`686`: :ref:`Python now uses UTF-8 as the default encoding
   <whatsnew315-utf8-default>`
+* :pep:`829`: :ref:`Package startup configuration files <whatsnew315-startup-files>`
 * :pep:`728`: :ref:`TypedDict with typed extra items <whatsnew315-typeddict>`
 * :pep:`747`: :ref:`Annotating type forms with TypeForm
   <whatsnew315-typeform>`
@@ -94,7 +95,6 @@ Summary -- Release highlights
 * :ref:`Improved error messages <whatsnew315-improved-error-messages>`
 * :ref:`The official Windows 64-bit binaries now use the tail-calling interpreter
   <whatsnew315-windows-tail-calling-interpreter>`
-* :pep:`829`: Package Startup Configuration Files
 
 New features
 ============
@@ -452,6 +452,31 @@ agen() for x in a)``.
 
 (Contributed by Adam Hartz in :gh:`143055`.)
 
+.. _whatsnew315-startup-files:
+
+:pep:`829`: Package startup configuration files
+-----------------------------------------------
+
+Loaded by the :mod:`site` module when ``-S`` is not given, :ref:`.pth files <site-pth-files>`
+can contain lines that both extend :data:`sys.path` and execute arbitrary code
+when the line starts with ``import`` (followed by a space or tab).  The latter
+functionality can be problematic, since it is difficult to know exactly what
+gets executed when Python starts up.
+
+As a step towards improving the ability to audit pre-start executable code,
+Python 3.15 introduces :ref:`.start files <site-start-files>` which contain entry point
+specifications of the form ``pkg.mod:callable`` where ``pkg.mod`` is the
+import path to the given callable.  When Python starts up, the callable is
+located and called with no arguments.
+
+``import`` lines in :file:`.pth` files are silently deprecated.  When a
+matching :file:`.start` file is found, ``import`` lines in :file:`.pth` files
+are ignored.  There is no change to :data:`sys.path` extension lines in
+:file:`.pth` files.
+
+(Contributed by Barry Warsaw in :gh:`148641`.)
+
+
 .. _whatsnew315-abi3t:
 
 :pep:`803` -- Stable ABI for Free-Threaded Builds
@@ -627,6 +652,11 @@ Other language changes
 
   (Contributed by Adam Turner in :gh:`133711`; PEP 686 written by Inada Naoki.)
 
+* The interpreter help (such as ``python --help``) is now in color.
+  This can be controlled by :ref:`environment variables
+  <using-on-controlling-color>`.
+  (Contributed by Hugo van Kemenade in :gh:`148766`.)
+
 * Unraisable exceptions are now highlighted with color by default. This can be
   controlled by :ref:`environment variables <using-on-controlling-color>`.
   (Contributed by Peter Bierma in :gh:`134170`.)
@@ -1663,13 +1693,31 @@ wave
 (Contributed by Lionel Koenig and Michiel W. Beijen in :gh:`60729`.)
 
 
+webbrowser
+----------
+
+* On macOS, the new :class:`!webbrowser.MacOS` class opens URLs via
+  :program:`/usr/bin/open` instead of constructing and executing AppleScript
+  via :program:`osascript`. The default browser is detected from the
+  LaunchServices preferences file using :mod:`plistlib`, with
+  :class:`!com.apple.Safari` as the fallback on fresh installations.
+  For non-HTTP(S) URLs, :program:`open -b <bundle-id>` is used to route the
+  URL through a browser rather than the OS file handler, preventing
+  file injection attacks.
+  (Contributed by Jeff Lyon in :gh:`137586`.)
+
+
 xml
 ---
 
 * Add the :func:`xml.is_valid_name` function, which allows to check
   whether a string can be used as an element or attribute name in XML.
   (Contributed by Serhiy Storchaka in :gh:`139489`.)
 
+* Add the :func:`xml.is_valid_text` function, which allows to check
+  whether a string can be used in the XML document.
+  (Contributed by Serhiy Storchaka in :gh:`139489`.)
+
 
 xml.parsers.expat
 -----------------
@@ -2059,6 +2107,13 @@ New deprecations
     (Contributed by kishorhange111 in :gh:`148849`.)
 
 
+* :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* explicitly close the current file.
+
+
 * :mod:`re`:
 
   * :func:`re.match` and :meth:`re.Pattern.match` are now
@@ -2102,6 +2157,12 @@ New deprecations
     merely imported or accessed from the :mod:`!typing` module.
 
 
+* :mod:`webbrowser`:
+
+  * :class:`!webbrowser.MacOSXOSAScript` is deprecated in favour of
+    :class:`!webbrowser.MacOS` and scheduled for removal in Python 3.17.
+    (Contributed by Jeff Lyon in :gh:`137586`.)
+
 * ``__version__``
 
   * The ``__version__``, ``version`` and ``VERSION`` attributes have been
@@ -2291,6 +2352,11 @@ New features
   Python 3.14.
   (Contributed by Victor Stinner in :gh:`142417`.)
 
+* Add :c:func:`PyUnstable_DumpTraceback` and
+  :c:func:`PyUnstable_DumpTracebackThreads` functions to output Python
+  stacktraces.
+  (Contributed by Alex Malyshev in :gh:`145559`.)
+
 Changed C APIs
 --------------
 

Include/cpython/traceback.h

@@ -11,3 +11,11 @@ struct _traceback {
     int tb_lasti;
     int tb_lineno;
 };
+
+PyAPI_FUNC(const char*) PyUnstable_DumpTraceback(int fd, PyThreadState *tstate);
+
+PyAPI_FUNC(const char*) PyUnstable_DumpTracebackThreads(
+    int fd,
+    PyInterpreterState *interp,
+    PyThreadState *current_tstate,
+    Py_ssize_t max_threads);