mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-12 12:58:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

[3.12] gh-121834: Improve complex C-API docs (GH-121835) (#121897)

Browse source 
* [3.12] gh-121834: Improve `complex` C-API docs (GH-121835)
(cherry picked from commit 72dccd6073)

Co-authored-by: sobolevn <mail@sobolevn.me>
Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
This commit is contained in:
sobolevn 2024-07-17 10:30:18 +03:00 • committed by GitHub
parent 6e0ba93dfa
commit 6a19d22a19
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 18 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

24
Doc/c-api/complex.rst
View file

@ -25,12 +25,16 @@ pointers. This is consistent throughout the API.
The C structure which corresponds to the value portion of a Python 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 number object. Most of the functions for dealing with complex number objects
use structures of this type as input or output values, as appropriate. It is use structures of this type as input or output values, as appropriate.
defined as::
.. c:member:: double real
double imag
The structure is defined as::
typedef struct { typedef struct {
double real; double real;
double imag; double imag;
} Py_complex; } Py_complex;
@ -106,17 +110,22 @@ Complex Numbers as Python Objects
.. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v) .. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)
Create a new Python complex number object from a C :c:type:`Py_complex` value. 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) .. c:function:: PyObject* PyComplex_FromDoubles(double real, double imag)
Return a new :c:type:`PyComplexObject` object from *real* and *imag*. Return a new :c:type:`PyComplexObject` object from *real* and *imag*.
Return ``NULL`` with an exception set on error.
.. c:function:: double PyComplex_RealAsDouble(PyObject *op) .. c:function:: double PyComplex_RealAsDouble(PyObject *op)
Return the real part of *op* as a C :c:expr:`double`. Return the real part of *op* as a C :c:expr:`double`.
Upon failure, this method returns ``-1.0`` with an exception set, so one
should call :c:func:`PyErr_Occurred` to check for errors.
.. c:function:: double PyComplex_ImagAsDouble(PyObject *op) .. c:function:: double PyComplex_ImagAsDouble(PyObject *op)
@ -131,8 +140,11 @@ Complex Numbers as Python Objects
method, this method will first be called to convert *op* to a Python complex method, this method will first be called to convert *op* to a Python complex
number object. If :meth:`!__complex__` is not defined then it falls back to number object. If :meth:`!__complex__` is not defined then it falls back to
:meth:`~object.__float__`. If :meth:`!__float__` is not defined then it falls back :meth:`~object.__float__`. If :meth:`!__float__` is not defined then it falls back
to :meth:`~object.__index__`. Upon failure, this method returns ``-1.0`` as a real to :meth:`~object.__index__`.
value.
Upon failure, this method returns :c:type:`Py_complex`
with :c:member:`~Py_complex.real` set to ``-1.0`` and with an exception set, so one
should call :c:func:`PyErr_Occurred` to check for errors.
.. versionchanged:: 3.8 .. versionchanged:: 3.8
Use :meth:`~object.__index__` if available. Use :meth:`~object.__index__` if available.