From 03f6803e8bd1493e3548c2f65e8ab6dbefe73ab1 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Tue, 16 Jul 2024 10:04:57 +0300 Subject: [PATCH 1/6] gh-121834: Improve `complex` C-API docs --- Doc/c-api/complex.rst | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst index 5a0474869071d9..5580d6c68dfdce 100644 --- a/Doc/c-api/complex.rst +++ b/Doc/c-api/complex.rst @@ -106,11 +106,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 +123,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 +139,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 +155,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 ``.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 5ead0037518064f4f3dee3adf69b6cea05ff93a6 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Tue, 16 Jul 2024 10:26:33 +0300 Subject: [PATCH 2/6] Update Doc/c-api/complex.rst Co-authored-by: Sergey B Kirpichev --- Doc/c-api/complex.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst index 5580d6c68dfdce..0fd7519d079d27 100644 --- a/Doc/c-api/complex.rst +++ b/Doc/c-api/complex.rst @@ -158,7 +158,7 @@ Complex Numbers as Python Objects to :meth:`~object.__index__`. Upon failure, this method returns :c:type:`Py_complex` - with ``.real`` set to ``-1.0`` and with an exception set, so one + 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 From 62c402c3df8eeb9c21baa948344742c2347cd8dc Mon Sep 17 00:00:00 2001 From: sobolevn Date: Tue, 16 Jul 2024 10:32:52 +0300 Subject: [PATCH 3/6] Add Py_complex members --- Doc/c-api/complex.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst index 0fd7519d079d27..be39847e8a2b67 100644 --- a/Doc/c-api/complex.rst +++ b/Doc/c-api/complex.rst @@ -25,8 +25,12 @@ 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:`Py_complex.real` + * :c:member:`Py_complex.imag` + + It is defined as:: typedef struct { double real; From 1bf9ae06f0571d3717eb86147bf6c501002830eb Mon Sep 17 00:00:00 2001 From: sobolevn Date: Tue, 16 Jul 2024 10:38:11 +0300 Subject: [PATCH 4/6] Add Py_complex members --- Doc/c-api/complex.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst index be39847e8a2b67..5a589315630a93 100644 --- a/Doc/c-api/complex.rst +++ b/Doc/c-api/complex.rst @@ -27,15 +27,17 @@ pointers. This is consistent throughout the API. number object. Most of the functions for dealing with complex number objects use structures of this type as input or output values, as appropriate. - * :c:member:`Py_complex.real` - * :c:member:`Py_complex.imag` + .. c:namespace:: Py_complex - It is defined as:: + .. c:member:: double real + .. c:member:: double imag - typedef struct { - double real; - double imag; - } Py_complex; + It is defined as:: + + typedef struct { + double real; + double imag; + } Py_complex; .. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right) From 1afad21815c8a1a6ecf1683ff6517c5385f660d1 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Tue, 16 Jul 2024 10:45:35 +0300 Subject: [PATCH 5/6] Add Py_complex members --- 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 5a589315630a93..f1c609d4a64eea 100644 --- a/Doc/c-api/complex.rst +++ b/Doc/c-api/complex.rst @@ -27,8 +27,6 @@ pointers. This is consistent throughout the API. number object. Most of the functions for dealing with complex number objects use structures of this type as input or output values, as appropriate. - .. c:namespace:: Py_complex - .. c:member:: double real .. c:member:: double imag From fbd0858b7149ba4e2612a820fcc7a42596694331 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Tue, 16 Jul 2024 19:30:07 +0300 Subject: [PATCH 6/6] Update Doc/c-api/complex.rst Co-authored-by: Petr Viktorin --- Doc/c-api/complex.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst index f1c609d4a64eea..67d0c5f144e075 100644 --- a/Doc/c-api/complex.rst +++ b/Doc/c-api/complex.rst @@ -28,14 +28,14 @@ pointers. This is consistent throughout the API. use structures of this type as input or output values, as appropriate. .. c:member:: double real - .. c:member:: double imag + double imag - It is defined as:: + The structure is defined as:: - typedef struct { - double real; - double imag; - } Py_complex; + typedef struct { + double real; + double imag; + } Py_complex; .. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)