Skip to content

Commit 8eb8365

Browse files
skirpichevskirpichev
committed
gh-128813: cleanup C-API docs for PyComplexObject
* move non-deprecated API up * make a dedicated section for deprecated low-leved API
1 parent d7dbde8 commit 8eb8365

File tree

2 files changed

+104
-113
lines changed

2 files changed

+104
-113
lines changed

‎Doc/c-api/complex.rst

Lines changed: 103 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -3,116 +3,10 @@
33
.. _complexobjects:
44

55
Complex 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.
14-
15-
16-
Complex Numbers as C Structures
17-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
18-
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.
22-
23-
24-
.. c:type:: Py_complex
25-
26-
The C structure which corresponds to the value portion of a Python complex
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.
29-
30-
.. c:member:: double real
31-
double imag
32-
33-
The structure is defined as::
34-
35-
typedef struct {
36-
double real;
37-
double imag;
38-
} Py_complex;
39-
40-
41-
.. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
42-
43-
Return the sum of two complex numbers, using the C :c:type:`Py_complex`
44-
representation.
45-
46-
.. deprecated:: 3.15
47-
This function is :term:`soft deprecated`.
48-
49-
50-
.. c:function:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
51-
52-
Return the difference between two complex numbers, using the C
53-
:c:type:`Py_complex` representation.
54-
55-
.. deprecated:: 3.15
56-
This function is :term:`soft deprecated`.
57-
58-
59-
.. c:function:: Py_complex _Py_c_neg(Py_complex num)
60-
61-
Return the negation of the complex number *num*, using the C
62-
:c:type:`Py_complex` representation.
63-
64-
.. deprecated:: 3.15
65-
This function is :term:`soft deprecated`.
66-
67-
68-
.. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
69-
70-
Return the product of two complex numbers, using the C :c:type:`Py_complex`
71-
representation.
72-
73-
.. deprecated:: 3.15
74-
This function is :term:`soft deprecated`.
75-
76-
77-
.. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
78-
79-
Return the quotient of two complex numbers, using the C :c:type:`Py_complex`
80-
representation.
81-
82-
If *divisor* is null, this method returns zero and sets
83-
:c:data:`errno` to :c:macro:`!EDOM`.
84-
85-
.. deprecated:: 3.15
86-
This function is :term:`soft deprecated`.
87-
88-
89-
.. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
90-
91-
Return the exponentiation of *num* by *exp*, using the C :c:type:`Py_complex`
92-
representation.
93-
94-
If *num* is null and *exp* is not a positive real number,
95-
this method returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`.
96-
97-
Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
98-
99-
.. deprecated:: 3.15
100-
This function is :term:`soft deprecated`.
101-
102-
103-
.. c:function:: double _Py_c_abs(Py_complex num)
104-
105-
Return the absolute value of the complex number *num*.
106-
107-
Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
108-
109-
.. deprecated:: 3.15
110-
This function is :term:`soft deprecated`.
111-
112-
113-
Complex Numbers as Python Objects
114-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
115-
11610

11711
.. c:type:: PyComplexObject
11812
@@ -147,12 +41,6 @@ Complex Numbers as Python Objects
14741
:c:type:`PyComplexObject`. This function always succeeds.
14842
14943
150-
.. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)
151-
152-
Create a new Python complex number object from a C :c:type:`Py_complex` value.
153-
Return ``NULL`` with an exception set on error.
154-
155-
15644
.. c:function:: PyObject* PyComplex_FromDoubles(double real, double imag)
15745
15846
Return a new :c:type:`PyComplexObject` object from *real* and *imag*.
@@ -191,6 +79,29 @@ Complex Numbers as Python Objects
19179
.. versionchanged:: 3.13
19280
Use :meth:`~object.__complex__` if available.
19381
82+
83+
.. c:type:: Py_complex
84+
85+
This C structure defines export format for a Python complex
86+
number object.
87+
88+
.. c:member:: double real
89+
double imag
90+
91+
The structure is defined as::
92+
93+
typedef struct {
94+
double real;
95+
double imag;
96+
} Py_complex;
97+
98+
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+
194105
.. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)
195106
196107
Return the :c:type:`Py_complex` value of the complex number *op*.
@@ -207,3 +118,82 @@ Complex Numbers as Python Objects
207118
208119
.. versionchanged:: 3.8
209120
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:type:`double complex`.
135+
136+
137+
.. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
138+
139+
Return the sum of two complex numbers, using the C :c:type:`Py_complex`
140+
representation.
141+
142+
.. deprecated:: 3.15
143+
144+
145+
.. c:function:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
146+
147+
Return the difference between two complex numbers, using the C
148+
:c:type:`Py_complex` representation.
149+
150+
.. deprecated:: 3.15
151+
152+
153+
.. c:function:: Py_complex _Py_c_neg(Py_complex num)
154+
155+
Return the negation of the complex number *num*, using the C
156+
:c:type:`Py_complex` representation.
157+
158+
.. deprecated:: 3.15
159+
160+
161+
.. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
162+
163+
Return the product of two complex numbers, using the C :c:type:`Py_complex`
164+
representation.
165+
166+
.. deprecated:: 3.15
167+
168+
169+
.. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
170+
171+
Return the quotient of two complex numbers, using the C :c:type:`Py_complex`
172+
representation.
173+
174+
If *divisor* is null, this method returns zero and sets
175+
:c:data:`errno` to :c:macro:`!EDOM`.
176+
177+
.. deprecated:: 3.15
178+
179+
180+
.. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
181+
182+
Return the exponentiation of *num* by *exp*, using the C :c:type:`Py_complex`
183+
representation.
184+
185+
If *num* is null and *exp* is not a positive real number,
186+
this method returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`.
187+
188+
Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
189+
190+
.. deprecated:: 3.15
191+
192+
193+
.. c:function:: double _Py_c_abs(Py_complex num)
194+
195+
Return the absolute value of the complex number *num*.
196+
197+
Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
198+
199+
.. deprecated:: 3.15

‎Doc/conf.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,7 @@
174174
('c:type', '__int64'),
175175
('c:type', 'unsigned __int64'),
176176
('c:type', 'double'),
177+
('c:type', 'double complex'),
177178
# Standard C structures
178179
('c:struct', 'in6_addr'),
179180
('c:struct', 'in_addr'),

0 commit comments

Comments
 (0)