Merge remote-tracking branch 'upstream/main' into compare_op

.github/workflows/reusable-macos.yml

@@ -42,7 +42,7 @@ jobs:
       run: |
         brew install pkg-config openssl@3.0 xz gdbm tcl-tk@8 make
         # Because alternate versions are not symlinked into place by default:
-        brew link tcl-tk@8
+        brew link --overwrite tcl-tk@8
     - name: Configure CPython
       run: |
         GDBM_CFLAGS="-I$(brew --prefix gdbm)/include" \

Doc/c-api/frame.rst

@@ -132,14 +132,34 @@ See also :ref:`Reflection <reflection>`.
    .. versionadded:: 3.11
 
    .. versionchanged:: 3.13
-      As part of :pep:`667`, return a proxy object for optimized scopes.
+      As part of :pep:`667`, return an instance of :c:var:`PyFrameLocalsProxy_Type`.
 
 
 .. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame)
 
    Return the line number that *frame* is currently executing.
 
 
+Frame Locals Proxies
+^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 3.13
+
+The :attr:`~frame.f_locals` attribute on a :ref:`frame object <frame-objects>`
+is an instance of a "frame-locals proxy". The proxy object exposes a
+write-through view of the underlying locals dictionary for the frame. This
+ensures that the variables exposed by ``f_locals`` are always up to date with
+the live local variables in the frame itself.
+
+See :pep:`667` for more information.
+
+.. c:var:: PyTypeObject PyFrameLocalsProxy_Type
+
+   The type of frame :func:`locals` proxy objects.
+
+.. c:function:: int PyFrameLocalsProxy_Check(PyObject *obj)
+
+   Return non-zero if *obj* is a frame :func:`locals` proxy.
 
 Internal Frames
 ^^^^^^^^^^^^^^^

Doc/c-api/long.rst

@@ -653,3 +653,177 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
 
    .. versionadded:: 3.12
 
