Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

gh-121834: Improve `complex` C-API docs (#121835) 

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:01:28 +03:00 committed by GitHub
parent f6c7d8d79c
commit 72dccd6073
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 22 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
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
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
defined as::
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;
double real;
double imag;
} Py_complex;
@ -106,11 +110,13 @@ Complex Numbers as Python Objects
.. 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*.
Return ``NULL`` with an exception set on error.
.. c:function:: double PyComplex_RealAsDouble(PyObject *op)
@ -121,7 +127,9 @@ Complex Numbers as Python Objects
:meth:`~object.__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 call :c:func:`PyFloat_AsDouble` and
returns its result. Upon failure, this method returns ``-1.0``, so one
returns its result.
Upon failure, this method returns ``-1.0`` with an exception set, so one
should call :c:func:`PyErr_Occurred` to check for errors.
.. versionchanged:: 3.13
@ -135,8 +143,10 @@ Complex Numbers as Python Objects
:meth:`~object.__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 call :c:func:`PyFloat_AsDouble` and
returns ``0.0`` on success. Upon failure, this method returns ``-1.0``, so
one should call :c:func:`PyErr_Occurred` to check for errors.
returns ``0.0`` on success.
Upon failure, this method returns ``-1.0`` with an exception set, so one
should call :c:func:`PyErr_Occurred` to check for errors.
.. versionchanged:: 3.13
Use :meth:`~object.__complex__` if available.
@ -149,8 +159,11 @@ Complex Numbers as Python Objects
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
: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
value.
to :meth:`~object.__index__`.
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
Use :meth:`~object.__index__` if available.