Merge branch '3.13' into backport-bd3d31f-3.13

.azure-pipelines/ci.yml

@@ -1,4 +1,4 @@
-trigger: ['main', '3.12', '3.11', '3.10', '3.9', '3.8', '3.7']
+trigger: ['main', '3.13', '3.12', '3.11', '3.10', '3.9', '3.8']
 
 jobs:
 - job: Prebuild

.github/workflows/build.yml

@@ -40,6 +40,49 @@ jobs:
     if: fromJSON(needs.check_source.outputs.run-docs)
     uses: ./.github/workflows/reusable-docs.yml
 
+  check_abi:
+    name: 'Check if the ABI has changed'
+    runs-on: ubuntu-latest
+    needs: check_source
+    if: needs.check_source.outputs.run_tests == 'true'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+      - name: Install dependencies
+        run: |
+            sudo ./.github/workflows/posix-deps-apt.sh
+            sudo apt-get install -yq abigail-tools
+      - name: Build CPython
+        env:
+          CFLAGS: -g3 -O0
+        run: |
+          # Build Python with the libpython dynamic library
+          ./configure --enable-shared
+          make -j4
+      - name: Check for changes in the ABI
+        id: check
+        run: |
+          if ! make check-abidump; then
+            echo "Generated ABI file is not up to date."
+            echo "Please add the release manager of this branch as a reviewer of this PR."
+            echo ""
+            echo "The up to date ABI file should be attached to this build as an artifact."
+            echo ""
+            echo "To learn more about this check: https://devguide.python.org/getting-started/setup-building/index.html#regenerate-the-abi-dump"
+            echo ""
+            exit 1
+          fi
+      - name: Generate updated ABI files
+        if: ${{ failure() && steps.check.conclusion == 'failure' }}
+        run: |
+          make regen-abidump
+      - uses: actions/upload-artifact@v4
+        name: Publish updated ABI files
+        if: ${{ failure() && steps.check.conclusion == 'failure' }}
+        with:
+          name: abi-data
+          path: ./Doc/data/*.abi
+
   check_generated_files:
     name: 'Check if generated files are up to date'
     # Don't use ubuntu-latest but a specific version to make the job

.gitignore

@@ -169,5 +169,3 @@ Python/frozen_modules/MANIFEST
 /python
 !/Python/
 
-# main branch only: ABI files are not checked/maintained.
-Doc/data/python*.abi

.readthedocs.yml

@@ -8,7 +8,7 @@ sphinx:
    configuration: Doc/conf.py
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
     python: "3"
 

Doc/c-api/bytearray.rst

@@ -42,17 +42,22 @@ Direct API functions
    Return a new bytearray object from any object, *o*, that implements the
    :ref:`buffer protocol <bufferobjects>`.
 
+   On failure, return ``NULL`` with an exception set.
+
 
 .. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)
 
-   Create a new bytearray object from *string* and its length, *len*.  On
-   failure, ``NULL`` is returned.
+   Create a new bytearray object from *string* and its length, *len*.
+
+   On failure, return ``NULL`` with an exception set.
 
 
 .. c:function:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)
 
    Concat bytearrays *a* and *b* and return a new bytearray with the result.
 
+   On failure, return ``NULL`` with an exception set.
+
 
 .. c:function:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)
 

Doc/c-api/long.rst

@@ -501,6 +501,17 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionadded:: 3.13
 
 
+.. c:function:: PyObject* PyLong_GetInfo(void)
+
+   On success, return a read only :term:`named tuple`, that holds
+   information about Python's internal representation of integers.
+   See :data:`sys.int_info` for description of individual fields.
+
+   On failure, return ``NULL`` with an exception set.
+
+   .. versionadded:: 3.1
+
+
 .. c:function:: int PyUnstable_Long_IsCompact(const PyLongObject* op)
 
    Return 1 if *op* is compact, 0 otherwise.

Doc/library/dis.rst

@@ -1102,11 +1102,15 @@ iterations of the loop.
 .. opcode:: BUILD_TUPLE (count)
 
    Creates a tuple consuming *count* items from the stack, and pushes the
-   resulting tuple onto the stack.::
+   resulting tuple onto the stack::
 
-      assert count > 0
-      STACK, values = STACK[:-count], STACK[-count:]
-      STACK.append(tuple(values))
+      if count == 0:
+          value = ()
+      else:
+          STACK = STACK[:-count]
+          value = tuple(STACK[-count:])
+
+      STACK.append(value)
 
 
 .. opcode:: BUILD_LIST (count)

Doc/library/email.errors.rst

@@ -58,6 +58,13 @@ The following exception classes are defined in the :mod:`email.errors` module:
    :class:`~email.mime.nonmultipart.MIMENonMultipart` (e.g.
    :class:`~email.mime.image.MIMEImage`).
 
+
+.. exception:: HeaderWriteError()
+
+   Raised when an error occurs when the :mod:`~email.generator` outputs
+   headers.
+
+
 .. exception:: MessageDefect()
 
    This is the base class for all defects found when parsing email messages.

Doc/library/email.policy.rst

@@ -229,6 +229,24 @@ added matters.  To illustrate::
 
       .. versionadded:: 3.6
 
+
+   .. attribute:: verify_generated_headers
+
+      If ``True`` (the default), the generator will raise
+      :exc:`~email.errors.HeaderWriteError` instead of writing a header
+      that is improperly folded or delimited, such that it would
+      be parsed as multiple headers or joined with adjacent data.
+      Such headers can be generated by custom header classes or bugs
+      in the ``email`` module.
+
+      As it's a security feature, this defaults to ``True`` even in the
+      :class:`~email.policy.Compat32` policy.
+      For backwards compatible, but unsafe, behavior, it must be set to
+      ``False`` explicitly.
+
+      .. versionadded:: 3.13
+
+
    The following :class:`Policy` method is intended to be called by code using
    the email library to create policy instances with custom settings:
 

Doc/library/logging.config.rst

@@ -753,9 +753,12 @@ The ``queue`` and ``listener`` keys are optional.
 
 If the ``queue`` key is present, the corresponding value can be one of the following:
 
-* An actual instance of :class:`queue.Queue` or a subclass thereof. This is of course
-  only possible if you are constructing or modifying the configuration dictionary in
-  code.
+* An object implementing the :class:`queue.Queue` public API. For instance,
+  this may be an actual instance of :class:`queue.Queue` or a subclass thereof,
+  or a proxy obtained by :meth:`multiprocessing.managers.SyncManager.Queue`.
+
+  This is of course only possible if you are constructing or modifying
+  the configuration dictionary in code.
 
 * A string that resolves to a callable which, when called with no arguments, returns
   the :class:`queue.Queue` instance to use. That callable could be a

Doc/library/os.path.rst

@@ -81,7 +81,7 @@ the :mod:`glob` module.)
 
    Return the longest common sub-path of each pathname in the iterable
    *paths*.  Raise :exc:`ValueError` if *paths* contain both absolute
-   and relative pathnames, the *paths* are on the different drives or
+   and relative pathnames, if *paths* are on different drives, or
    if *paths* is empty.  Unlike :func:`commonprefix`, this returns a
    valid path.
 

Doc/library/site.rst

@@ -32,14 +32,22 @@ It starts by constructing up to four directories from a head and a tail part.
 For the head part, it uses ``sys.prefix`` and ``sys.exec_prefix``; empty heads
 are skipped.  For the tail part, it uses the empty string and then
 :file:`lib/site-packages` (on Windows) or
-:file:`lib/python{X.Y}/site-packages` (on Unix and macOS).  For each
+:file:`lib/python{X.Y[t]}/site-packages` (on Unix and macOS). (The
+optional suffix "t" indicates the :term:`free threading` build, and is
+appended if ``"t"`` is present in the :attr:`sys.abiflags` constant.)
+For each
 of the distinct head-tail combinations, it sees if it refers to an existing
 directory, and if so, adds it to ``sys.path`` and also inspects the newly
 added path for configuration files.
 
 .. versionchanged:: 3.5
    Support for the "site-python" directory has been removed.
 
+.. versionchanged:: 3.13
+   On Unix, :term:`Free threading <free threading>` Python installations are
+   identified by the "t" suffix in the version-specific directory name, such as
+   :file:`lib/python3.13t/`.
+
 If a file named "pyvenv.cfg" exists one directory above sys.executable,
 sys.prefix and sys.exec_prefix are set to that directory and
 it is also checked for site-packages (sys.base_prefix and
@@ -188,11 +196,12 @@ Module contents
 
    Path to the user site-packages for the running Python.  Can be ``None`` if
    :func:`getusersitepackages` hasn't been called yet.  Default value is
-   :file:`~/.local/lib/python{X.Y}/site-packages` for UNIX and non-framework
+   :file:`~/.local/lib/python{X.Y}[t]/site-packages` for UNIX and non-framework
    macOS builds, :file:`~/Library/Python/{X.Y}/lib/python/site-packages` for macOS
    framework builds, and :file:`{%APPDATA%}\\Python\\Python{XY}\\site-packages`
-   on Windows.  This directory is a site directory, which means that
-   :file:`.pth` files in it will be processed.
+   on Windows.  The optional "t" indicates the free-threaded build.  This
+   directory is a site directory, which means that :file:`.pth` files in it
+   will be processed.
 
 
 .. data:: USER_BASE

Doc/library/ssl.rst

@@ -2710,7 +2710,7 @@ Verifying certificates
 
 When calling the :class:`SSLContext` constructor directly,
 :const:`CERT_NONE` is the default.  Since it does not authenticate the other
-peer, it can be insecure, especially in client mode where most of time you
+peer, it can be insecure, especially in client mode where most of the time you
 would like to ensure the authenticity of the server you're talking to.
 Therefore, when in client mode, it is highly recommended to use
 :const:`CERT_REQUIRED`.  However, it is in itself not sufficient; you also

Doc/library/stdtypes.rst

@@ -1209,8 +1209,9 @@ accepts integers that meet the value restriction ``0 <= x <= 255``).
 | ``s.pop()`` or ``s.pop(i)``  | retrieves the item at *i* and  | \(2)                |
 |                              | also removes it from *s*       |                     |
 +------------------------------+--------------------------------+---------------------+
-| ``s.remove(x)``              | remove the first item from *s* | \(3)                |
-|                              | where ``s[i]`` is equal to *x* |                     |
+| ``s.remove(x)``              | removes the first item from    | \(3)                |
+|                              | *s* where ``s[i]`` is equal to |                     |
+|                              | *x*                            |                     |
 +------------------------------+--------------------------------+---------------------+
 | ``s.reverse()``              | reverses the items of *s* in   | \(4)                |
 |                              | place                          |                     |

Doc/reference/datamodel.rst

@@ -106,12 +106,16 @@ that mutable object is changed.
 Types affect almost all aspects of object behavior.  Even the importance of
 object identity is affected in some sense: for immutable types, operations that
 compute new values may actually return a reference to any existing object with
-the same type and value, while for mutable objects this is not allowed.  E.g.,
-after ``a = 1; b = 1``, ``a`` and ``b`` may or may not refer to the same object
-with the value one, depending on the implementation, but after ``c = []; d =
-[]``, ``c`` and ``d`` are guaranteed to refer to two different, unique, newly
-created empty lists. (Note that ``c = d = []`` assigns the same object to both
-``c`` and ``d``.)
+the same type and value, while for mutable objects this is not allowed.
+For example, after ``a = 1; b = 1``, *a* and *b* may or may not refer to
+the same object with the value one, depending on the implementation.
+This is because :class:`int` is an immutable type, so the reference to ``1``
+can be reused. This behaviour depends on the implementation used, so should
+not be relied upon, but is something to be aware of when making use of object
+identity tests.
+However, after ``c = []; d = []``, *c* and *d* are guaranteed to refer to two
+different, unique, newly created empty lists. (Note that ``e = f = []`` assigns
+the *same* object to both *e* and *f*.)
 
 
 .. _types:
@@ -996,7 +1000,7 @@ Special attributes:
       a :ref:`generic class <generic-classes>`.
 
    :attr:`~class.__static_attributes__`
-      A tuple containing names of attributes of this class which are accessed
+      A tuple containing names of attributes of this class which are assigned
       through ``self.X`` from any function in its body.
 
    :attr:`__firstlineno__`

Doc/tools/templates/download.html

@@ -1,5 +1,5 @@
 {% extends "layout.html" %}
-{% set title = 'Download' %}
+{% set title = _('Download') %}
 {% if daily is defined %}
   {% set dlbase = pathto('archives', 1) %}
 {% else %}
@@ -11,58 +11,68 @@
 {% endif %}
 
 {% block body %}
-<h1>Download Python {{ release }} Documentation</h1>
+<h1>{% trans %}Download Python {{ release }} Documentation{% endtrans %}</h1>
 
-{% if last_updated %}<p><b>Last updated on: {{ last_updated }}.</b></p>{% endif %}
+{% if last_updated %}<p><b>{% trans %}Last updated on: {{ last_updated }}.{% endtrans %}</b></p>{% endif %}
 
-<p>To download an archive containing all the documents for this version of
-Python in one of various formats, follow one of links in this table.</p>
+<p>{% trans %}To download an archive containing all the documents for this version of
+Python in one of various formats, follow one of links in this table.{% endtrans %}</p>
 
 <table class="docutils">
-  <tr><th>Format</th><th>Packed as .zip</th><th>Packed as .tar.bz2</th></tr>
-  <tr><td>PDF (US-Letter paper size)</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-pdf-letter.zip">Download</a> (ca. 17 MiB)</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-pdf-letter.tar.bz2">Download</a> (ca. 17 MiB)</td>
+  <tr>
+    <th>{% trans %}Format{% endtrans %}</th>
+    <th>{% trans %}Packed as .zip{% endtrans %}</th>
+    <th>{% trans %}Packed as .tar.bz2{% endtrans %}</th>
   </tr>
-  <tr><td>PDF (A4 paper size)</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-pdf-a4.zip">Download</a> (ca. 17 MiB)</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-pdf-a4.tar.bz2">Download</a> (ca. 17 MiB)</td>
+  <tr>
+    <td>{% trans %}PDF (US-Letter paper size){% endtrans %}</td>
+    <td>{% trans download_size="17" %}<a href="{{ dlbase }}/python-{{ release }}-docs-pdf-letter.zip">Download</a> (ca. {{ download_size }} MiB){% endtrans %}</td>
+    <td>{% trans download_size="17" %}<a href="{{ dlbase }}/python-{{ release }}-docs-pdf-letter.tar.bz2">Download</a> (ca. {{ download_size }} MiB){% endtrans %}</td>
   </tr>
-  <tr><td>HTML</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-html.zip">Download</a> (ca. 13 MiB)</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-html.tar.bz2">Download</a> (ca. 8 MiB)</td>
+  <tr>
+    <td>{% trans %}PDF (A4 paper size){% endtrans %}</td>
+    <td>{% trans download_size="17" %}<a href="{{ dlbase }}/python-{{ release }}-docs-pdf-a4.zip">Download</a> (ca. {{ download_size }} MiB){% endtrans %}</td>
+    <td>{% trans download_size="17" %}<a href="{{ dlbase }}/python-{{ release }}-docs-pdf-a4.tar.bz2">Download</a> (ca. {{ download_size }} MiB){% endtrans %}</td>
   </tr>
-  <tr><td>Plain text</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-text.zip">Download</a> (ca. 4 MiB)</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-text.tar.bz2">Download</a> (ca. 3 MiB)</td>
+  <tr>
+    <td>{% trans %}HTML{% endtrans %}</td>
+    <td>{% trans download_size="13" %}<a href="{{ dlbase }}/python-{{ release }}-docs-html.zip">Download</a> (ca. {{ download_size }} MiB){% endtrans %}</td>
+    <td>{% trans download_size="8" %}<a href="{{ dlbase }}/python-{{ release }}-docs-html.tar.bz2">Download</a> (ca. {{ download_size }} MiB){% endtrans %}</td>
   </tr>
-  <tr><td>Texinfo</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-texinfo.zip">Download</a> (ca. 9 MiB)</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs-texinfo.tar.bz2">Download</a> (ca. 7 MiB)</td>
+  <tr>
+    <td>{% trans %}Plain text{% endtrans %}</td>
+    <td>{% trans download_size="4" %}<a href="{{ dlbase }}/python-{{ release }}-docs-text.zip">Download</a> (ca. {{ download_size }} MiB){% endtrans %}</td>
+    <td>{% trans download_size="3" %}<a href="{{ dlbase }}/python-{{ release }}-docs-text.tar.bz2">Download</a> (ca. {{ download_size }} MiB){% endtrans %}</td>
+  </tr>
+  <tr>
+    <td>{% trans %}Texinfo{% endtrans %}</td>
+    <td>{% trans download_size="9" %}<a href="{{ dlbase }}/python-{{ release }}-docs-texinfo.zip">Download</a> (ca. {{ download_size }} MiB){% endtrans %}</td>
+    <td>{% trans download_size="7" %}<a href="{{ dlbase }}/python-{{ release }}-docs-texinfo.tar.bz2">Download</a> (ca. {{ download_size }} MiB){% endtrans %}</td>
  </tr>
- <tr><td>EPUB</td>
-    <td><a href="{{ dlbase }}/python-{{ release }}-docs.epub">Download</a> (ca. 6 MiB)</td>
+ <tr>
+    <td>{% trans %}EPUB{% endtrans %}</td>
+    <td>{% trans download_size="6" %}<a href="{{ dlbase }}/python-{{ release }}-docs.epub">Download</a> (ca. {{ download_size }} MiB){% endtrans %}</td>
     <td></td>
   </tr>
 </table>
 
-<p>These archives contain all the content in the documentation.</p>
+<p>{% trans %}These archives contain all the content in the documentation.{% endtrans %}</p>
 
 
-<h2>Unpacking</h2>
+<h2>{% trans %}Unpacking{% endtrans %}</h2>
 
-<p>Unix users should download the .tar.bz2 archives; these are bzipped tar
+<p>{% trans %}Unix users should download the .tar.bz2 archives; these are bzipped tar
 archives and can be handled in the usual way using tar and the bzip2
 program. The <a href="https://infozip.sourceforge.net">Info-ZIP</a> unzip program can be
 used to handle the ZIP archives if desired. The .tar.bz2 archives provide the
-best compression and fastest download times.</p>
+best compression and fastest download times.{% endtrans %}</p>
 
-<p>Windows users can use the ZIP archives since those are customary on that
-platform. These are created on Unix using the Info-ZIP zip program.</p>
+<p>{% trans %}Windows users can use the ZIP archives since those are customary on that
+platform. These are created on Unix using the Info-ZIP zip program.{% endtrans %}</p>
 
 
-<h2>Problems</h2>
+<h2>{% trans %}Problems{% endtrans %}</h2>
 
-<p>If you have comments or suggestions for the Python documentation, please send
-email to <a href="mailto:[email protected]">[email protected]</a>.</p>
+<p>{% trans %}If you have comments or suggestions for the Python documentation, please send
+email to <a href="mailto:[email protected]">[email protected]</a>.{% endtrans %}</p>
 {% endblock %}