From e11ca8e6297e44fe3efdbbac7aca949008361ac3 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Wed, 17 Jul 2024 10:01:28 +0300 Subject: [PATCH 1/3] [3.12] gh-121834: Improve `complex` C-API docs (GH-121835) (cherry picked from commit 72dccd60735b597e99c007a7b69210763a746877) Co-authored-by: sobolevn Co-authored-by: Sergey B Kirpichev Co-authored-by: Petr Viktorin --- Doc/c-api/complex.rst | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst index e3fd001c599c80..1ed51b82b2e4f1 100644 --- a/Doc/c-api/complex.rst +++ b/Doc/c-api/complex.rst @@ -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,22 +110,30 @@ 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) 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) Return the imaginary 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:: Py_complex PyComplex_AsCComplex(PyObject *op) @@ -131,8 +143,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. From d2de7882e055241aec986afa16820d3f3d874dca Mon Sep 17 00:00:00 2001 From: sobolevn Date: Wed, 17 Jul 2024 10:13:00 +0300 Subject: [PATCH 2/3] Update complex.rst --- Doc/c-api/complex.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst index 1ed51b82b2e4f1..1b9ae917fdc943 100644 --- a/Doc/c-api/complex.rst +++ b/Doc/c-api/complex.rst @@ -131,8 +131,7 @@ Complex Numbers as Python Objects Return the imaginary 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. + This function always succeeds. .. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op) From f064027ca3db47d2ebecb9a15d531a6b5e5e3ab5 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Wed, 17 Jul 2024 10:23:07 +0300 Subject: [PATCH 3/3] Update Doc/c-api/complex.rst Co-authored-by: Sergey B Kirpichev --- Doc/c-api/complex.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst index 1b9ae917fdc943..77cb67d8de2b4c 100644 --- a/Doc/c-api/complex.rst +++ b/Doc/c-api/complex.rst @@ -131,8 +131,6 @@ Complex Numbers as Python Objects Return the imaginary part of *op* as a C :c:expr:`double`. - This function always succeeds. - .. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)