+
+Export API
+^^^^^^^^^^
+
+.. versionadded:: 3.14
+
+.. c:struct:: PyLongLayout
+
+   Layout of an array of "digits" ("limbs" in the GMP terminology), used to
+   represent absolute value for arbitrary precision integers.
+
+   Use :c:func:`PyLong_GetNativeLayout` to get the native layout of Python
+   :class:`int` objects, used internally for integers with "big enough"
+   absolute value.
+
+   See also :data:`sys.int_info` which exposes similar information in Python.
+
+   .. c:member:: uint8_t bits_per_digit
+
+      Bits per digit. For example, a 15 bit digit means that bits 0-14 contain
+      meaningful information.
+
+   .. c:member:: uint8_t digit_size
+
+      Digit size in bytes. For example, a 15 bit digit will require at least 2
+      bytes.
+
+   .. c:member:: int8_t digits_order
+
+      Digits order:
+
+      - ``1`` for most significant digit first
+      - ``-1`` for least significant digit first
+
+   .. c:member:: int8_t digit_endianness
+
+      Digit endianness:
+
+      - ``1`` for most significant byte first (big endian)
+      - ``-1`` for least significant byte first (little endian)
+
+
+.. c:function:: const PyLongLayout* PyLong_GetNativeLayout(void)
+
+   Get the native layout of Python :class:`int` objects.
+
+   See the :c:struct:`PyLongLayout` structure.
+
+   The function must not be called before Python initialization nor after
+   Python finalization. The returned layout is valid until Python is
+   finalized. The layout is the same for all Python sub-interpreters
+   in a process, and so it can be cached.
+
+
+.. c:struct:: PyLongExport
+
+   Export of a Python :class:`int` object.
+
+   There are two cases:
+
+   * If :c:member:`digits` is ``NULL``, only use the :c:member:`value` member.
+   * If :c:member:`digits` is not ``NULL``, use :c:member:`negative`,
+     :c:member:`ndigits` and :c:member:`digits` members.
+
+   .. c:member:: int64_t value
+
+      The native integer value of the exported :class:`int` object.
+      Only valid if :c:member:`digits` is ``NULL``.
+
+   .. c:member:: uint8_t negative
+
+      ``1`` if the number is negative, ``0`` otherwise.
+      Only valid if :c:member:`digits` is not ``NULL``.
+
+   .. c:member:: Py_ssize_t ndigits
+
+      Number of digits in :c:member:`digits` array.
+      Only valid if :c:member:`digits` is not ``NULL``.
+
+   .. c:member:: const void *digits
+
+      Read-only array of unsigned digits. Can be ``NULL``.
+
+
+.. c:function:: int PyLong_Export(PyObject *obj, PyLongExport *export_long)
+
+   Export a Python :class:`int` object.
+
+   *export_long* must point to a :c:struct:`PyLongExport` structure allocated
+   by the caller. It must not be ``NULL``.
+
+   On success, fill in *\*export_long* and return ``0``.
+   On error, set an exception and return ``-1``.
+
+   :c:func:`PyLong_FreeExport` must be called when the export is no longer
+   needed.
+
+    .. impl-detail::
+        This function always succeeds if *obj* is a Python :class:`int` object
+        or a subclass.
+
+
+.. c:function:: void PyLong_FreeExport(PyLongExport *export_long)
+
+   Release the export *export_long* created by :c:func:`PyLong_Export`.
+
+   .. impl-detail::
+      Calling :c:func:`PyLong_FreeExport` is optional if *export_long->digits*
+      is ``NULL``.
+
+
+PyLongWriter API
+^^^^^^^^^^^^^^^^
+
+The :c:type:`PyLongWriter` API can be used to import an integer.
+
+.. versionadded:: 3.14
+
+.. c:struct:: PyLongWriter
+
+   A Python :class:`int` writer instance.
+
+   The instance must be destroyed by :c:func:`PyLongWriter_Finish` or
+   :c:func:`PyLongWriter_Discard`.
+
+
+.. c:function:: PyLongWriter* PyLongWriter_Create(int negative, Py_ssize_t ndigits, void **digits)
+
+   Create a :c:type:`PyLongWriter`.
+
+   On success, allocate *\*digits* and return a writer.
+   On error, set an exception and return ``NULL``.
+
+   *negative* is ``1`` if the number is negative, or ``0`` otherwise.
+
+   *ndigits* is the number of digits in the *digits* array. It must be
+   greater than 0.
+
+   *digits* must not be NULL.
+
+   After a successful call to this function, the caller should fill in the
+   array of digits *digits* and then call :c:func:`PyLongWriter_Finish` to get
+   a Python :class:`int`.
+   The layout of *digits* is described by :c:func:`PyLong_GetNativeLayout`.
+
+   Digits must be in the range [``0``; ``(1 << bits_per_digit) - 1``]
+   (where the :c:struct:`~PyLongLayout.bits_per_digit` is the number of bits
+   per digit).
+   Any unused most significant digits must be set to ``0``.
+
+   Alternately, call :c:func:`PyLongWriter_Discard` to destroy the writer
+   instance without creating an :class:`~int` object.
+
+
+.. c:function:: PyObject* PyLongWriter_Finish(PyLongWriter *writer)
+
+   Finish a :c:type:`PyLongWriter` created by :c:func:`PyLongWriter_Create`.
+
+   On success, return a Python :class:`int` object.
+   On error, set an exception and return ``NULL``.
+
+   The function takes care of normalizing the digits and converts the object
+   to a compact integer if needed.
+
+   The writer instance and the *digits* array are invalid after the call.
+
+
+.. c:function:: void PyLongWriter_Discard(PyLongWriter *writer)
+
+   Discard a :c:type:`PyLongWriter` created by :c:func:`PyLongWriter_Create`.
+
+   *writer* must not be ``NULL``.
+
+   The writer instance and the *digits* array are invalid after the call.

Doc/c-api/object.rst

@@ -509,6 +509,12 @@ Object Protocol
    iterated.
 
 
+.. c:function:: PyObject* PyObject_SelfIter(PyObject *obj)
+
+   This is equivalent to the Python ``__iter__(self): return self`` method.
+   It is intended for :term:`iterator` types, to be used in the :c:member:`PyTypeObject.tp_iter` slot.
+
+
 .. c:function:: PyObject* PyObject_GetAIter(PyObject *o)
 
    This is the equivalent to the Python expression ``aiter(o)``. Takes an

Doc/c-api/sequence.rst

