Merge remote-tracking branch 'origin/main' into HEAD

Doc/c-api/arg.rst

@@ -160,7 +160,7 @@ There are three ways strings and buffers can be converted to C:
 ``w*`` (read-write :term:`bytes-like object`) [Py_buffer]
    This format accepts any object which implements the read-write buffer
    interface. It fills a :c:type:`Py_buffer` structure provided by the caller.
-   The buffer may contain embedded null bytes. The caller have to call
+   The buffer may contain embedded null bytes. The caller has to call
    :c:func:`PyBuffer_Release` when it is done with the buffer.
 
 ``es`` (:class:`str`) [const char \*encoding, char \*\*buffer]
@@ -305,7 +305,7 @@ the minimal value for the corresponding signed integer type of the same size.
 ``D`` (:class:`complex`) [Py_complex]
    Convert a Python complex number to a C :c:type:`Py_complex` structure.
 
-.. deprecated:: next
+.. deprecated:: 3.15
 
    For unsigned integer formats ``B``, ``H``, ``I``, ``k`` and ``K``,
    :exc:`DeprecationWarning` is emitted when the value is larger than

Doc/c-api/bytes.rst

@@ -236,7 +236,7 @@ PyBytesWriter
 The :c:type:`PyBytesWriter` API can be used to create a Python :class:`bytes`
 object.
 
-.. versionadded:: next
+.. versionadded:: 3.15
 
 .. c:type:: PyBytesWriter
 
@@ -259,8 +259,9 @@ Create, Finish, Discard
    If *size* is greater than zero, allocate *size* bytes, and set the
    writer size to *size*. The caller is responsible to write *size*
    bytes using :c:func:`PyBytesWriter_GetData`.
+   This function does not overallocate.
 
-   On error, set an exception and return NULL.
+   On error, set an exception and return ``NULL``.
 
    *size* must be positive or zero.
 
@@ -349,6 +350,8 @@ Low-level API
 
    Resize the writer to *size* bytes. It can be used to enlarge or to
    shrink the writer.
+   This function typically overallocates to achieve amortized performance when
+   resizing multiple times.
 
    Newly allocated bytes are left uninitialized.
 
@@ -360,6 +363,8 @@ Low-level API
 .. c:function:: int PyBytesWriter_Grow(PyBytesWriter *writer, Py_ssize_t grow)
 
    Resize the writer by adding *grow* bytes to the current writer size.
+   This function typically overallocates to achieve amortized performance when
+   resizing multiple times.
 
    Newly allocated bytes are left uninitialized.
 

Doc/c-api/capsule.rst

@@ -15,7 +15,7 @@ Refer to :ref:`using-capsules` for more information on using these objects.
 .. c:type:: PyCapsule
 
    This subtype of :c:type:`PyObject` represents an opaque value, useful for C
