[Python-checkins] cpython (2.7): Issue #13522: document error return values of some float and complex C API

[antoine.pitrou]

http://hg.python.org/cpython/rev/059e4d752fbe
changeset:   74025:059e4d752fbe
branch:      2.7
parent:      74003:766a21ebf82e
user:        Antoine Pitrou <solipsis at pitrou.net>
date:        Sun Dec 18 01:25:27 2011 +0100
summary:
  Issue #13522: document error return values of some float and complex C API functions.

files:
  Doc/c-api/complex.rst |  7 +++++++
  Doc/c-api/float.rst   |  2 ++
  Misc/ACKS             |  1 +
  3 files changed, 10 insertions(+), 0 deletions(-)


diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst
--- a/Doc/c-api/complex.rst
+++ b/Doc/c-api/complex.rst
@@ -63,12 +63,18 @@
    Return the quotient of two complex numbers, using the C :ctype:`Py_complex`
    representation.
 
+   If *divisor* is null, this method returns zero and sets
+   :cdata:`errno` to :cdata:`EDOM`.
+
 
 .. cfunction:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
 
    Return the exponentiation of *num* by *exp*, using the C :ctype:`Py_complex`
    representation.
 
+   If :attr:`exp.imag` is not null, or :attr:`exp.real` is negative,
+   this method returns zero and sets :cdata:`errno` to :cdata:`EDOM`.
+
 
 Complex Numbers as Python Objects
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -125,6 +131,7 @@
 .. cfunction:: Py_complex PyComplex_AsCComplex(PyObject *op)
 
    Return the :ctype:`Py_complex` value of the complex number *op*.
+   Upon failure, this method returns ``-1.0`` as a real value.
 
    .. versionchanged:: 2.6
       If *op* is not a Python complex number object but has a :meth:`__complex__`
diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst
--- a/Doc/c-api/float.rst
+++ b/Doc/c-api/float.rst
@@ -55,6 +55,8 @@
    Return a C :ctype:`double` representation of the contents of *pyfloat*.  If
    *pyfloat* is not a Python floating point object but has a :meth:`__float__`
    method, this method will first be called to convert *pyfloat* into a float.
+   This method returns ``-1.0`` upon failure, so one should call
+   :cfunc:`PyErr_Occurred` to check for errors.
 
 
 .. cfunction:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
diff --git a/Misc/ACKS b/Misc/ACKS
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -120,6 +120,7 @@
 Lee Busby
 Ralph Butler
 Jp Calderone
+Arnaud Calmettes
 Daniel Calvelo
 Tony Campbell
 Brett Cannon

-- 
Repository URL: http://hg.python.org/cpython