@@ -105,6 +105,15 @@ Sequence Protocol
    equivalent to the Python expression ``value in o``.
 
 
+.. c:function:: int PySequence_In(PyObject *o, PyObject *value)
+
+   Alias for :c:func:`PySequence_Contains`.
+
+   .. deprecated:: 3.14
+      The function is :term:`soft deprecated` and should no longer be used to
+      write new code.
+
+
 .. c:function:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)
 
    Return the first index *i* for which ``o[i] == value``.  On error, return

Doc/data/refcounts.dat

@@ -1299,6 +1299,13 @@ PyLong_GetSign:int:::
 PyLong_GetSign:PyObject*:v:0:
 PyLong_GetSign:int*:sign::
 
+PyLong_Export:int:::
+PyLong_Export:PyObject*:obj:0:
+PyLong_Export:PyLongExport*:export_long::
+
+PyLongWriter_Finish:PyObject*::+1:
+PyLongWriter_Finish:PyLongWriter*:writer::
+
 PyMapping_Check:int:::
 PyMapping_Check:PyObject*:o:0:
 
@@ -1849,6 +1856,9 @@ PyObject_RichCompareBool:PyObject*:o1:0:
 PyObject_RichCompareBool:PyObject*:o2:0:
 PyObject_RichCompareBool:int:opid::
 
+PyObject_SelfIter:PyObject*::+1:
+PyObject_SelfIter:PyObject*:obj:0:
+
 PyObject_SetAttr:int:::
 PyObject_SetAttr:PyObject*:o:0:
 PyObject_SetAttr:PyObject*:attr_name:0:

Doc/library/ast.rst

@@ -1807,15 +1807,15 @@ aliases.
 
    .. doctest::
 
-        >>> print(ast.dump(ast.parse("type Alias[**P = (int, str)] = Callable[P, int]"), indent=4))
+        >>> print(ast.dump(ast.parse("type Alias[**P = [int, str]] = Callable[P, int]"), indent=4))
         Module(
             body=[
                 TypeAlias(
                     name=Name(id='Alias', ctx=Store()),
                     type_params=[
                         ParamSpec(
                             name='P',
-                            default_value=Tuple(
+                            default_value=List(
                                 elts=[
                                     Name(id='int', ctx=Load()),
                                     Name(id='str', ctx=Load())],

Doc/library/asyncio-policy.rst

@@ -40,12 +40,20 @@ for the current process:
 
    Return the current process-wide policy.
 
+   .. deprecated:: next
+      The :func:`get_event_loop_policy` function is deprecated and
+      will be removed in Python 3.16.
+
 .. function:: set_event_loop_policy(policy)
 
    Set the current process-wide policy to *policy*.
 
    If *policy* is set to ``None``, the default policy is restored.
 
+   .. deprecated:: next
+      The :func:`set_event_loop_policy` function is deprecated and
+      will be removed in Python 3.16.
+
 
 .. _asyncio-policy-objects:
 

Doc/library/ctypes.rst

@@ -1964,7 +1964,7 @@ Utility functions
 
    .. availability:: Windows
 
-   .. versionadded:: next
+   .. versionadded:: 3.14
 
 
 .. function:: cast(obj, type)
@@ -2825,4 +2825,4 @@ Exceptions
 
    .. availability:: Windows
 
-   .. versionadded:: next
+   .. versionadded:: 3.14

Doc/library/errno.rst

@@ -617,7 +617,7 @@ defined by the module.  The specific list of defined symbols is available as
 
    Memory page has hardware error.
 
-   .. versionadded:: next
+   .. versionadded:: 3.14
 
 
 .. data:: EALREADY

Doc/library/http.cookies.rst

@@ -98,7 +98,7 @@ Cookie Objects
 .. method:: BaseCookie.output(attrs=None, header='Set-Cookie:', sep='\r\n')
 
    Return a string representation suitable to be sent as HTTP headers. *attrs* and
-   *header* are sent to each :class:`Morsel`'s :meth:`output` method. *sep* is used
+   *header* are sent to each :class:`Morsel`'s :meth:`~Morsel.output` method. *sep* is used
    to join the headers together, and is by default the combination ``'\r\n'``
    (CRLF).