33.. _complexobjects :
44
55Complex Number Objects
6- ----------------------
6+ ======================
77
88.. index :: pair: object; complex number
99
10- Python's complex number objects are implemented as two distinct types when
11- viewed from the C API: one is the Python object exposed to Python programs, and
12- the other is a C structure which represents the actual complex number value.
13- The API provides functions for working with both.
1410
11+ .. c :type :: PyComplexObject
1512
16- Complex Numbers as C Structures
17- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13+ :c:type: `PyObject ` represents a Python complex number object.
14+
15+ .. c :member :: Py_complex cval
16+
17+ :c:type: `Py_complex ` representation.
18+
19+ .. deprecated-removed :: next 3.20
20+ Use :c:func: `PyComplex_AsCComplex ` and
21+ :c:func: `PyComplex_FromCComplex ` to convert a
22+ Python complex number to/from the C :c:type: `Py_complex `
23+ representation.
24+
25+
26+ .. c :var :: PyTypeObject PyComplex_Type
27+
28+ :c:type: `PyTypeObject ` represents the Python complex number
29+ type. It is the same object as :class: `complex ` in the Python layer.
30+
31+
32+ .. c :function :: int PyComplex_Check (PyObject *p)
33+
34+ Return true if its argument is a :c:type: `PyComplexObject ` or a subtype of
35+ :c:type: `PyComplexObject `. This function always succeeds.
36+
37+
38+ .. c :function :: int PyComplex_CheckExact (PyObject *p)
39+
40+ Return true if its argument is a :c:type: `PyComplexObject `, but not a subtype of
41+ :c:type: `PyComplexObject `. This function always succeeds.
42+
43+
44+ .. c :function :: PyObject* PyComplex_FromDoubles (double real, double imag)
45+
46+ Return a new :c:type:`PyComplexObject` object from *real* and *imag*.
47+ Return ``NULL`` with an exception set on error.
48+
49+
50+ .. c:function:: double PyComplex_RealAsDouble(PyObject *op)
51+
52+ Return the real part of *op * as a C :c:expr: `double `.
53+
54+ If *op * is not a Python complex number object but has a
55+ :meth: `~object.__complex__ ` method, this method will first be called to
56+ convert *op * to a Python complex number object. If :meth: `!__complex__ ` is
57+ not defined then it falls back to call :c:func: `PyFloat_AsDouble ` and
58+ returns its result.
59+
60+ Upon failure, this method returns ``-1.0 `` with an exception set, so one
61+ should call :c:func: `PyErr_Occurred ` to check for errors.
1862
19- Note that the functions which accept these structures as parameters and return
20- them as results do so *by value * rather than dereferencing them through
21- pointers. This is consistent throughout the API.
63+ .. versionchanged :: 3.13
64+ Use :meth: `~object.__complex__ ` if available.
65+
66+ .. c :function :: double PyComplex_ImagAsDouble (PyObject *op)
67+
68+ Return the imaginary part of *op * as a C :c:expr: `double `.
69+
70+ If *op * is not a Python complex number object but has a
71+ :meth: `~object.__complex__ ` method, this method will first be called to
72+ convert *op * to a Python complex number object. If :meth: `!__complex__ ` is
73+ not defined then it falls back to call :c:func: `PyFloat_AsDouble ` and
74+ returns ``0.0 `` on success.
75+
76+ Upon failure, this method returns ``-1.0 `` with an exception set, so one
77+ should call :c:func: `PyErr_Occurred ` to check for errors.
78+
79+ .. versionchanged :: 3.13
80+ Use :meth: `~object.__complex__ ` if available.
2281
2382
2483.. c :type :: Py_complex
2584
26-
27- number object. Most of the functions for dealing with complex number objects
28- use structures of this type as input or output values, as appropriate.
85+
86+ number object.
2987
3088 .. c :member :: double real
3189 double imag
@@ -38,13 +96,50 @@ pointers. This is consistent throughout the API.
3896 } Py_complex;
3997
4098
99+ .. c :function :: PyObject* PyComplex_FromCComplex (Py_complex v)
100+
101+ Create a new Python complex number object from a C :c:type:`Py_complex` value.
102+ Return ``NULL`` with an exception set on error.
103+
104+
105+ .. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)
106+
107+ Return the :c:type: `Py_complex ` value of the complex number *op *.
108+
109+ If *op * is not a Python complex number object but has a :meth: `~object.__complex__ `
110+ method, this method will first be called to convert *op * to a Python complex
111+ number object. If :meth: `!__complex__ ` is not defined then it falls back to
112+ :meth: `~object.__float__ `. If :meth: `!__float__ ` is not defined then it falls back
113+ to :meth: `~object.__index__ `.
114+
115+ Upon failure, this method returns :c:type: `Py_complex `
116+ with :c:member: `~Py_complex.real ` set to ``-1.0 `` and with an exception set, so one
117+ should call :c:func: `PyErr_Occurred ` to check for errors.
118+
119+ .. versionchanged :: 3.8
120+ Use :meth: `~object.__index__ ` if available.
121+
122+
123+ Complex Numbers as C Structures
124+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
125+
126+ The API also provides functions for working with complex numbers, using the
127+ :c:type: `Py_complex ` representation. Note that the functions which accept
128+ these structures as parameters and return them as results do so *by value *
129+ rather than dereferencing them through pointers.
130+
131+ Please note, that these functions are :term: `soft deprecated ` since Python
132+ 3.15. Avoid using this API in a new code to do complex arithmetic: either use
133+ the `Number Protocol <number >`_ API or use native complex types, like
134+ :c:expr: `double complex `.
135+
136+
41137.. c :function :: Py_complex _Py_c_sum (Py_complex left, Py_complex right)
42138
43139 Return the sum of two complex numbers, using the C :c:type:`Py_complex`
44140 representation.
45141
46142 .. deprecated:: 3.15
47- This function is :term:`soft deprecated`.
48143
49144
50145.. c:function:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
@@ -53,7 +148,6 @@ pointers. This is consistent throughout the API.
53148 :c:type:`Py_complex` representation.
54149
55150 .. deprecated:: 3.15
56- This function is :term:`soft deprecated`.
57151
58152
59153.. c:function:: Py_complex _Py_c_neg(Py_complex num)
@@ -62,7 +156,6 @@ pointers. This is consistent throughout the API.
62156 :c:type:`Py_complex` representation.
63157
64158 .. deprecated:: 3.15
65- This function is :term:`soft deprecated`.
66159
67160
68161.. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
@@ -71,7 +164,6 @@ pointers. This is consistent throughout the API.
71164 representation.
72165
73166 .. deprecated:: 3.15
74- This function is :term:`soft deprecated`.
75167
76168
77169.. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
@@ -83,7 +175,6 @@ pointers. This is consistent throughout the API.
83175 :c:data:`errno` to :c:macro:`!EDOM`.
84176
85177 .. deprecated:: 3.15
86- This function is :term:`soft deprecated`.
87178
88179
89180.. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
@@ -97,7 +188,6 @@ pointers. This is consistent throughout the API.
97188 Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
98189
99190 .. deprecated:: 3.15
100- This function is :term:`soft deprecated`.
101191
102192
103193.. c:function:: double _Py_c_abs(Py_complex num)
@@ -107,93 +197,3 @@ pointers. This is consistent throughout the API.
107197 Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
108198
109199 .. deprecated:: 3.15
110- This function is :term:`soft deprecated`.
111-
112-
113- Complex Numbers as Python Objects
114- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
115-
116-
117- .. c:type:: PyComplexObject
118-
119- This subtype of :c:type:`PyObject` represents a Python complex number object.
120-
121-
122- .. c:var:: PyTypeObject PyComplex_Type
123-
124- This instance of :c:type:`PyTypeObject` represents the Python complex number
125- type. It is the same object as :class:`complex` in the Python layer.
126-
127-
128- .. c:function:: int PyComplex_Check(PyObject *p)
129-
130- Return true if its argument is a :c:type: `PyComplexObject ` or a subtype of
131- :c:type: `PyComplexObject `. This function always succeeds.
132-
133-
134- .. c :function :: int PyComplex_CheckExact (PyObject *p)
135-
136- Return true if its argument is a :c:type: `PyComplexObject `, but not a subtype of
137- :c:type: `PyComplexObject `. This function always succeeds.
138-
139-
140- .. c :function :: PyObject* PyComplex_FromCComplex (Py_complex v)
141-
142- Create a new Python complex number object from a C :c:type:`Py_complex` value.
143- Return ``NULL`` with an exception set on error.
144-
145-
146- .. c:function:: PyObject* PyComplex_FromDoubles(double real, double imag)
147-
148- Return a new :c:type:`PyComplexObject` object from *real* and *imag*.
149- Return ``NULL`` with an exception set on error.
150-
151-
152- .. c:function:: double PyComplex_RealAsDouble(PyObject *op)
153-
154- Return the real part of *op * as a C :c:expr: `double `.
155-
156- If *op * is not a Python complex number object but has a
157- :meth: `~object.__complex__ ` method, this method will first be called to
158- convert *op * to a Python complex number object. If :meth: `!__complex__ ` is
159- not defined then it falls back to call :c:func: `PyFloat_AsDouble ` and
160- returns its result.
161-
162- Upon failure, this method returns ``-1.0 `` with an exception set, so one
163- should call :c:func: `PyErr_Occurred ` to check for errors.
164-
165- .. versionchanged :: 3.13
166- Use :meth: `~object.__complex__ ` if available.
167-
168- .. c :function :: double PyComplex_ImagAsDouble (PyObject *op)
169-
170- Return the imaginary part of *op * as a C :c:expr: `double `.
171-
172- If *op * is not a Python complex number object but has a
173- :meth: `~object.__complex__ ` method, this method will first be called to
174- convert *op * to a Python complex number object. If :meth: `!__complex__ ` is
175- not defined then it falls back to call :c:func: `PyFloat_AsDouble ` and
176- returns ``0.0 `` on success.
177-
178- Upon failure, this method returns ``-1.0 `` with an exception set, so one
179- should call :c:func: `PyErr_Occurred ` to check for errors.
180-
181- .. versionchanged :: 3.13
182- Use :meth: `~object.__complex__ ` if available.
183-
184- .. c :function :: Py_complex PyComplex_AsCComplex (PyObject *op)
185-
186- Return the :c:type: `Py_complex ` value of the complex number *op *.
187-
188- If *op * is not a Python complex number object but has a :meth: `~object.__complex__ `
189- method, this method will first be called to convert *op * to a Python complex
190- number object. If :meth: `!__complex__ ` is not defined then it falls back to
191- :meth: `~object.__float__ `. If :meth: `!__float__ ` is not defined then it falls back
192- to :meth: `~object.__index__ `.
193-
194- Upon failure, this method returns :c:type: `Py_complex `
195- with :c:member: `~Py_complex.real ` set to ``-1.0 `` and with an exception set, so one
196- should call :c:func: `PyErr_Occurred ` to check for errors.
197-
198- .. versionchanged :: 3.8
199- Use :meth: `~object.__index__ ` if available.
0 commit comments