gh-150671: Deprecate PyAsyncGen_New, PyCoro_New, PyGen_New, PyGen_NewWithQualName functions (#150672)

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: Victor Stinner <vstinner@python.org>

Author: 3 people

Doc/c-api/coro.rst

@@ -33,3 +33,9 @@ return.
    with ``__name__`` and ``__qualname__`` set to *name* and *qualname*.
    A reference to *frame* is stolen by this function.  The *frame* argument
    must not be ``NULL``.
+
+   .. deprecated-removed:: 3.16 3.18
+
+      This function has not been used since 3.10.
+      It is also impossible to construct a proper *frame*
+      object to call this function.

Doc/c-api/gen.rst

@@ -38,13 +38,25 @@ than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`.
    A reference to *frame* is stolen by this function. The argument must not be
    ``NULL``.
 
+   .. deprecated-removed:: 3.16 3.18
+
+      This function has not been used since 3.10.
+      It is also impossible to construct a proper *frame*
+      object to call this function.
+
 .. c:function:: PyObject* PyGen_NewWithQualName(PyFrameObject *frame, PyObject *name, PyObject *qualname)
 
    Create and return a new generator object based on the *frame* object,
    with ``__name__`` and ``__qualname__`` set to *name* and *qualname*.
    A reference to *frame* is stolen by this function.  The *frame* argument
    must not be ``NULL``.
 
+   .. deprecated-removed:: 3.16 3.18
+
+      This function has not been used since 3.10.
+      It is also impossible to construct a proper *frame*
+      object to call this function.
+
 
 .. c:function:: PyCodeObject* PyGen_GetCode(PyGenObject *gen)
 
@@ -77,6 +89,12 @@ Asynchronous Generator Objects
 
    .. versionadded:: 3.6
 
+   .. deprecated-removed:: 3.16 3.18
+
+      This function has not been used since 3.10.
+      It is also impossible to construct a proper *frame*
+      object to call this function.
+
 .. c:function:: int PyAsyncGen_CheckExact(PyObject *op)
 
    Return true if *op* is an asynchronous generator object, false otherwise.

Doc/deprecations/c-api-pending-removal-in-3.18.rst

@@ -40,6 +40,10 @@ Pending removal in Python 3.18
   * :c:func:`!_PyUnicodeWriter_PrepareKind`: (no replacement).
   * :c:func:`!_Py_HashPointer`: use :c:func:`Py_HashPointer`.
   * :c:func:`!_Py_fopen_obj`: use :c:func:`Py_fopen`.
+  * :c:func:`PyGen_New`: (no replacement).
+  * :c:func:`PyGen_NewWithQualName`: (no replacement).
+  * :c:func:`PyCoro_New`: (no replacement).
+  * :c:func:`PyAsyncGen_New`: (no replacement).
 
   The `pythoncapi-compat project
   <https://github.com/python/pythoncapi-compat/>`__ can be used to get

Doc/whatsnew/3.16.rst

@@ -275,10 +275,14 @@ Deprecated
 
 .. include:: ../deprecations/pending-removal-in-3.17.rst
 
+.. include:: ../deprecations/pending-removal-in-3.18.rst
+
 .. include:: ../deprecations/pending-removal-in-3.19.rst
 
 .. include:: ../deprecations/pending-removal-in-3.20.rst
 
+.. include:: ../deprecations/pending-removal-in-3.21.rst
+
 .. include:: ../deprecations/pending-removal-in-future.rst
 
 
@@ -326,9 +330,19 @@ Porting to Python 3.16
 Deprecated C APIs
 -----------------
 
-* TODO
+* :c:func:`PyGen_New`, :c:func:`PyGen_NewWithQualName`, :c:func:`PyCoro_New`,
+  and :c:func:`PyAsyncGen_New` are deprecated.
+  They are scheduled for removal in 3.18.
 
 .. Add C API deprecations above alphabetically, not here at the end.
 
+.. include:: ../deprecations/c-api-pending-removal-in-3.18.rst
+
+.. include:: ../deprecations/c-api-pending-removal-in-3.19.rst
+
+.. include:: ../deprecations/c-api-pending-removal-in-3.20.rst
+
+.. include:: ../deprecations/c-api-pending-removal-in-future.rst
+
 Removed C APIs
 --------------

Include/cpython/genobject.h

@@ -16,8 +16,8 @@ PyAPI_DATA(PyTypeObject) PyGen_Type;
 #define PyGen_Check(op) PyObject_TypeCheck((op), &PyGen_Type)
 #define PyGen_CheckExact(op) Py_IS_TYPE((op), &PyGen_Type)
 
-PyAPI_FUNC(PyObject *) PyGen_New(PyFrameObject *);
-PyAPI_FUNC(PyObject *) PyGen_NewWithQualName(PyFrameObject *,
+Py_DEPRECATED(3.16) PyAPI_FUNC(PyObject *) PyGen_New(PyFrameObject *);
+Py_DEPRECATED(3.16) PyAPI_FUNC(PyObject *) PyGen_NewWithQualName(PyFrameObject *,
     PyObject *name, PyObject *qualname);
 PyAPI_FUNC(PyCodeObject *) PyGen_GetCode(PyGenObject *gen);
 
@@ -29,7 +29,7 @@ typedef struct _PyCoroObject PyCoroObject;
 PyAPI_DATA(PyTypeObject) PyCoro_Type;
 
 #define PyCoro_CheckExact(op) Py_IS_TYPE((op), &PyCoro_Type)
-PyAPI_FUNC(PyObject *) PyCoro_New(PyFrameObject *,
+Py_DEPRECATED(3.16) PyAPI_FUNC(PyObject *) PyCoro_New(PyFrameObject *,
     PyObject *name, PyObject *qualname);
 
 
@@ -40,7 +40,7 @@ typedef struct _PyAsyncGenObject PyAsyncGenObject;
 PyAPI_DATA(PyTypeObject) PyAsyncGen_Type;
 PyAPI_DATA(PyTypeObject) _PyAsyncGenASend_Type;
 
-PyAPI_FUNC(PyObject *) PyAsyncGen_New(PyFrameObject *,
+Py_DEPRECATED(3.16) PyAPI_FUNC(PyObject *) PyAsyncGen_New(PyFrameObject *,
     PyObject *name, PyObject *qualname);
 
 #define PyAsyncGen_CheckExact(op) Py_IS_TYPE((op), &PyAsyncGen_Type)

Misc/NEWS.d/next/C_API/2026-05-31-15-39-58.gh-issue-150671.bTkDVC.rst

@@ -0,0 +1,4 @@
+Deprecate these C-API functions: :c:func:`PyGen_New`,
+:c:func:`PyGen_NewWithQualName`, :c:func:`PyCoro_New`, and
+:c:func:`PyAsyncGen_New`.
+Schedule them for removal in 3.18