https://github.com/python/cpython/commit/bc4996c125b3cd5c73d41c6bf4e71571a2b832c2
commit: bc4996c125b3cd5c73d41c6bf4e71571a2b832c2
branch: main
author: Sergey B Kirpichev <skirpic...@gmail.com>
committer: encukou <encu...@gmail.com>
date: 2025-08-11T13:51:39+02:00
summary:
gh-128813: cleanup C-API docs for PyComplexObject (GH-137579)
* move non-deprecated API up
* make a dedicated section for deprecated low-leved API
files:
M Doc/c-api/complex.rst
diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst
index a1fd27ad0acd2e..aa91b85d07fc7e 100644
--- a/Doc/c-api/complex.rst
+++ b/Doc/c-api/complex.rst
@@ -3,116 +3,10 @@
.. _complexobjects:
Complex Number Objects
-----------------------
+======================
.. index:: pair: object; complex number
-Python's complex number objects are implemented as two distinct types when
-viewed from the C API: one is the Python object exposed to Python programs,
and
-the other is a C structure which represents the actual complex number value.
-The API provides functions for working with both.
-
-
-Complex Numbers as C Structures
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Note that the functions which accept these structures as parameters and return
-them as results do so *by value* rather than dereferencing them through
-pointers. This is consistent throughout the API.
-
-
-.. c:type:: Py_complex
-
- The C structure which corresponds to the value portion of a Python complex
- number object. Most of the functions for dealing with complex number
objects
- use structures of this type as input or output values, as appropriate.
-
- .. c:member:: double real
- double imag
-
- The structure is defined as::
-
- typedef struct {
- double real;
- double imag;
- } Py_complex;
-
-
-.. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
-
- 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)
-
- Return the quotient of two complex numbers, using the C :c:type:`Py_complex`
- representation.
-
- 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)
-
- Return the exponentiation of *num* by *exp*, using the C
:c:type:`Py_complex`
- representation.
-
- If *num* is null and *exp* is not a positive real number,
- this method returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`.
-
- 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
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
.. c:type:: PyComplexObject
@@ -147,12 +41,6 @@ Complex Numbers as Python Objects
:c:type:`PyComplexObject`. This function always succeeds.
-.. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)
-
- Create a new Python complex number object from a C :c:type:`Py_complex`
value.
- Return ``NULL`` with an exception set on error.
-
-
.. c:function:: PyObject* PyComplex_FromDoubles(double real, double imag)
Return a new :c:type:`PyComplexObject` object from *real* and *imag*.
@@ -191,6 +79,29 @@ Complex Numbers as Python Objects
.. versionchanged:: 3.13
Use :meth:`~object.__complex__` if available.
+
+.. c:type:: Py_complex
+
+ This C structure defines export format for a Python complex
+ number object.
+
+ .. c:member:: double real
+ double imag
+
+ The structure is defined as::
+
+ typedef struct {
+ double real;
+ double imag;
+ } Py_complex;
+
+
+.. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)
+
+ Create a new Python complex number object from a C :c:type:`Py_complex`
value.
+ Return ``NULL`` with an exception set on error.
+
+
.. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)
Return the :c:type:`Py_complex` value of the complex number *op*.
@@ -207,3 +118,82 @@ Complex Numbers as Python Objects
.. versionchanged:: 3.8
Use :meth:`~object.__index__` if available.
+
+
+Complex Numbers as C Structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The API also provides functions for working with complex numbers, using the
+:c:type:`Py_complex` representation. Note that the functions which accept
+these structures as parameters and return them as results do so *by value*
+rather than dereferencing them through pointers.
+
+Please note, that these functions are :term:`soft deprecated` since Python
+3.15. Avoid using this API in a new code to do complex arithmetic: either use
+the `Number Protocol <number>`_ API or use native complex types, like
+:c:expr:`double complex`.
+
+
+.. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
+
+ Return the sum of two complex numbers, using the C :c:type:`Py_complex`
+ representation.
+
+ .. deprecated:: 3.15
+
+
+.. 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
+
+
+.. 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
+
+
+.. 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
+
+
+.. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
+
+ Return the quotient of two complex numbers, using the C :c:type:`Py_complex`
+ representation.
+
+ If *divisor* is null, this method returns zero and sets
+ :c:data:`errno` to :c:macro:`!EDOM`.
+
+ .. deprecated:: 3.15
+
+
+.. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
+
+ Return the exponentiation of *num* by *exp*, using the C
:c:type:`Py_complex`
+ representation.
+
+ If *num* is null and *exp* is not a positive real number,
+ this method returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`.
+
+ Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
+
+ .. deprecated:: 3.15
+
+
+.. 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
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: arch...@mail-archive.com
