Merge branch 'main' into add-gdb-support

Author: diegorusso

.github/workflows/posix-deps-apt.sh

@@ -26,9 +26,16 @@ apt-get -yq --no-install-recommends install \
     xvfb \
     zlib1g-dev
 
-# Workaround missing libmpdec-dev on ubuntu 24.04:
-# https://launchpad.net/~ondrej/+archive/ubuntu/php
-# https://deb.sury.org/
-sudo add-apt-repository ppa:ondrej/php
-apt-get update
-apt-get -yq --no-install-recommends install libmpdec-dev
+# Workaround missing libmpdec-dev on ubuntu 24.04 by building mpdecimal
+# from source. ppa:ondrej/php (launchpad.net) are unreliable 
+# (https://status.canonical.com) so fetch the tarball directly
+# from the upstream host.
+# https://www.bytereef.org/mpdecimal/
+MPDECIMAL_VERSION=4.0.1
+curl -fsSL "https://www.bytereef.org/software/mpdecimal/releases/mpdecimal-${MPDECIMAL_VERSION}.tar.gz" \
+    | tar -xz -C /tmp
+(cd "/tmp/mpdecimal-${MPDECIMAL_VERSION}" \
+    && ./configure --prefix=/usr/local \
+    && make -j"$(nproc)" \
+    && make install)
+ldconfig

Doc/library/email.policy.rst

@@ -403,11 +403,26 @@ added matters.  To illustrate::
    .. attribute:: utf8
 
       If ``False``, follow :rfc:`5322`, supporting non-ASCII characters in
-      headers by encoding them as "encoded words".  If ``True``, follow
-      :rfc:`6532` and use ``utf-8`` encoding for headers.  Messages
+      headers by encoding them as :rfc:`2047` "encoded words".  If ``True``,
+      follow :rfc:`6532` and use ``utf-8`` encoding for headers.  Messages
       formatted in this way may be passed to SMTP servers that support
       the ``SMTPUTF8`` extension (:rfc:`6531`).
 
+      When ``False``, the generator will raise
+      :exc:`~email.errors.HeaderWriteError` if any header includes non-ASCII
+      characters in a context where :rfc:`2047` does not permit encoded words.
+      This particularly applies to mailboxes ("addr-spec") with non-ASCII
+      characters, which can be created via
+      :class:`~email.headerregistry.Address`. To use a mailbox with a non-ASCII
+      domain name with ``utf8=False``, first encode the domain using the
+      third-party :pypi:`idna` or :pypi:`uts46` module or with
+      :mod:`encodings.idna`. It is not possible to use a non-ASCII username
+      ("local-part") in a mailbox when ``utf8=False``.
+
+      .. versionchanged:: 3.15
+         Can trigger the raising of :exc:`~email.errors.HeaderWriteError`.
+         (Earlier versions incorrectly applied :rfc:`2047` in certain contexts,
+         mostly notably in addr-specs.)
 
    .. attribute:: refold_source
 

Doc/library/faulthandler.rst

@@ -31,7 +31,8 @@ tracebacks:
 * Each string is limited to 500 characters.
 * Only the filename, the function name and the line number are
   displayed. (no source code)
-* It is limited to 100 frames and 100 threads.
+* It is limited to 100 frames per thread, and 100 threads
+  (configurable via *max_threads*).
 * The order is reversed: the most recent call is shown first.
 
 By default, the Python traceback is written to :data:`sys.stderr`. To see
@@ -55,16 +56,20 @@ at Python startup.
 Dumping the traceback
 ---------------------
 
-.. function:: dump_traceback(file=sys.stderr, all_threads=True)
+.. function:: dump_traceback(file=sys.stderr, all_threads=True, *, max_threads=100)
 
    Dump the tracebacks of all threads into *file*. If *all_threads* is
-   ``False``, dump only the current thread.
+   ``False``, dump only the current thread. *max_threads* caps the number
+   of threads dumped.
 
    .. seealso:: :func:`traceback.print_tb`, which can be used to print a traceback object.
 
    .. versionchanged:: 3.5
       Added support for passing file descriptor to this function.
 
