From 40fc415af04e86d1833c34f7e71c215d4e240a26 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Thu, 31 Jul 2025 13:38:52 +0300 Subject: [PATCH 1/8] gh-128813: deprecate cval field of the PyComplexObject struct --- Doc/c-api/complex.rst | 6 ++++++ Doc/deprecations/c-api-pending-removal-in-3.17.rst | 4 ++++ Doc/deprecations/index.rst | 2 ++ Doc/whatsnew/3.15.rst | 4 ++++ .../C_API/2025-07-31-11-53-38.gh-issue-128813.axQIxb.rst | 2 ++ 5 files changed, 18 insertions(+) create mode 100644 Doc/deprecations/c-api-pending-removal-in-3.17.rst create mode 100644 Misc/NEWS.d/next/C_API/2025-07-31-11-53-38.gh-issue-128813.axQIxb.rst diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst index 34488848f87cd1..3dc896506a1fdd 100644 --- a/Doc/c-api/complex.rst +++ b/Doc/c-api/complex.rst @@ -118,6 +118,12 @@ 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:: 3.15 + .. c:var:: PyTypeObject PyComplex_Type diff --git a/Doc/deprecations/c-api-pending-removal-in-3.17.rst b/Doc/deprecations/c-api-pending-removal-in-3.17.rst new file mode 100644 index 00000000000000..6a4b7c8f390b95 --- /dev/null +++ b/Doc/deprecations/c-api-pending-removal-in-3.17.rst @@ -0,0 +1,4 @@ +Pending removal in Python 3.17 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* The ``cval`` field in :c:type:`PyComplexObject` (:gh:`128813`). diff --git a/Doc/deprecations/index.rst b/Doc/deprecations/index.rst index d064f2bec42c22..d66a27e6dd932c 100644 --- a/Doc/deprecations/index.rst +++ b/Doc/deprecations/index.rst @@ -16,6 +16,8 @@ C API deprecations .. include:: c-api-pending-removal-in-3.15.rst +.. include:: c-api-pending-removal-in-3.17.rst + .. include:: c-api-pending-removal-in-3.18.rst .. include:: c-api-pending-removal-in-future.rst diff --git a/Doc/whatsnew/3.15.rst b/Doc/whatsnew/3.15.rst index 1e54a61a449adc..beb47e03eaae28 100644 --- a/Doc/whatsnew/3.15.rst +++ b/Doc/whatsnew/3.15.rst @@ -548,6 +548,10 @@ 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. + (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-11-53-38.gh-issue-128813.axQIxb.rst b/Misc/NEWS.d/next/C_API/2025-07-31-11-53-38.gh-issue-128813.axQIxb.rst new file mode 100644 index 00000000000000..5a4fb12f996517 --- /dev/null +++ b/Misc/NEWS.d/next/C_API/2025-07-31-11-53-38.gh-issue-128813.axQIxb.rst @@ -0,0 +1,2 @@ +Document and deprecate :c:member:`~PyComplexObject.cval` field of +the :c:type:`PyComplexObject` type. Patch by Sergey B Kirpichev. From 6f12297f38a1f894dbda75405dfe31fb0dcd55de Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Fri, 1 Aug 2025 19:03:06 +0300 Subject: [PATCH 2/8] Update Doc/c-api/complex.rst Co-authored-by: Petr Viktorin --- Doc/c-api/complex.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst index 3dc896506a1fdd..251c07065f9b58 100644 --- a/Doc/c-api/complex.rst +++ b/Doc/c-api/complex.rst @@ -122,7 +122,7 @@ Complex Numbers as Python Objects The complex number value, using the C :c:type:`Py_complex` representation. - .. deprecated:: 3.15 + .. deprecated-removed:: next 3.17 .. c:var:: PyTypeObject PyComplex_Type From 6fd0b44ba795c3884c0219713b481e9696e3dec9 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Fri, 1 Aug 2025 19:09:28 +0300 Subject: [PATCH 3/8] address review: merge news --- .../C_API/2025-07-31-04-30-42.gh-issue-128813.opL-Pv.rst | 5 +++-- .../C_API/2025-07-31-11-53-38.gh-issue-128813.axQIxb.rst | 2 -- 2 files changed, 3 insertions(+), 4 deletions(-) delete mode 100644 Misc/NEWS.d/next/C_API/2025-07-31-11-53-38.gh-issue-128813.axQIxb.rst 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 625989b33704a7..caa8f3e9c985cd 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. diff --git a/Misc/NEWS.d/next/C_API/2025-07-31-11-53-38.gh-issue-128813.axQIxb.rst b/Misc/NEWS.d/next/C_API/2025-07-31-11-53-38.gh-issue-128813.axQIxb.rst deleted file mode 100644 index 5a4fb12f996517..00000000000000 --- a/Misc/NEWS.d/next/C_API/2025-07-31-11-53-38.gh-issue-128813.axQIxb.rst +++ /dev/null @@ -1,2 +0,0 @@ -Document and deprecate :c:member:`~PyComplexObject.cval` field of -the :c:type:`PyComplexObject` type. Patch by Sergey B Kirpichev. From dde16f1215d1d7593f8fc26e8c73d3e107d7edb0 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Wed, 6 Aug 2025 06:12:01 +0300 Subject: [PATCH 4/8] address review: suggest PyComplex_AsCComplex/PyComplex_FromCComplex --- Doc/c-api/complex.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst index 251c07065f9b58..1c73600bb3976e 100644 --- a/Doc/c-api/complex.rst +++ b/Doc/c-api/complex.rst @@ -123,6 +123,9 @@ Complex Numbers as Python Objects The complex number value, using the C :c:type:`Py_complex` representation. .. deprecated-removed:: next 3.17 + Use instead :c:func:`PyComplex_AsCComplex` and + :c:func:`PyComplex_FromCComplex` to access/set a Python complex + number, using the C :c:type:`Py_complex` representation. .. c:var:: PyTypeObject PyComplex_Type From 028e8b16bf721355120203c426882474f648e7dd Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Thu, 7 Aug 2025 19:29:57 +0300 Subject: [PATCH 5/8] address review: delay removal to 3.20 --- Doc/c-api/complex.rst | 2 +- ...-removal-in-3.17.rst => c-api-pending-removal-in-3.20.rst} | 2 +- Doc/deprecations/index.rst | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) rename Doc/deprecations/{c-api-pending-removal-in-3.17.rst => c-api-pending-removal-in-3.20.rst} (75%) diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst index 1c73600bb3976e..16ee1666e2ef00 100644 --- a/Doc/c-api/complex.rst +++ b/Doc/c-api/complex.rst @@ -122,7 +122,7 @@ Complex Numbers as Python Objects The complex number value, using the C :c:type:`Py_complex` representation. - .. deprecated-removed:: next 3.17 + .. deprecated-removed:: next 3.20 Use instead :c:func:`PyComplex_AsCComplex` and :c:func:`PyComplex_FromCComplex` to access/set a Python complex number, using the C :c:type:`Py_complex` representation. diff --git a/Doc/deprecations/c-api-pending-removal-in-3.17.rst b/Doc/deprecations/c-api-pending-removal-in-3.20.rst similarity index 75% rename from Doc/deprecations/c-api-pending-removal-in-3.17.rst rename to Doc/deprecations/c-api-pending-removal-in-3.20.rst index 6a4b7c8f390b95..40a9f20a355088 100644 --- a/Doc/deprecations/c-api-pending-removal-in-3.17.rst +++ b/Doc/deprecations/c-api-pending-removal-in-3.20.rst @@ -1,4 +1,4 @@ -Pending removal in Python 3.17 +Pending removal in Python 3.20 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * The ``cval`` field in :c:type:`PyComplexObject` (:gh:`128813`). diff --git a/Doc/deprecations/index.rst b/Doc/deprecations/index.rst index d66a27e6dd932c..c6e05c176b2aa1 100644 --- a/Doc/deprecations/index.rst +++ b/Doc/deprecations/index.rst @@ -16,8 +16,8 @@ C API deprecations .. include:: c-api-pending-removal-in-3.15.rst -.. include:: c-api-pending-removal-in-3.17.rst - .. 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 From a923733a359f6f9950bdb27fa2cc29949ee75724 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Fri, 8 Aug 2025 11:32:39 +0300 Subject: [PATCH 6/8] Update Doc/c-api/complex.rst Co-authored-by: Petr Viktorin --- Doc/c-api/complex.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst index 16ee1666e2ef00..a1fd27ad0acd2e 100644 --- a/Doc/c-api/complex.rst +++ b/Doc/c-api/complex.rst @@ -123,9 +123,10 @@ Complex Numbers as Python Objects The complex number value, using the C :c:type:`Py_complex` representation. .. deprecated-removed:: next 3.20 - Use instead :c:func:`PyComplex_AsCComplex` and - :c:func:`PyComplex_FromCComplex` to access/set a Python complex - number, using the C :c:type:`Py_complex` representation. + 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 From ca67c2aa1dcc5ce027989e6f67bcc0872588b526 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Fri, 8 Aug 2025 12:50:49 +0300 Subject: [PATCH 7/8] address review: suggest PyComplex_AsCComplex/PyComplex_FromCComplex --- Doc/deprecations/c-api-pending-removal-in-3.20.rst | 5 ++++- Doc/whatsnew/3.15.rst | 5 ++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/Doc/deprecations/c-api-pending-removal-in-3.20.rst b/Doc/deprecations/c-api-pending-removal-in-3.20.rst index 40a9f20a355088..b88fde0ccdbfbe 100644 --- a/Doc/deprecations/c-api-pending-removal-in-3.20.rst +++ b/Doc/deprecations/c-api-pending-removal-in-3.20.rst @@ -1,4 +1,7 @@ Pending removal in Python 3.20 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* The ``cval`` field in :c:type:`PyComplexObject` (:gh:`128813`). +* 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/whatsnew/3.15.rst b/Doc/whatsnew/3.15.rst index a5e240a325f499..18d3809c464691 100644 --- a/Doc/whatsnew/3.15.rst +++ b/Doc/whatsnew/3.15.rst @@ -571,7 +571,10 @@ Deprecated C APIs (Contributed by Serhiy Storchaka in :gh:`132629`.) * Deprecate :c:member:`~PyComplexObject.cval` field of the the - :c:type:`PyComplexObject` type. + :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`, From 7e491dc88988002530cb0d1dd2a7c5c6c0e0a315 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Fri, 8 Aug 2025 12:30:08 +0200 Subject: [PATCH 8/8] Apply suggestions from code review --- Doc/deprecations/c-api-pending-removal-in-3.20.rst | 2 +- Doc/whatsnew/3.15.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/deprecations/c-api-pending-removal-in-3.20.rst b/Doc/deprecations/c-api-pending-removal-in-3.20.rst index b88fde0ccdbfbe..82f975d6ed4020 100644 --- a/Doc/deprecations/c-api-pending-removal-in-3.20.rst +++ b/Doc/deprecations/c-api-pending-removal-in-3.20.rst @@ -1,7 +1,7 @@ Pending removal in Python 3.20 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* The ``cval`` field in :c:type:`PyComplexObject` (:gh:`128813`): +* 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/whatsnew/3.15.rst b/Doc/whatsnew/3.15.rst index 18d3809c464691..93f56eed857068 100644 --- a/Doc/whatsnew/3.15.rst +++ b/Doc/whatsnew/3.15.rst @@ -571,7 +571,7 @@ Deprecated C APIs (Contributed by Serhiy Storchaka in :gh:`132629`.) * Deprecate :c:member:`~PyComplexObject.cval` field of the the - :c:type:`PyComplexObject` type: + :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.