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().

1 files changed, 34 insertions, 0 deletions

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 @@ Integer Objects
 
 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 @@ All integers are implemented as "long" integer objects of arbitrary size.
    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 @@ All integers are implemented as "long" integer objects of arbitrary size.
    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 @@ All integers are implemented as "long" integer objects of arbitrary size.
    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 @@ All integers are implemented as "long" integer objects of arbitrary size.
    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 @@ All integers are implemented as "long" integer objects of arbitrary size.
    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 @@ All integers are implemented as "long" integer objects of arbitrary size.
    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 @@ All integers are implemented as "long" integer objects of arbitrary size.
    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 @@ All integers are implemented as "long" integer objects of arbitrary size.
    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 @@ All integers are implemented as "long" integer objects of arbitrary size.
    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 @@ All integers are implemented as "long" integer objects of arbitrary size.
    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 @@ All integers are implemented as "long" integer objects of arbitrary size.
    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.