Skip to content

gh-128813: cleanup C-API docs for PyComplexObject #137579

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 11, 2025
Merged

gh-128813: cleanup C-API docs for PyComplexObject #137579

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
216 changes: 103 additions & 113 deletions Doc/c-api/complex.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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*.
Expand Down Expand Up @@ -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*.
Expand All @@ -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
Loading