gh-128813: soft-deprecate _Py_c_*() functions (GH-137261)

skirpichev · web-flow · commit 9ced5c4ace93 · 2025-08-01T09:40:12.000+02:00
diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst
@@ -43,24 +43,36 @@ pointers.  This is consistent throughout the API.
    Return the sum of two complex numbers, using the C :c:type:`Py_complex`
    representation.
 
+   .. deprecated:: 3.15
+      This function is :term:`soft deprecated`.
+
 
 .. c:function:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
 
    Return the difference between two complex numbers, using the C
    :c:type:`Py_complex` representation.
 
+   .. deprecated:: 3.15
+      This function is :term:`soft deprecated`.
+
 
 .. c:function:: Py_complex _Py_c_neg(Py_complex num)
 
    Return the negation of the complex number *num*, using the C
    :c:type:`Py_complex` representation.
 
+   .. deprecated:: 3.15
+      This function is :term:`soft deprecated`.
+
 
 .. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
 
    Return the product of two complex numbers, using the C :c:type:`Py_complex`
    representation.
 
+   .. deprecated:: 3.15
+      This function is :term:`soft deprecated`.
+
 
 .. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
 
@@ -70,6 +82,9 @@ pointers.  This is consistent throughout the API.
    If *divisor* is null, this method returns zero and sets
    :c:data:`errno` to :c:macro:`!EDOM`.
 
+   .. deprecated:: 3.15
+      This function is :term:`soft deprecated`.
+
 
 .. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
 
@@ -81,6 +96,19 @@ pointers.  This is consistent throughout the API.
 
    Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
 
+   .. deprecated:: 3.15
+      This function is :term:`soft deprecated`.
+
+
+.. c:function:: double _Py_c_abs(Py_complex num)
+
+   Return the absolute value of the complex number *num*.
+
+   Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
+
+   .. deprecated:: 3.15
+      This function is :term:`soft deprecated`.
+
 
 Complex Numbers as Python Objects
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Doc/whatsnew/3.15.rst b/Doc/whatsnew/3.15.rst
@@ -548,6 +548,11 @@ Deprecated C APIs
   signed integer type of the same size is now deprecated.
   (Contributed by Serhiy Storchaka in :gh:`132629`.)
 
+* 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`.
+  (Contributed by Sergey B Kirpichev in :gh:`128813`.)
+
 .. Add C API deprecations above alphabetically, not here at the end.
 
 Removed C APIs
diff --git a/Include/cpython/complexobject.h b/Include/cpython/complexobject.h
@@ -7,7 +7,8 @@ typedef struct {
     double imag;
 } Py_complex;
 
-// Operations on complex numbers.
+/* Operations on complex numbers (soft deprecated
+   since Python 3.15). */
 PyAPI_FUNC(Py_complex) _Py_c_sum(Py_complex, Py_complex);
 PyAPI_FUNC(Py_complex) _Py_c_diff(Py_complex, Py_complex);
 PyAPI_FUNC(Py_complex) _Py_c_neg(Py_complex);
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
@@ -0,0 +1,4 @@
+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`.
+Patch by Sergey B Kirpichev.
