gh-128813: deprecate cval field of the PyComplexObject struct (#137271)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Victor Stinner <vstinner@python.org>

diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst
index 34488848f87cd1a9440408360ae8a742c9816548..a1fd27ad0acd2e8353064e3f99153bec3dcfb541 100644 (file)
--- 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 (file)
index 0000000..82f975d
--- /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 d064f2bec42c229225dfeccd73bdd234cab2632c..c6e05c176b2aa1764261cfa018aeb88ab2cfe500 100644 (file)
--- 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 89644a509a0bb4aa55e3fad1a4cfd84620364e9b..93f56eed857068e08b39f3ec3699618c7ea08091 100644 (file)
--- 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 625989b33704a734f2936fb0f0b761eb5a193ca5..caa8f3e9c985cd5b532c1ef6037f0610ca058056 100644 (file)
--- 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.