+   .. versionchanged:: next
+      Added the *max_threads* keyword argument.
+
 
 Dumping the C stack
 -------------------
@@ -100,7 +105,7 @@ instead of the stack, even if the operating system supports dumping stacks.
 Fault handler state
 -------------------
 
-.. function:: enable(file=sys.stderr, all_threads=True, c_stack=True)
+.. function:: enable(file=sys.stderr, all_threads=True, c_stack=True, *, max_threads=100)
 
    Enable the fault handler: install handlers for the :const:`~signal.SIGSEGV`,
    :const:`~signal.SIGFPE`, :const:`~signal.SIGABRT`, :const:`~signal.SIGBUS`
@@ -116,6 +121,8 @@ Fault handler state
    traceback, unless the system does not support it. See :func:`dump_c_stack` for
    more information on compatibility.
 
+   *max_threads* caps the number of threads dumped when a fatal signal fires.
+
    .. versionchanged:: 3.5
       Added support for passing file descriptor to this function.
 
@@ -133,6 +140,9 @@ Fault handler state
    .. versionchanged:: 3.14
       The dump now displays the C stack trace if *c_stack* is true.
 
+   .. versionchanged:: next
+      Added the *max_threads* keyword argument.
+
 .. function:: disable()
 
    Disable the fault handler: uninstall the signal handlers installed by
@@ -146,15 +156,15 @@ Fault handler state
 Dumping the tracebacks after a timeout
 --------------------------------------
 
-.. function:: dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False)
+.. function:: dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False, *, max_threads=100)
 
    Dump the tracebacks of all threads, after a timeout of *timeout* seconds, or
    every *timeout* seconds if *repeat* is ``True``.  If *exit* is ``True``, call
    :c:func:`!_exit` with status=1 after dumping the tracebacks.  (Note
    :c:func:`!_exit` exits the process immediately, which means it doesn't do any
    cleanup like flushing file buffers.) If the function is called twice, the new
    call replaces previous parameters and resets the timeout. The timer has a
