From 184ec8a80b977eee4a4e665699b20a0ee14870a3 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Sun, 31 May 2026 15:47:29 +0300 Subject: [PATCH 1/2] gh-150671: Deprecate `PyAsyncGen_New`, `PyCoro_New`, `PyGen_New`, `PyGen_NewWithQualName` functions --- Doc/c-api/coro.rst | 6 ++++++ Doc/c-api/gen.rst | 18 ++++++++++++++++++ .../c-api-pending-removal-in-3.18.rst | 4 ++++ Doc/whatsnew/3.16.rst | 14 +++++++++++++- Include/cpython/genobject.h | 8 ++++---- ...6-05-31-15-39-58.gh-issue-150671.bTkDVC.rst | 5 +++++ 6 files changed, 50 insertions(+), 5 deletions(-) create mode 100644 Misc/NEWS.d/next/C_API/2026-05-31-15-39-58.gh-issue-150671.bTkDVC.rst diff --git a/Doc/c-api/coro.rst b/Doc/c-api/coro.rst index caa855a10d20ca9..edf88872db3255b 100644 --- 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 was not used since 3.10, + it is now 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 ed121726b89620c..c996a0756a35156 100644 --- 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 was not used since 3.10, + it is now 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 was not used since 3.10, + it is now 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 was not used since 3.10, + it is now 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 022aee93aa70c47..820334ee43c82e4 100644 --- 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 `__ can be used to get diff --git a/Doc/whatsnew/3.16.rst b/Doc/whatsnew/3.16.rst index 9a0a0d3d8831f5f..f71155df485cfe1 100644 --- a/Doc/whatsnew/3.16.rst +++ b/Doc/whatsnew/3.16.rst @@ -239,6 +239,8 @@ 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 @@ -290,9 +292,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 f75884e597e2c24..e14facd77edec53 100644 --- 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 index 000000000000000..b52a6e4d21cbca5 --- /dev/null +++ b/Misc/NEWS.d/next/C_API/2026-05-31-15-39-58.gh-issue-150671.bTkDVC.rst @@ -0,0 +1,5 @@ +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 From 00d16035805a851da5b293191618623976585aa5 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Sun, 31 May 2026 18:52:46 +0300 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Peter Bierma --- Doc/c-api/coro.rst | 4 ++-- Doc/c-api/gen.rst | 12 ++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/Doc/c-api/coro.rst b/Doc/c-api/coro.rst index edf88872db3255b..06422fb63f34f1a 100644 --- a/Doc/c-api/coro.rst +++ b/Doc/c-api/coro.rst @@ -36,6 +36,6 @@ return. .. deprecated-removed:: 3.16 3.18 - This function was not used since 3.10, - it is now impossible to construct a proper *frame* + 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 c996a0756a35156..7713ba2ee4f8047 100644 --- a/Doc/c-api/gen.rst +++ b/Doc/c-api/gen.rst @@ -40,8 +40,8 @@ than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`. .. deprecated-removed:: 3.16 3.18 - This function was not used since 3.10, - it is now impossible to construct a proper *frame* + 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) @@ -53,8 +53,8 @@ than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`. .. deprecated-removed:: 3.16 3.18 - This function was not used since 3.10, - it is now impossible to construct a proper *frame* + This function has not been used since 3.10. + It is also impossible to construct a proper *frame* object to call this function. @@ -91,8 +91,8 @@ Asynchronous Generator Objects .. deprecated-removed:: 3.16 3.18 - This function was not used since 3.10, - it is now impossible to construct a proper *frame* + 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)