From 9743d069bd53e9d3a8f09df899ec1c906a79da24 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Fri, 8 Aug 2025 13:36:42 +0300 Subject: [PATCH] gh-128813: deprecate cval field of the PyComplexObject struct (#137271) Co-authored-by: Petr Viktorin Co-authored-by: Victor Stinner --- Doc/c-api/complex.rst | 10 ++++++++++ Doc/deprecations/c-api-pending-removal-in-3.20.rst | 7 +++++++ Doc/deprecations/index.rst | 2 ++ Doc/whatsnew/3.15.rst | 7 +++++++ .../2025-07-31-04-30-42.gh-issue-128813.opL-Pv.rst | 5 +++-- 5 files changed, 29 insertions(+), 2 deletions(-) create mode 100644 Doc/deprecations/c-api-pending-removal-in-3.20.rst diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst index 34488848f87c..a1fd27ad0acd 100644 --- a/Doc/c-api/complex.rst +++ b/Doc/c-api/complex.rst @@ -118,6 +118,16 @@ Complex Numbers as Python Objects This subtype of :c:type:`PyObject` represents a Python complex number object. + .. c:member:: Py_complex cval + + The complex number value, using the C :c:type:`Py_complex` representation. + + .. deprecated-removed:: next 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` + representation. + .. c:var:: PyTypeObject PyComplex_Type diff --git a/Doc/deprecations/c-api-pending-removal-in-3.20.rst b/Doc/deprecations/c-api-pending-removal-in-3.20.rst new file mode 100644 index 000000000000..82f975d6ed40 --- /dev/null +++ b/Doc/deprecations/c-api-pending-removal-in-3.20.rst @@ -0,0 +1,7 @@ +Pending removal in Python 3.20 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* The ``cval`` field in :c:type:`PyComplexObject` (:gh:`128813`). + Use :c:func:`PyComplex_AsCComplex` and :c:func:`PyComplex_FromCComplex` + to convert a Python complex number to/from the C :c:type:`Py_complex` + representation. diff --git a/Doc/deprecations/index.rst b/Doc/deprecations/index.rst index d064f2bec42c..c6e05c176b2a 100644 --- a/Doc/deprecations/index.rst +++ b/Doc/deprecations/index.rst @@ -18,4 +18,6 @@ C API deprecations .. include:: c-api-pending-removal-in-3.18.rst +.. include:: c-api-pending-removal-in-3.20.rst + .. include:: c-api-pending-removal-in-future.rst diff --git a/Doc/whatsnew/3.15.rst b/Doc/whatsnew/3.15.rst index 89644a509a0b..93f56eed8570 100644 --- a/Doc/whatsnew/3.15.rst +++ b/Doc/whatsnew/3.15.rst @@ -570,6 +570,13 @@ Deprecated C APIs signed integer type of the same size is now deprecated. (Contributed by Serhiy Storchaka in :gh:`132629`.) +* Deprecate :c:member:`~PyComplexObject.cval` field of the the + :c:type:`PyComplexObject` type. + Use :c:func:`PyComplex_AsCComplex` and :c:func:`PyComplex_FromCComplex` + to convert a Python complex number to/from the C :c:type:`Py_complex` + representation. + (Contributed by Sergey B Kirpichev in :gh:`128813`.) + * Functions :c:func:`_Py_c_sum`, :c:func:`_Py_c_diff`, :c:func:`_Py_c_neg`, :c:func:`_Py_c_prod`, :c:func:`_Py_c_quot`, :c:func:`_Py_c_pow` and :c:func:`_Py_c_abs` are :term:`soft deprecated`. diff --git a/Misc/NEWS.d/next/C_API/2025-07-31-04-30-42.gh-issue-128813.opL-Pv.rst b/Misc/NEWS.d/next/C_API/2025-07-31-04-30-42.gh-issue-128813.opL-Pv.rst index 625989b33704..caa8f3e9c985 100644 --- a/Misc/NEWS.d/next/C_API/2025-07-31-04-30-42.gh-issue-128813.opL-Pv.rst +++ b/Misc/NEWS.d/next/C_API/2025-07-31-04-30-42.gh-issue-128813.opL-Pv.rst @@ -1,4 +1,5 @@ Functions :c:func:`_Py_c_sum`, :c:func:`_Py_c_diff`, :c:func:`_Py_c_neg`, -:c:func:`_Py_c_prod`, :c:func:`_Py_c_quot`, :c:func:`_Py_c_pow` and -previously undocumented :c:func:`_Py_c_abs` are :term:`soft deprecated`. +:c:func:`_Py_c_prod`, :c:func:`_Py_c_quot`, :c:func:`_Py_c_pow` and previously +undocumented :c:func:`_Py_c_abs` are :term:`soft deprecated`. Deprecate also +:c:member:`~PyComplexObject.cval` field of the :c:type:`PyComplexObject` type. Patch by Sergey B Kirpichev. -- 2.47.3