Issue #12965: More PyLong_As* clarifications. Thanks Stefan Krah.

1 files changed, 39 insertions, 22 deletions

diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index e428da1..e2f58ad 100644
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -167,9 +167,11 @@ All integers are implemented as "long" integer objects of arbitrary size.
       single: PY_SSIZE_T_MAX
       single: OverflowError (built-in exception)
 
-   Return a C :c:type:`Py_ssize_t` representation of the contents of *pylong*.
-   If *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError`
-   is raised and ``-1`` will be returned.
+   Return a C :c:type:`Py_ssize_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:`Py_ssize_t`.
 
 
 .. c:function:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
@@ -178,16 +180,20 @@ All integers are implemented as "long" integer objects of arbitrary size.
       single: ULONG_MAX
       single: OverflowError (built-in exception)
 
-   Return a C :c:type:`unsigned long` representation of the contents of *pylong*.
-   If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is
-   raised.
+   Return a C :c:type:`unsigned long` 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:`unsigned long`.
 
 
 .. c:function:: size_t PyLong_AsSize_t(PyObject *pylong)
 
-   Return a :c:type:`size_t` representation of the contents of *pylong*.  If
-   *pylong* is greater than the maximum value for a :c:type:`size_t`, an
-   :exc:`OverflowError` is raised.
+   Return a C :c:type:`size_t` representation of 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`.
 
 
 .. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
@@ -195,32 +201,43 @@ All integers are implemented as "long" integer objects of arbitrary size.
    .. index::
       single: OverflowError (built-in exception)
 
-   Return a C :c:type:`unsigned long long` from a Python integer. If
-   *pylong* cannot be represented as an :c:type:`unsigned long long`,
-   an :exc:`OverflowError` is raised and ``(unsigned long long)-1`` is
-   returned.
+   Return a C :c:type:`unsigned PY_LONG_LONG` representation of of *pylong*.
+   *pylong* must be an instance of :c:type:`PyLongObject`.
+
+   Raise :exc:`OverflowError` if the value of *pylong* is out of range for an
+   :c:type:`unsigned PY_LONG_LONG`.
 
    .. versionchanged:: 3.1
       A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`.
 
 
-.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
+.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
 
-   Return a C :c:type:`unsigned long` from a Python integer, without checking for
-   overflow.
+   Return a C :c:type:`unsigned long` representation of *obj*.  If *obj*
+   is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__`
+   method (if present) to convert it to a :c:type:`PyLongObject`.
 
+   If the value of *obj* is out of range for an :c:type:`unsigned long`,
+   return the reduction of that value modulo :const:`ULONG_MAX + 1`.
 
-.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)
 
-   Return a C :c:type:`unsigned long long` from a Python integer, without
-   checking for overflow.
+.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *obj)
+
+   Return a C :c:type:`unsigned long long` representation of *obj*.  If *obj*
+   is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__`
+   method (if present) to convert it to a :c:type:`PyLongObject`.
+
+   If the value of *obj* is out of range for an :c:type:`unsigned long long`,
+   return the reduction of that value modulo :const:`PY_ULLONG_MAX + 1`.
 
 
 .. c:function:: double PyLong_AsDouble(PyObject *pylong)
 
-   Return a C :c:type:`double` representation of the contents of *pylong*.  If
-   *pylong* cannot be approximately represented as a :c:type:`double`, an
-   :exc:`OverflowError` exception is raised and ``-1.0`` will be returned.
+   Return a C :c:type:`double` 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:`double`.
 
 
 .. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong)