Merge branch 'main' into gh-140795-ssl-exc

Author: colesbury

.github/CODEOWNERS

@@ -143,6 +143,9 @@ Misc/externals.spdx.json      @sethmlarson
 Misc/sbom.spdx.json           @sethmlarson
 Tools/build/generate_sbom.py  @sethmlarson
 
+# ABI check
+Misc/libabigail.abignore      @encukou
+
 
 # ----------------------------------------------------------------------------
 # Platform Support

Doc/c-api/apiabiversion.rst

@@ -34,6 +34,23 @@ See :ref:`stable` for a discussion of API and ABI stability across versions.
    This can be ``0xA`` for alpha, ``0xB`` for beta, ``0xC`` for release
    candidate or ``0xF`` for final.
 
+
+   .. c:namespace:: NULL
+   .. c:macro:: PY_RELEASE_LEVEL_ALPHA
+      :no-typesetting:
+   .. c:macro:: PY_RELEASE_LEVEL_BETA
+      :no-typesetting:
+   .. c:macro:: PY_RELEASE_LEVEL_GAMMA
+      :no-typesetting:
+   .. c:macro:: PY_RELEASE_LEVEL_FINAL
+      :no-typesetting:
+
+   For completeness, the values are available as macros:
+   :c:macro:`!PY_RELEASE_LEVEL_ALPHA` (``0xA``),
+   :c:macro:`!PY_RELEASE_LEVEL_BETA` (``0xB``),
+   :c:macro:`!PY_RELEASE_LEVEL_GAMMA` (``0xC``), and
+   :c:macro:`!PY_RELEASE_LEVEL_FINAL` (``0xF``).
+
 .. c:macro:: PY_RELEASE_SERIAL
 
    The ``2`` in ``3.4.1a2``. Zero for final releases.
@@ -46,6 +63,12 @@ See :ref:`stable` for a discussion of API and ABI stability across versions.
    Use this for numeric comparisons, for example,
    ``#if PY_VERSION_HEX >= ...``.
 
+.. c:macro:: PY_VERSION
+
+   The Python version as a string, for example, ``"3.4.1a2"``.
+
+These macros are defined in :source:`Include/patchlevel.h`.
+
 
 Run-time version
 ----------------

Doc/c-api/module.rst

@@ -820,15 +820,18 @@ struct:
    .. versionadded:: 3.5
 
 .. c:macro:: PYTHON_API_VERSION
+             PYTHON_API_STRING
 
-   The C API version. Defined for backwards compatibility.
+   The C API version, as an integer (``1013``) and string (``"1013"``), respectively.
+   Defined for backwards compatibility.
 
    Currently, this constant is not updated in new Python versions, and is not
    useful for versioning. This may change in the future.
 
 .. c:macro:: PYTHON_ABI_VERSION
+             PYTHON_ABI_STRING
 
-   Defined as ``3`` for backwards compatibility.
+   Defined as ``3`` and ``"3"``, respectively, for backwards compatibility.
 
    Currently, this constant is not updated in new Python versions, and is not
    useful for versioning. This may change in the future.

Doc/c-api/unicode.rst

@@ -65,6 +65,27 @@ Python:
    .. versionadded:: 3.3
 
 
+   The structure of a particular object can be determined using the following
+   macros.
+   The macros cannot fail; their behavior is undefined if their argument
+   is not a Python Unicode object.
+
+   .. c:namespace:: NULL
+
+   .. c:macro:: PyUnicode_IS_COMPACT(o)
+
+      True if *o* uses the :c:struct:`PyCompactUnicodeObject` structure.
+
+      .. versionadded:: 3.3
+
+
+   .. c:macro:: PyUnicode_IS_COMPACT_ASCII(o)
+
+      True if *o* uses the :c:struct:`PyASCIIObject` structure.
+
+      .. versionadded:: 3.3
+
+
 The following APIs are C macros and static inlined functions for fast checks and
 access to internal read-only data of Unicode objects:
 

Doc/library/array.rst

@@ -9,7 +9,7 @@
 --------------
 
 This module defines an object type which can compactly represent an array of
-basic values: characters, integers, floating-point numbers.  Arrays are sequence
+basic values: characters, integers, floating-point numbers.  Arrays are mutable :term:`sequence`
 types and behave very much like lists, except that the type of objects stored in
 them is constrained.  The type is specified at object creation time by using a
 :dfn:`type code`, which is a single character.  The following type codes are