-   extension modules who need to pass an opaque value (as a :c:expr:`void*`
+   extension modules which need to pass an opaque value (as a :c:expr:`void*`
    pointer) through Python code to other C code.  It is often used to make a C
    function pointer defined in one module available to other modules, so the
    regular import mechanism can be used to access C APIs defined in dynamically

Doc/c-api/code.rst

@@ -289,7 +289,7 @@ may change without deprecation warnings.
 
 .. c:function:: Py_ssize_t PyUnstable_Eval_RequestCodeExtraIndex(freefunc free)
 
-   Return a new an opaque index value used to adding data to code objects.
+   Return a new opaque index value used to adding data to code objects.
 
    You generally call this function once (per interpreter) and use the result
    with ``PyCode_GetExtra`` and ``PyCode_SetExtra`` to manipulate

Doc/c-api/codec.rst

@@ -7,7 +7,7 @@ Codec registry and support functions
 
    Register a new codec search function.
 
-   As side effect, this tries to load the :mod:`!encodings` package, if not yet
+   As a side effect, this tries to load the :mod:`!encodings` package, if not yet
    done, to make sure that it is always first in the list of search functions.
 
 .. c:function:: int PyCodec_Unregister(PyObject *search_function)
@@ -39,7 +39,7 @@ Codec registry and support functions
    *object* is passed through the decoder function found for the given
    *encoding* using the error handling method defined by *errors*.  *errors* may
    be ``NULL`` to use the default method defined for the codec.  Raises a
-   :exc:`LookupError` if no encoder can be found.
+   :exc:`LookupError` if no decoder can be found.
 
 
 Codec lookup API

Doc/c-api/complex.rst

@@ -16,7 +16,7 @@ Complex Number Objects
 
       The complex number value, using the C :c:type:`Py_complex` representation.
 
-      .. deprecated-removed:: next 3.20
+      .. deprecated-removed:: 3.15 3.20
          Use :c:func:`PyComplex_AsCComplex` and
          :c:func:`PyComplex_FromCComplex` to convert a
          Python complex number to/from the C :c:type:`Py_complex`

Doc/c-api/conversion.rst

@@ -41,7 +41,7 @@ The return value (*rv*) for these functions should be interpreted as follows:
   ``rv + 1`` bytes would have been needed to succeed. ``str[size-1]`` is ``'\0'``
   in this case.
 
-* When ``rv < 0``, "something bad happened." ``str[size-1]`` is ``'\0'`` in
+* When ``rv < 0``, the output conversion failed and ``str[size-1]`` is ``'\0'`` in
   this case too, but the rest of *str* is undefined. The exact cause of the error
   depends on the underlying platform.
 

Doc/c-api/dict.rst

@@ -50,7 +50,7 @@ Dictionary Objects
 
 .. c:function:: int PyDict_Contains(PyObject *p, PyObject *key)
 
-   Determine if dictionary *p* contains *key*.  If an item in *p* is matches
+   Determine if dictionary *p* contains *key*.  If an item in *p* matches
    *key*, return ``1``, otherwise return ``0``.  On error, return ``-1``.
    This is equivalent to the Python expression ``key in p``.
 
@@ -198,7 +198,7 @@ Dictionary Objects
 .. c:function:: int PyDict_Pop(PyObject *p, PyObject *key, PyObject **result)
 
    Remove *key* from dictionary *p* and optionally return the removed value.
-   Do not raise :exc:`KeyError` if the key missing.
+   Do not raise :exc:`KeyError` if the key is missing.
 
    - If the key is present, set *\*result* to a new reference to the removed
      value if *result* is not ``NULL``, and return ``1``.
@@ -207,7 +207,7 @@ Dictionary Objects
    - On error, raise an exception and return ``-1``.
 
    Similar to :meth:`dict.pop`, but without the default value and
-   not raising :exc:`KeyError` if the key missing.
+   not raising :exc:`KeyError` if the key is missing.
 
    .. versionadded:: 3.13
 

Doc/c-api/function.rst

@@ -175,6 +175,9 @@ There are a few functions specific to Python functions.
 
    .. versionadded:: 3.12
 
+    - ``PyFunction_PYFUNC_EVENT_MODIFY_QUALNAME``
+
+   .. versionadded:: 3.15
 
 .. c:type:: int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value)
 

Doc/c-api/init.rst

@@ -1113,7 +1113,7 @@ code, or when embedding the Python interpreter:
    This function is safe to call without an :term:`attached thread state`; it
    will simply return ``NULL`` indicating that there was no prior thread state.
 
-   .. seealso:
+   .. seealso::
       :c:func:`PyEval_ReleaseThread`
 
    .. note::
@@ -1124,6 +1124,19 @@ code, or when embedding the Python interpreter:
 The following functions use thread-local storage, and are not compatible
 with sub-interpreters:
 
+.. c:type:: PyGILState_STATE
+
+   The type of the value returned by :c:func:`PyGILState_Ensure` and passed to
+   :c:func:`PyGILState_Release`.
+
+   .. c:enumerator:: PyGILState_LOCKED
+
+      The GIL was already held when :c:func:`PyGILState_Ensure` was called.
+
+   .. c:enumerator:: PyGILState_UNLOCKED
+
+      The GIL was not held when :c:func:`PyGILState_Ensure` was called.
+
 .. c:function:: PyGILState_STATE PyGILState_Ensure()
 
    Ensure that the current thread is ready to call the Python C API regardless
