gh-150671: Deprecate `PyAsyncGen_New`, `PyCoro_New`, `PyGen_New`, `PyGen_NewWithQualN...

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

diff --git a/Doc/c-api/coro.rst b/Doc/c-api/coro.rst
index caa855a10d20ca93c66e33967671f1116d491efd..06422fb63f34f1ad70df95edf52efe43e9a65e14 100644 (file)
--- a/Doc/c-api/coro.rst
+++ b/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.

diff --git a/Doc/c-api/gen.rst b/Doc/c-api/gen.rst
index ed121726b89620c20e2048bfdeda62ffbe8048ed..7713ba2ee4f8047840f6ee72567e75367c6b50ce 100644 (file)
--- a/Doc/c-api/gen.rst
+++ b/Doc/c-api/gen.rst
@@ -38,6 +38,12 @@ 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,
@@ -45,6 +51,12 @@ than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`.
    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.

diff --git a/Doc/deprecations/c-api-pending-removal-in-3.18.rst b/Doc/deprecations/c-api-pending-removal-in-3.18.rst
index 022aee93aa70c47798a26df4457eea7303c353f4..820334ee43c82e4e61b28d8fc73f2627e3fbd3aa 100644 (file)
--- a/Doc/deprecations/c-api-pending-removal-in-3.18.rst
+++ b/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

diff --git a/Doc/whatsnew/3.16.rst b/Doc/whatsnew/3.16.rst
index 6c35124ba7b486507aceb6c29aea2c3fb3299c49..8e4c4a1e9b1de028b89369224265d7df9270958f 100644 (file)
--- a/Doc/whatsnew/3.16.rst
+++ b/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
 --------------

diff --git a/Include/cpython/genobject.h b/Include/cpython/genobject.h
index f75884e597e2c247f211d0159f72b051070531d0..e14facd77edec53394e93363bb60bf2bb2129ba0 100644 (file)
--- a/Include/cpython/genobject.h
+++ b/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)

diff --git a/Misc/NEWS.d/next/C_API/2026-05-31-15-39-58.gh-issue-150671.bTkDVC.rst b/Misc/NEWS.d/next/C_API/2026-05-31-15-39-58.gh-issue-150671.bTkDVC.rst
new file mode 100644 (file)
index 0000000..a67a0f8
--- /dev/null
+++ b/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