gh-128813: deprecate cval field of the PyComplexObject struct

skirpichev · skirpichev · commit 7cb20b1cc5c0 · 2025-07-31T13:50:35.000+03:00
diff --git 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
@@ -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
@@ -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
@@ -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/Include/cpython/complexobject.h b/Include/cpython/complexobject.h
@@ -26,7 +26,7 @@ real and imaginary parts.
 */
 typedef struct {
     PyObject_HEAD
-    Py_complex cval;
+    Py_DEPRECATED(3.15) Py_complex cval;
 } PyComplexObject;
 
 PyAPI_FUNC(PyObject *) PyComplex_FromCComplex(Py_complex);
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
@@ -0,0 +1,2 @@
+Document and deprecate :c:member:`~PyComplexObject.cval` field of
+the :c:type:`PyComplexObject` type.  Patch by Sergey B Kirpichev.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+Document and deprecate :c:member:`~PyComplexObject.cval` field of
	`2`	+the :c:type:`PyComplexObject` type. Patch by Sergey B Kirpichev.