Issue #12965: Clean up C-API docs for PyLong_AsLongLong(AndOverflow); clarify that __int__ will be called for non-PyLongs
diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index 526a87d..e428da1 100644
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -121,6 +121,7 @@
Raise :exc:`OverflowError` if the value of *obj* is out of range for a
:c:type:`long`.
+
.. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
Return a C :c:type:`long` representation of *obj*. If *obj* is not an
@@ -133,15 +134,29 @@
occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
-.. c:function:: PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *pylong, int *overflow)
+.. c:function:: PY_LONG_LONG PyLong_AsLongLong(PyObject *obj)
- Return a C :c:type:`long long` representation of the contents of
- *pylong*. If *pylong* is greater than :const:`PY_LLONG_MAX` or less
- than :const:`PY_LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``,
- respectively, and return ``-1``; otherwise, set *\*overflow* to
- ``0``. If any other exception occurs (for example a TypeError or
- MemoryError), then ``-1`` will be returned and *\*overflow* will
- be ``0``.
+ .. index::
+ single: OverflowError (built-in exception)
+
+ Return a C :c:type:`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`.
+
+ Raise :exc:`OverflowError` if the value of *obj* is out of range for a
+ :c:type:`long`.
+
+
+.. c:function:: PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
+
+ Return a C :c:type:`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 greater than :const:`PY_LLONG_MAX` or less than
+ :const:`PY_LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
+ and return ``-1``; otherwise, set *\*overflow* to ``0``. If any other
+ exception occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
.. versionadded:: 3.2
@@ -175,16 +190,6 @@
:exc:`OverflowError` is raised.
-.. c:function:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)
-
- .. index::
- single: OverflowError (built-in exception)
-
- Return a C :c:type:`long long` from a Python integer. If *pylong*
- cannot be represented as a :c:type:`long long`, an
- :exc:`OverflowError` is raised and ``-1`` is returned.
-
-
.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
.. index::