@@ -93,7 +93,7 @@ The module defines the following type:
    otherwise, the initializer's iterator is passed to the :meth:`extend` method
    to add initial items to the array.
 
-   Array objects support the ordinary sequence operations of indexing, slicing,
+   Array objects support the ordinary :ref:`mutable <typesseq-mutable>` :term:`sequence` operations of indexing, slicing,
    concatenation, and multiplication.  When using slice assignment, the assigned
    value must be an array object with the same type code; in all other cases,
    :exc:`TypeError` is raised. Array objects also implement the buffer interface,

Doc/library/concurrent.futures.rst

@@ -21,6 +21,11 @@ or separate processes, using :class:`ProcessPoolExecutor`.
 Each implements the same interface, which is defined
 by the abstract :class:`Executor` class.
 
+:class:`concurrent.futures.Future` must not be confused with
+:class:`asyncio.Future`, which is designed for use with :mod:`asyncio`
+tasks and coroutines. See the :doc:`asyncio's Future <asyncio-future>`
+documentation for a detailed comparison of the two.
+
 .. include:: ../includes/wasm-notavail.rst
 
 Executor Objects

Doc/library/dis.rst

@@ -768,7 +768,7 @@ not have to be) the original ``STACK[-2]``.
       end = STACK.pop()
       start = STACK.pop()
       container = STACK.pop()
-      values = STACK.pop()
+      value = STACK.pop()
       container[start:end] = value
 
    .. versionadded:: 3.12

Doc/library/email.message.rst

@@ -57,7 +57,7 @@ message objects.
    :class:`~email.policy.default` policy, which follows the rules of the email
    RFCs except for line endings (instead of the RFC mandated ``\r\n``, it uses
    the Python standard ``\n`` line endings).  For more information see the
-   :mod:`~email.policy` documentation.
+   :mod:`~email.policy` documentation. [2]_
 
    .. method:: as_string(unixfrom=False, maxheaderlen=None, policy=None)
 
@@ -749,3 +749,9 @@ message objects.
 .. [1] Originally added in 3.4 as a :term:`provisional module <provisional
        package>`.  Docs for legacy message class moved to
        :ref:`compat32_message`.
+
+.. [2] The :class:`EmailMessage` class requires a policy that provides a
+       ``content_manager`` attribute for content management methods like
+       ``set_content()`` and ``get_content()`` to work. The legacy
+       :const:`~email.policy.compat32` policy does not support these methods
+       and should not be used with :class:`EmailMessage`.

Doc/library/email.policy.rst

@@ -662,6 +662,13 @@ The header objects and their attributes are described in
    An instance of :class:`Compat32`, providing  backward compatibility with the
    behavior of the email package in Python 3.2.
 
+   .. note::
+
+      The :const:`compat32` policy should not be used as a policy for
+      :class:`~email.message.EmailMessage` objects, and should only be used
+      to serialize messages that were created using the :const:`compat32`
+      policy.
+
 
 .. rubric:: Footnotes
 

Doc/library/enum.rst

@@ -153,6 +153,12 @@ Module Contents
 
       Return a list of all power-of-two integers contained in a flag.
 
+   :func:`enum.bin`
+
+      Like built-in :func:`bin`, except negative values are represented in
+      two's complement, and the leading bit always indicates sign
+      (``0`` implies positive, ``1`` implies negative).
+
 
 .. versionadded:: 3.6  ``Flag``, ``IntFlag``, ``auto``
 .. versionadded:: 3.11  ``StrEnum``, ``EnumCheck``, ``ReprEnum``, ``FlagBoundary``, ``property``, ``member``, ``nonmember``, ``global_enum``, ``show_flag_values``
@@ -1035,6 +1041,20 @@ Utilities and Decorators
 
    .. versionadded:: 3.11
 
+.. function:: bin(num, max_bits=None)
+
+   Like built-in :func:`bin`, except negative values are represented in
+   two's complement, and the leading bit always indicates sign
+   (``0`` implies positive, ``1`` implies negative).
+
+      >>> import enum
+      >>> enum.bin(10)
+      '0b0 1010'
+      >>> enum.bin(~10)   # ~10 is -11
+      '0b1 0101'
+
+   .. versionadded:: 3.10
+
 ---------------
 
 Notes