@@ -1174,12 +1187,12 @@ with sub-interpreters:
    made on the main thread.  This is mainly a helper/diagnostic function.
 
    .. note::
-      This function does not account for :term:`thread states <thread state>` created
-      by something other than :c:func:`PyGILState_Ensure` (such as :c:func:`PyThreadState_New`).
+      This function may return non-``NULL`` even when the :term:`thread state`
+      is detached.
       Prefer :c:func:`PyThreadState_Get` or :c:func:`PyThreadState_GetUnchecked`
       for most cases.
 
-   .. seealso: :c:func:`PyThreadState_Get``
+   .. seealso:: :c:func:`PyThreadState_Get`
 
 .. c:function:: int PyGILState_Check()
 
@@ -1278,11 +1291,11 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
    must be :term:`attached <attached thread state>`
 
    .. versionchanged:: 3.9
-      This function now calls the :c:member:`PyThreadState.on_delete` callback.
+      This function now calls the :c:member:`!PyThreadState.on_delete` callback.
       Previously, that happened in :c:func:`PyThreadState_Delete`.
 
    .. versionchanged:: 3.13
-      The :c:member:`PyThreadState.on_delete` callback was removed.
+      The :c:member:`!PyThreadState.on_delete` callback was removed.
 
 
 .. c:function:: void PyThreadState_Delete(PyThreadState *tstate)
@@ -2127,7 +2140,7 @@ use a thread key and functions to associate a :c:expr:`void*` value per
 thread.
 
 A :term:`thread state` does *not* need to be :term:`attached <attached thread state>`
-when calling these functions; they suppl their own locking.
+when calling these functions; they supply their own locking.
 
 Note that :file:`Python.h` does not include the declaration of the TLS APIs,
 you need to include :file:`pythread.h` to use thread-local storage.

Doc/c-api/iter.rst

@@ -54,6 +54,6 @@ There are two functions specifically for working with iterators.
 
    - ``PYGEN_RETURN`` if iterator returns. Return value is returned via *presult*.
    - ``PYGEN_NEXT`` if iterator yields. Yielded value is returned via *presult*.
-   - ``PYGEN_ERROR`` if iterator has raised and exception. *presult* is set to ``NULL``.
+   - ``PYGEN_ERROR`` if iterator has raised an exception. *presult* is set to ``NULL``.
 
    .. versionadded:: 3.10

Doc/c-api/long.rst

@@ -43,7 +43,7 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. impl-detail::
 
       CPython keeps an array of integer objects for all integers
-      between ``-5`` and ``256``.  When you create an int in that range
+      between ``-5`` and ``1024``.  When you create an int in that range
       you actually just get back a reference to the existing object.
 
 

Doc/c-api/module.rst

@@ -102,6 +102,10 @@ Module Objects
    Return a pointer to the :c:type:`PyModuleDef` struct from which the module was
    created, or ``NULL`` if the module wasn't created from a definition.
 
+   On error, return ``NULL`` with an exception set.
+   Use :c:func:`PyErr_Occurred` to tell this case apart from a mising
+   :c:type:`!PyModuleDef`.
+
 
 .. c:function:: PyObject* PyModule_GetFilenameObject(PyObject *module)
 

Doc/c-api/object.rst

@@ -201,7 +201,7 @@ Object Protocol
    This case can arise from forgetting ``NULL`` checks and would delete the
    attribute.
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Must not be called with NULL value if an exception is set.
 
 
@@ -226,7 +226,7 @@ Object Protocol
    For more details, see :c:func:`PyUnicode_InternFromString`, which may be
    used internally to create a key object.
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Must not be called with NULL value if an exception is set.
 
 
@@ -600,7 +600,7 @@ Object Protocol
 
    Clear the managed dictionary of *obj*.
 
-   This function must only be called in a traverse function of the type which
+   This function must only be called in a clear function of the type which
    has the :c:macro:`Py_TPFLAGS_MANAGED_DICT` flag set.
 
    .. versionadded:: 3.13

Doc/c-api/stable.rst

@@ -202,7 +202,7 @@ third-party distributors.
 ABI Checking
 ============
 
-.. versionadded:: next
+.. versionadded:: 3.15
 
 Python includes a rudimentary check for ABI compatibility.
 
@@ -249,7 +249,7 @@ The full API is described below for advanced use cases.
    may lead to crashes.
    In particular, it is not safe to examine the raised exception.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
 .. c:macro:: PyABIInfo_VAR(NAME)
 
@@ -266,7 +266,7 @@ The full API is described below for advanced use cases.
           PyABIInfo_DEFAULT_ABI_VERSION
       }
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
 .. c:type:: PyABIInfo
 
@@ -294,7 +294,7 @@ The full API is described below for advanced use cases.
          Default flags, based on current values of macros such as
          :c:macro:`Py_LIMITED_API` and :c:macro:`Py_GIL_DISABLED`.
 
-      Alternately, the field can be set to to the following flags, combined
+      Alternately, the field can be set to the following flags, combined
       by bitwise OR.
       Unused bits must be set to zero.
 
@@ -352,7 +352,7 @@ The full API is described below for advanced use cases.
          values of macros such as :c:macro:`Py_LIMITED_API`,
          :c:macro:`PY_VERSION_HEX` and :c:macro:`Py_GIL_DISABLED`.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
 
 .. _limited-api-list:

Doc/c-api/sys.rst

@@ -268,7 +268,7 @@ accessible to C code.  They all work with the current interpreter thread's
    If the non-existing object should not be treated as a failure, you can use
    :c:func:`PySys_GetOptionalAttr` instead.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
 .. c:function:: PyObject *PySys_GetAttrString(const char *name)
 
@@ -279,7 +279,7 @@ accessible to C code.  They all work with the current interpreter thread's
    If the non-existing object should not be treated as a failure, you can use
    :c:func:`PySys_GetOptionalAttrString` instead.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
 .. c:function:: int PySys_GetOptionalAttr(PyObject *name, PyObject **result)
 
@@ -293,7 +293,7 @@ accessible to C code.  They all work with the current interpreter thread's
    * Set an exception, set *\*result* to ``NULL``, and return ``-1``,
      if an error occurred.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
 .. c:function:: int PySys_GetOptionalAttrString(const char *name, PyObject **result)
 
@@ -301,7 +301,7 @@ accessible to C code.  They all work with the current interpreter thread's
    specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
    rather than a :c:expr:`PyObject*`.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
 .. c:function:: PyObject *PySys_GetObject(const char *name)
 

Doc/c-api/tuple.rst

@@ -37,6 +37,19 @@ Tuple Objects
    or ``NULL`` with an exception set on failure.
 
 
+.. c:function:: PyObject* PyTuple_FromArray(PyObject *const *array, Py_ssize_t size)
+
+   Create a tuple of *size* items and copy references from *array* to the new
+   tuple.
+
+   *array* can be NULL if *size* is ``0``.
+
+   On success, return a new reference.
+   On error, set an exception and return ``NULL``.
+
+   .. versionadded:: 3.15
+
+
 .. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
 
    Return a new tuple object of size *n*,

Doc/c-api/typeobj.rst

@@ -1260,7 +1260,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
       This bit indicates that instances of the class have a :attr:`~object.__dict__`
       attribute, and that the space for the dictionary is managed by the VM.
 
-      If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` should also be set.
+      If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` must also be set.
 
       The type traverse function must call :c:func:`PyObject_VisitManagedDict`
       and its clear function must call :c:func:`PyObject_ClearManagedDict`.
@@ -1278,6 +1278,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
       This bit indicates that instances of the class should be weakly
       referenceable.
 
+      If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` must also be set.
+
       .. versionadded:: 3.12
 
       **Inheritance:**
@@ -1704,7 +1706,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    :c:func:`Py_CLEAR` macro performs the operations in a safe order.
 
    If the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit is set in the
-   :c:member:`~PyTypeObject.tp_flags` field, the traverse function must call
+   :c:member:`~PyTypeObject.tp_flags` field, the clear function must call
    :c:func:`PyObject_ClearManagedDict` like this::
 
        PyObject_ClearManagedDict((PyObject*)self);