-   sub-second resolution.
+   sub-second resolution. *max_threads* caps the number of threads dumped.
 
    The *file* must be kept open until the traceback is dumped or
    :func:`cancel_dump_traceback_later` is called: see :ref:`issue with file
@@ -168,6 +178,9 @@ Dumping the tracebacks after a timeout
    .. versionchanged:: 3.7
       This function is now always available.
 
+   .. versionchanged:: next
+      Added the *max_threads* keyword argument.
+
 .. function:: cancel_dump_traceback_later()
 
    Cancel the last call to :func:`dump_traceback_later`.
@@ -176,11 +189,12 @@ Dumping the tracebacks after a timeout
 Dumping the traceback on a user signal
 --------------------------------------
 
-.. function:: register(signum, file=sys.stderr, all_threads=True, chain=False)
+.. function:: register(signum, file=sys.stderr, all_threads=True, chain=False, *, max_threads=100)
 
    Register a user signal: install a handler for the *signum* signal to dump
    the traceback of all threads, or of the current thread if *all_threads* is
    ``False``, into *file*. Call the previous handler if chain is ``True``.
+   *max_threads* caps the number of threads dumped.
 
    The *file* must be kept open until the signal is unregistered by
    :func:`unregister`: see :ref:`issue with file descriptors <faulthandler-fd>`.
@@ -190,6 +204,9 @@ Dumping the traceback on a user signal
    .. versionchanged:: 3.5
       Added support for passing file descriptor to this function.
 
+   .. versionchanged:: next
+      Added the *max_threads* keyword argument.
+
 .. function:: unregister(signum)
 
    Unregister a user signal: uninstall the handler of the *signum* signal

Doc/library/functools.rst

@@ -468,7 +468,7 @@ The :mod:`!functools` module defines the following functions:
 
    Roughly equivalent to::
 
-      initial_missing = object()
+      initial_missing = sentinel('initial_missing')
 
       def reduce(function, iterable, /, initial=initial_missing):
           it = iter(iterable)

Doc/library/gc.rst

@@ -37,18 +37,11 @@ The :mod:`!gc` module provides the following functions:
 
 .. function:: collect(generation=2)
 
-   Perform a collection.  The optional argument *generation*
+   With no arguments, run a full collection.  The optional argument *generation*
    may be an integer specifying which generation to collect (from 0 to 2).  A
    :exc:`ValueError` is raised if the generation number is invalid. The sum of
    collected objects and uncollectable objects is returned.
 
-   Calling ``gc.collect(0)`` will perform a GC collection on the young generation.
-
-   Calling ``gc.collect(1)`` will perform a GC collection on the young generation
-   and an increment of the old generation.
-
-   Calling ``gc.collect(2)`` or ``gc.collect()`` performs a full collection
-
    The free lists maintained for a number of built-in types are cleared
    whenever a full collection or collection of the highest generation (2)
    is run.  Not all items in some free lists may be freed due to the
@@ -60,6 +53,9 @@ The :mod:`!gc` module provides the following functions:
    .. versionchanged:: 3.14
       ``generation=1`` performs an increment of collection.
 
+   .. versionchanged:: 3.14.5
+      ``generation=1`` performs collection of the middle generation.
+
 
 .. function:: set_debug(flags)
 
@@ -75,20 +71,19 @@ The :mod:`!gc` module provides the following functions:
 
 .. function:: get_objects(generation=None)
 
-
    Returns a list of all objects tracked by the collector, excluding the list
-   returned. If *generation* is not ``None``, return only the objects as follows:
-
-   * 0: All objects in the young generation
-   * 1: No objects, as there is no generation 1 (as of Python 3.14)
-   * 2: All objects in the old generation
+   returned. If *generation* is not ``None``, return only the objects tracked by
+   the collector that are in that generation.
 
    .. versionchanged:: 3.8
       New *generation* parameter.
 
    .. versionchanged:: 3.14
       Generation 1 is removed
 
+   .. versionchanged:: 3.14.5
+      Generation 1 is reintroduced to maintain GC behavior from 3.13.
+
    .. audit-event:: gc.get_objects generation gc.get_objects
 
 .. function:: get_stats()
@@ -124,33 +119,33 @@ The :mod:`!gc` module provides the following functions:
    Set the garbage collection thresholds (the collection frequency). Setting
    *threshold0* to zero disables collection.
 
-   The GC classifies objects into two generations depending on whether they have
-   survived a collection. New objects are placed in the young generation. If an
-   object survives a collection it is moved into the old generation.
-
-   In order to decide when to run, the collector keeps track of the number of object
+   The GC classifies objects into three generations depending on how many
+   collection sweeps they have survived.  New objects are placed in the youngest
+   generation (generation ``0``).  If an object survives a collection it is moved
+   into the next older generation.  Since generation ``2`` is the oldest
+   generation, objects in that generation remain there after a collection.  In
+   order to decide when to run, the collector keeps track of the number object
    allocations and deallocations since the last collection.  When the number of
    allocations minus the number of deallocations exceeds *threshold0*, collection
-   starts. For each collection, all the objects in the young generation and some
-   fraction of the old generation is collected.
+   starts.  Initially only generation ``0`` is examined.  If generation ``0`` has
+   been examined more than *threshold1* times since generation ``1`` has been
+   examined, then generation ``1`` is examined as well.
+   With the third generation, things are a bit more complicated,
+   see `Collecting the oldest generation <https://github.com/python/cpython/blob/ff0ef0a54bef26fc507fbf9b7a6009eb7d3f17f5/InternalDocs/garbage_collector.md#collecting-the-oldest-generation>`_ for more information.
 
    In the free-threaded build, the increase in process memory usage is also
    checked before running the collector.  If the memory usage has not increased
    by 10% since the last collection and the net number of object allocations
    has not exceeded 40 times *threshold0*, the collection is not run.
 
