[Python-checkins] cpython (3.2): Issue #12965: Clean up C-API docs for PyLong_AsLong(AndOverflow); clarify that

[mark.dickinson]

http://hg.python.org/cpython/rev/5ca9a51f3d85
changeset:   77617:5ca9a51f3d85
branch:      3.2
parent:      77612:55849442d7a9
user:        Mark Dickinson <mdickinson at enthought.com>
date:        Sat Jun 23 10:49:12 2012 +0100
summary:
  Issue #12965: Clean up C-API docs for PyLong_AsLong(AndOverflow); clarify that __int__ will be called for non-PyLongs

files:
  Doc/c-api/long.rst |  29 ++++++++++++++++-------------
  1 files changed, 16 insertions(+), 13 deletions(-)


diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -108,26 +108,29 @@
 
 
 .. XXX alias PyLong_AS_LONG (for now)
-.. c:function:: long PyLong_AsLong(PyObject *pylong)
+.. c:function:: long PyLong_AsLong(PyObject *obj)
 
    .. index::
       single: LONG_MAX
       single: OverflowError (built-in exception)
 
-   Return a C :c:type:`long` representation of the contents of *pylong*.  If
-   *pylong* is greater than :const:`LONG_MAX`, raise an :exc:`OverflowError`,
-   and return -1. Convert non-long objects automatically to long first,
-   and return -1 if that raises exceptions.
+   Return a C :c:type:`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`.
 
-.. c:function:: long PyLong_AsLongAndOverflow(PyObject *pylong, int *overflow)
+   Raise :exc:`OverflowError` if the value of *obj* is out of range for a
+   :c:type:`long`.
 
-   Return a C :c:type:`long` representation of the contents of
-   *pylong*.  If *pylong* is greater than :const:`LONG_MAX` or less
-   than :const:`LONG_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``.
+.. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
+
+   Return a C :c:type:`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:`LONG_MAX` or less than
+   :const:`LONG_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.
 
 
 .. c:function:: PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *pylong, int *overflow)

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