Merge branch 'main' into gh-125866-again

Author: barneygale

.azure-pipelines/ci.yml

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

.editorconfig

@@ -1,6 +1,6 @@
 root = true
 
-[*.{py,c,cpp,h,js,rst,md,yml}]
+[*.{py,c,cpp,h,js,rst,md,yml,yaml}]
 trim_trailing_whitespace = true
 insert_final_newline = true
 indent_style = space
@@ -11,5 +11,5 @@ indent_size = 4
 [*.rst]
 indent_size = 3
 
-[*.{js,yml}]
+[*.{js,yml,yaml}]
 indent_size = 2

.github/PULL_REQUEST_TEMPLATE.md

@@ -7,10 +7,10 @@ Please read this comment in its entirety. It's quite important.
 It should be in the following format:
 
 ```
-gh-NNNNN: Summary of the changes made
+gh-NNNNNN: Summary of the changes made
 ```
 
-Where: gh-NNNNN refers to the GitHub issue number.
+Where: gh-NNNNNN refers to the GitHub issue number.
 
 Most PRs will require an issue number. Trivial changes, like fixing a typo, do not need an issue.
 
@@ -20,11 +20,11 @@ If this is a backport PR (PR made against branches other than `main`),
 please ensure that the PR title is in the following format:
 
 ```
-[X.Y] <title from the original PR> (GH-NNNN)
+[X.Y] <title from the original PR> (GH-NNNNNN)
 ```
 
-Where: [X.Y] is the branch name, e.g. [3.6].
+Where: [X.Y] is the branch name, for example: [3.13].
 
-GH-NNNN refers to the PR number from `main`.
+GH-NNNNNN refers to the PR number from `main`.
 
 -->

Doc/c-api/gcsupport.rst

@@ -277,7 +277,7 @@ the garbage collector.
 
    Type of the visitor function to be passed to :c:func:`PyUnstable_GC_VisitObjects`.
    *arg* is the same as the *arg* passed to ``PyUnstable_GC_VisitObjects``.
-   Return ``0`` to continue iteration, return ``1`` to stop iteration. Other return
+   Return ``1`` to continue iteration, return ``0`` to stop iteration. Other return
    values are reserved for now so behavior on returning anything else is undefined.
 
    .. versionadded:: 3.12

Doc/c-api/typeobj.rst

@@ -611,7 +611,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    Note that the :c:member:`~PyVarObject.ob_size` field may later be used for
    other purposes. For example, :py:type:`int` instances use the bits of
    :c:member:`~PyVarObject.ob_size` in an implementation-defined
-   way; the underlying storage and its size should be acessed using
+   way; the underlying storage and its size should be accessed using
    :c:func:`PyLong_Export`.
 
    .. note::
@@ -703,10 +703,13 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
    .. code-block:: c
 
