Document the error return of PyLong_As* APIs. (#5396)
Document the error return of PyLong_As* APIs.
A frequent Python C API usage error is neglecting to check the return
value and/or PyErr_Occurred().
diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index f50680b..4f16b57 100644
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -10,6 +10,9 @@
All integers are implemented as "long" integer objects of arbitrary size.
+On error, most ``PyLong_As*`` APIs return ``(return type)-1`` which cannot be
+distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
+
.. c:type:: PyLongObject
This subtype of :c:type:`PyObject` represents a Python integer object.
@@ -134,6 +137,8 @@
Raise :exc:`OverflowError` if the value of *obj* is out of range for a
:c:type:`long`.
+ Returns -1 on error. Use :c:func:`PyErr_Occurred` to disambiguate.
+
.. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
@@ -146,6 +151,8 @@
return ``-1``; otherwise, set *\*overflow* to ``0``. If any other exception
occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
+ Returns -1 on error. Use :c:func:`PyErr_Occurred` to disambiguate.
+
.. c:function:: long long PyLong_AsLongLong(PyObject *obj)
@@ -159,6 +166,8 @@
Raise :exc:`OverflowError` if the value of *obj* is out of range for a
:c:type:`long`.
+ Returns -1 on error. Use :c:func:`PyErr_Occurred` to disambiguate.
+
.. c:function:: long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
@@ -171,6 +180,8 @@
and return ``-1``; otherwise, set *\*overflow* to ``0``. If any other
exception occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
+ Returns -1 on error. Use :c:func:`PyErr_Occurred` to disambiguate.
+
.. versionadded:: 3.2
@@ -186,6 +197,8 @@
Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
:c:type:`Py_ssize_t`.
+ Returns -1 on error. Use :c:func:`PyErr_Occurred` to disambiguate.
+
.. c:function:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
@@ -199,15 +212,25 @@
Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
:c:type:`unsigned long`.
+ Returns ``(unsigned long)-1`` on error.
+ Use :c:func:`PyErr_Occurred` to disambiguate.
+
.. c:function:: size_t PyLong_AsSize_t(PyObject *pylong)
+ .. index::
+ single: SIZE_MAX
+ single: OverflowError (built-in exception)
+
Return a C :c:type:`size_t` representation of *pylong*. *pylong* must be
an instance of :c:type:`PyLongObject`.
Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
:c:type:`size_t`.
+ Returns ``(size_t)-1`` on error.
+ Use :c:func:`PyErr_Occurred` to disambiguate.
+
.. c:function:: unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)
@@ -220,6 +243,9 @@
Raise :exc:`OverflowError` if the value of *pylong* is out of range for an
:c:type:`unsigned long long`.
+ Returns ``(unsigned long long)-1`` on error.
+ Use :c:func:`PyErr_Occurred` to disambiguate.
+
.. versionchanged:: 3.1
A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`.
@@ -233,6 +259,8 @@
If the value of *obj* is out of range for an :c:type:`unsigned long`,
return the reduction of that value modulo ``ULONG_MAX + 1``.
+ Returns -1 on error. Use :c:func:`PyErr_Occurred` to disambiguate.
+
.. c:function:: unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)
@@ -243,6 +271,8 @@
If the value of *obj* is out of range for an :c:type:`unsigned long long`,
return the reduction of that value modulo ``PY_ULLONG_MAX + 1``.
+ Returns -1 on error. Use :c:func:`PyErr_Occurred` to disambiguate.
+
.. c:function:: double PyLong_AsDouble(PyObject *pylong)
@@ -252,6 +282,8 @@
Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
:c:type:`double`.
+ Returns -1.0 on error. Use :c:func:`PyErr_Occurred` to disambiguate.
+
.. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong)
@@ -259,3 +291,5 @@
If *pylong* cannot be converted, an :exc:`OverflowError` will be raised. This
is only assured to produce a usable :c:type:`void` pointer for values created
with :c:func:`PyLong_FromVoidPtr`.
+
+ Returns NULL on error. Use :c:func:`PyErr_Occurred` to disambiguate.