-   The fraction of the old generation that is collected is **inversely** proportional
-   to *threshold1*. The larger *threshold1* is, the slower objects in the old generation
-   are collected.
-   For the default value of 10, 1% of the old generation is scanned during each collection.
-
-   *threshold2* is ignored.
-
-   See `Garbage collector design <https://devguide.python.org/garbage_collector>`_ for more information.
+   See `Garbage collector design <https://github.com/python/cpython/blob/3.15/InternalDocs/garbage_collector.md>`_ for more information.
 
    .. versionchanged:: 3.14
       *threshold2* is ignored
 
+   .. versionchanged:: 3.14.5
+      *threshold2* is restored to match Python 3.13 behavior.
+
 
 .. function:: get_count()
 

Doc/library/http.cookies.rst

@@ -25,10 +25,8 @@ The character set, :data:`string.ascii_letters`, :data:`string.digits` and
 in a cookie name (as :attr:`~Morsel.key`).
 
 .. versionchanged:: 3.3
-   Allowed '``:``' as a valid cookie name character.
+   Allowed ':' as a valid cookie name character.
 
-.. versionchanged:: 3.15
-   Allowed '``"``' as a valid cookie value character.
 
 .. note::
 
@@ -313,10 +311,3 @@ The following example demonstrates how to use the :mod:`!http.cookies` module.
    >>> print(C)
    Set-Cookie: number=7
    Set-Cookie: string=seven
-   >>> import json
-   >>> C = cookies.SimpleCookie()
-   >>> C.load(f'cookies=7; mixins="{json.dumps({"chips": "dark chocolate"})}"; state=gooey')
-   >>> print(C)
-   Set-Cookie: cookies=7
-   Set-Cookie: mixins="{"chips": "dark chocolate"}"
-   Set-Cookie: state=gooey

Doc/library/http.server.rst

@@ -390,6 +390,14 @@ instantiation, of which this module provides three different variants:
       This will be ``"SimpleHTTP/" + __version__``, where ``__version__`` is
       defined at the module level.
 
+   .. attribute:: default_content_type
+
+      Specifies the Content-Type header value sent when the MIME type
+      cannot be guessed from the file extension of the requested URL.
+      By default, it is set to ``'application/octet-stream'``.
+
+      .. versionadded:: next
+
    .. attribute:: extensions_map
 
       A dictionary mapping suffixes into MIME types, contains custom overrides
@@ -528,6 +536,18 @@ The following options are accepted:
 
    .. versionadded:: 3.11
 
+.. option:: --content-type <content_type>
+
+   Specifies the default Content-Type HTTP header used when the MIME type
+   cannot be guessed from the URL's file extension. By default, the server
+   uses ``'application/octet-stream'``:
+
+   .. code-block:: bash
+
+      python -m http.server --content-type text/html
+
+   .. versionadded:: next
+
 .. option:: --tls-cert
 
    Specifies a TLS certificate chain for HTTPS connections:

Doc/library/pickletools.rst

@@ -79,6 +79,9 @@ Command-line options
 
    A pickle file to read, or ``-`` to indicate reading from standard input.
 
+.. versionadded:: next
+   Output is in color by default and can be
+   :ref:`controlled using environment variables <using-on-controlling-color>`.
 
 
 Programmatic interface

Doc/library/tomllib.rst

@@ -19,6 +19,12 @@ support writing TOML.
    Added TOML 1.1.0 support.
    See the :ref:`What's New <whatsnew315-tomllib-1-1-0>` for details.
 
+.. warning::
+
+   Be cautious when parsing data from untrusted sources.
+   A malicious TOML string may cause the decoder to consume considerable
+   CPU and memory resources.
+   Limiting the size of data to be parsed is recommended.
 
 .. seealso::
 

Doc/make.bat

@@ -13,7 +13,7 @@ if not defined SPHINXBUILD (
     %PYTHON% -c "import sphinx" > nul 2> nul
     if errorlevel 1 (
         echo Installing sphinx with %PYTHON%
-        %PYTHON% -m pip install -r pylock.toml
+        %PYTHON% -m pip install -r requirements.txt
         if errorlevel 1 exit /B
     )
     set SPHINXBUILD=%PYTHON% -c "import sphinx.cmd.build, sys; sys.exit(sphinx.cmd.build.main())"