-     static void foo_dealloc(foo_object *self) {
+     static void
+     foo_dealloc(PyObject *op)
+     {
+         foo_object *self = (foo_object *) op;
          PyObject_GC_UnTrack(self);
          Py_CLEAR(self->ref);
-         Py_TYPE(self)->tp_free((PyObject *)self);
+         Py_TYPE(self)->tp_free(self);
      }
 
    Finally, if the type is heap allocated (:c:macro:`Py_TPFLAGS_HEAPTYPE`), the
@@ -717,10 +720,12 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
    .. code-block:: c
 
-     static void foo_dealloc(foo_object *self) {
-         PyTypeObject *tp = Py_TYPE(self);
+     static void
+     foo_dealloc(PyObject *op)
+     {
+         PyTypeObject *tp = Py_TYPE(op);
          // free references and buffers here
-         tp->tp_free(self);
+         tp->tp_free(op);
          Py_DECREF(tp);
      }
 
@@ -1416,8 +1421,9 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    :mod:`!_thread` extension module::
 
       static int
-      local_traverse(localobject *self, visitproc visit, void *arg)
+      local_traverse(PyObject *op, visitproc visit, void *arg)
       {
+          localobject *self = (localobject *) op;
           Py_VISIT(self->args);
           Py_VISIT(self->kw);
           Py_VISIT(self->dict);
@@ -1511,8 +1517,9 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    members to ``NULL``, as in the following example::
 
       static int
-      local_clear(localobject *self)
+      local_clear(PyObject *op)
       {
+          localobject *self = (localobject *) op;
           Py_CLEAR(self->key);
           Py_CLEAR(self->args);
           Py_CLEAR(self->kw);

Doc/c-api/unicode.rst

@@ -622,7 +622,7 @@ APIs:
 
    On error, set *\*p_left* to ``NULL`` and set an exception.
 
-   On sucess, set *\*p_left* to a new strong reference to the result.
+   On success, set *\*p_left* to a new strong reference to the result.
 
 
 .. c:function:: void PyUnicode_AppendAndDel(PyObject **p_left, PyObject *right)

Doc/deprecations/pending-removal-in-3.16.rst

@@ -32,7 +32,6 @@ Pending removal in Python 3.16
     * :class:`asyncio.WindowsProactorEventLoopPolicy`
     * :func:`asyncio.get_event_loop_policy`
     * :func:`asyncio.set_event_loop_policy`
-    * :func:`asyncio.set_event_loop`
 
     Users should use :func:`asyncio.run` or :class:`asyncio.Runner` with
     *loop_factory* to use the desired event loop implementation.

Doc/extending/newtypes.rst

@@ -70,22 +70,24 @@ object itself needs to be freed here as well.  Here is an example of this
 function::
 
    static void
-   newdatatype_dealloc(newdatatypeobject *obj)
+   newdatatype_dealloc(PyObject *op)
    {
-       free(obj->obj_UnderlyingDatatypePtr);
-       Py_TYPE(obj)->tp_free((PyObject *)obj);
+       newdatatypeobject *self = (newdatatypeobject *) op;
+       free(self->obj_UnderlyingDatatypePtr);
+       Py_TYPE(self)->tp_free(self);
    }
 
 If your type supports garbage collection, the destructor should call
 :c:func:`PyObject_GC_UnTrack` before clearing any member fields::
 
    static void
-   newdatatype_dealloc(newdatatypeobject *obj)
+   newdatatype_dealloc(PyObject *op)
    {
-       PyObject_GC_UnTrack(obj);
-       Py_CLEAR(obj->other_obj);
+       newdatatypeobject *self = (newdatatypeobject *) op;
+       PyObject_GC_UnTrack(op);
+       Py_CLEAR(self->other_obj);
        ...
-       Py_TYPE(obj)->tp_free((PyObject *)obj);
+       Py_TYPE(self)->tp_free(self);
    }
 
 .. index::
@@ -117,17 +119,19 @@ done.  This can be done using the :c:func:`PyErr_Fetch` and
            PyErr_Fetch(&err_type, &err_value, &err_traceback);
 
            cbresult = PyObject_CallNoArgs(self->my_callback);
-           if (cbresult == NULL)
-               PyErr_WriteUnraisable(self->my_callback);
-           else
+           if (cbresult == NULL) {
+              PyErr_WriteUnraisable(self->my_callback);
+           }
+           else {
                Py_DECREF(cbresult);
+           }
 
            /* This restores the saved exception state */
            PyErr_Restore(err_type, err_value, err_traceback);
 
            Py_DECREF(self->my_callback);
        }
-       Py_TYPE(obj)->tp_free((PyObject*)self);
+       Py_TYPE(self)->tp_free(self);
    }
 
 .. note::
@@ -168,10 +172,11 @@ representation of the instance for which it is called.  Here is a simple
 example::
 
    static PyObject *
-   newdatatype_repr(newdatatypeobject *obj)
+   newdatatype_repr(PyObject *op)
    {
+       newdatatypeobject *self = (newdatatypeobject *) op;
        return PyUnicode_FromFormat("Repr-ified_newdatatype{{size:%d}}",
-                                   obj->obj_UnderlyingDatatypePtr->size);
+                                   self->obj_UnderlyingDatatypePtr->size);
    }
 
 If no :c:member:`~PyTypeObject.tp_repr` handler is specified, the interpreter will supply a
@@ -188,10 +193,11 @@ used instead.
 Here is a simple example::
 
    static PyObject *
-   newdatatype_str(newdatatypeobject *obj)
+   newdatatype_str(PyObject *op)
    {
+       newdatatypeobject *self = (newdatatypeobject *) op;
        return PyUnicode_FromFormat("Stringified_newdatatype{{size:%d}}",
-                                   obj->obj_UnderlyingDatatypePtr->size);
+                                   self->obj_UnderlyingDatatypePtr->size);
    }
 
 
@@ -329,16 +335,16 @@ method of a class would be called.
 Here is an example::
 
    static PyObject *
-   newdatatype_getattr(newdatatypeobject *obj, char *name)
+   newdatatype_getattr(PyObject *op, char *name)
    {
-       if (strcmp(name, "data") == 0)
-       {
-           return PyLong_FromLong(obj->data);
+       newdatatypeobject *self = (newdatatypeobject *) op;
+       if (strcmp(name, "data") == 0) {
+           return PyLong_FromLong(self->data);
        }
 
        PyErr_Format(PyExc_AttributeError,
                     "'%.100s' object has no attribute '%.400s'",
-                    Py_TYPE(obj)->tp_name, name);
+                    Py_TYPE(self)->tp_name, name);
        return NULL;
    }
 
@@ -349,7 +355,7 @@ example that simply raises an exception; if this were really all you wanted, the
 :c:member:`~PyTypeObject.tp_setattr` handler should be set to ``NULL``. ::
 
    static int
-   newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)
+   newdatatype_setattr(PyObject *op, char *name, PyObject *v)
    {
        PyErr_Format(PyExc_RuntimeError, "Read-only attribute: %s", name);
        return -1;
@@ -379,8 +385,10 @@ Here is a sample implementation, for a datatype that is considered equal if the
 size of an internal pointer is equal::
 
    static PyObject *
-   newdatatype_richcmp(newdatatypeobject *obj1, newdatatypeobject *obj2, int op)
+   newdatatype_richcmp(PyObject *lhs, PyObject *rhs, int op)
    {
+       newdatatypeobject *obj1 = (newdatatypeobject *) lhs;
+       newdatatypeobject *obj2 = (newdatatypeobject *) rhs;
        PyObject *result;
        int c, size1, size2;
 
@@ -399,8 +407,7 @@ size of an internal pointer is equal::
        case Py_GE: c = size1 >= size2; break;
        }
        result = c ? Py_True : Py_False;
-       Py_INCREF(result);
-       return result;
+       return Py_NewRef(result);
     }
 
 
@@ -439,12 +446,14 @@ This function, if you choose to provide it, should return a hash number for an
 instance of your data type. Here is a simple example::
 
    static Py_hash_t
-   newdatatype_hash(newdatatypeobject *obj)
+   newdatatype_hash(PyObject *op)
    {
+       newdatatypeobject *self = (newdatatypeobject *) op;
        Py_hash_t result;
-       result = obj->some_size + 32767 * obj->some_number;
-       if (result == -1)
-          result = -2;
+       result = self->some_size + 32767 * self->some_number;
+       if (result == -1) {
+           result = -2;
+       }
        return result;
    }
 
@@ -478,8 +487,9 @@ This function takes three arguments:
 Here is a toy ``tp_call`` implementation::
 
    static PyObject *
-   newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject *kwds)
+   newdatatype_call(PyObject *op, PyObject *args, PyObject *kwds)
    {
+       newdatatypeobject *self = (newdatatypeobject *) op;
        PyObject *result;
        const char *arg1;
        const char *arg2;
@@ -490,7 +500,7 @@ Here is a toy ``tp_call`` implementation::
        }
        result = PyUnicode_FromFormat(
            "Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\n",
-           obj->obj_UnderlyingDatatypePtr->size,
+           self->obj_UnderlyingDatatypePtr->size,
            arg1, arg2, arg3);
        return result;
    }
@@ -563,12 +573,12 @@ The only further addition is that ``tp_dealloc`` needs to clear any weak
 references (by calling :c:func:`PyObject_ClearWeakRefs`)::
 
    static void
-   Trivial_dealloc(TrivialObject *self)
+   Trivial_dealloc(PyObject *op)
    {
        /* Clear weakrefs first before calling any destructors */
-       PyObject_ClearWeakRefs((PyObject *) self);
+       PyObject_ClearWeakRefs(op);
        /* ... remainder of destruction code omitted for brevity ... */
-       Py_TYPE(self)->tp_free((PyObject *) self);
+       Py_TYPE(op)->tp_free(op);
    }
 
 

Doc/howto/logging-cookbook.rst

@@ -626,6 +626,19 @@ which, when run, will produce:
    of each message with the handler's level, and only passes a message to a
    handler if it's appropriate to do so.
 
+.. versionchanged:: next
+   The :class:`QueueListener` can be started (and stopped) via the
+   :keyword:`with` statement. For example:
+
+   .. code-block:: python
+
+      with QueueListener(que, handler) as listener:
+          # The queue listener automatically starts
+          # when the 'with' block is entered.
+          pass
+      # The queue listener automatically stops once
+      # the 'with' block is exited.
+
 .. _network-logging:
 
 Sending and receiving logging events across a network

Doc/library/annotationlib.rst

@@ -303,12 +303,12 @@ Functions
 .. function:: get_annotate_function(obj)
 
    Retrieve the :term:`annotate function` for *obj*. Return :const:`!None`
-   if *obj* does not have an annotate function.
+   if *obj* does not have an annotate function. *obj* may be a class, function,
+   module, or a namespace dictionary for a class. The last case is useful during
+   class creation, e.g. in the ``__new__`` method of a metaclass.
 
    This is usually equivalent to accessing the :attr:`~object.__annotate__`
-   attribute of *obj*, but direct access to the attribute may return the wrong
-   object in certain situations involving metaclasses. This function should be
-   used instead of accessing the attribute directly.
+   attribute of *obj*, but access through this public function is preferred.
 
    .. versionadded:: 3.14