homepage

I think the integer objects documentation could be clearer on a
couple of points:
 - Despite being listed under "Concrete Objects Layer", some
 functions implicitly accept anything with an __int__()
 method. Currently only the PyLong_AsLong() documentation
 states this explicitly.
 The patch clearly distinguishes between functions that
 duck type and functions that don't. 
 - The patch replaces "is greater than *_MAX" instances with
 "out of bounds" to include the other error condition
 "is less than *_MIN".
Additionally, the patch fixes comments in longobject.c that
don't state the duck typing behavior.

New changeset d4839fea4a5a by Mark Dickinson in branch 'default':
Issue #12965: Fix some inaccurate comments in Objects/longobject.c. Thanks Stefan Krah.
http://hg.python.org/cpython/rev/d4839fea4a5a 

I've fixed some of the inaccurate comments in Objects/longobject.c, for the default branch; I'm still looking at the Doc update.
This really is a bit of a mess, especially for cases like PyLong_AsVoidPtr, which can either end up calling PyLong_As(Long)Long (which allows conversion via __int__), or PyLong_AsUnsigned(Long)Long (which doesn't).
Ultimately, I think it would make sense to remove all __int__ conversions from Objects/longobject.c; this would affect:
 - PyLong_AsLongAndOverflow
 - PyLong_AsLong
 - PyLong_AsUnsignedLongMask
and the 'LongLong' variants of these. The ramifications of such a change might be quite long-reaching; in particular, I seem to recall that this would affect the 'getargs' machinery.
It could be fun to remove these conversions and see how much of the test-suite fails. :-)

> It could be fun to remove these conversions and see how much of the
> test-suite fails. :-)
... On my machine, just test_ctypes and test_getargs2, as it turns out.

> Ultimately, I think it would make sense to remove all __int__
> conversions from Objects/longobject.c;
+1
I think this API cleanup is worth some (probably very limited)
breakage in third party modules.

New changeset 5ca9a51f3d85 by Mark Dickinson in branch '3.2':
Issue #12965: Clean up C-API docs for PyLong_AsLong(AndOverflow); clarify that __int__ will be called for non-PyLongs
http://hg.python.org/cpython/rev/5ca9a51f3d85
New changeset 63fc1552cd36 by Mark Dickinson in branch 'default':
Issue #12965: Merge from 3.2
http://hg.python.org/cpython/rev/63fc1552cd36 

New changeset 3ace8e17074a by Mark Dickinson in branch '3.2':
Issue #12965: Clean up C-API docs for PyLong_AsLongLong(AndOverflow); clarify that __int__ will be called for non-PyLongs
http://hg.python.org/cpython/rev/3ace8e17074a
New changeset 85683f005fc8 by Mark Dickinson in branch 'default':
Issue #12965: Merge from 3.2.
http://hg.python.org/cpython/rev/85683f005fc8 

New changeset e1416a4d728a by Mark Dickinson in branch '3.2':
Issue #12965: More PyLong_As* clarifications. Thanks Stefan Krah.
http://hg.python.org/cpython/rev/e1416a4d728a
New changeset 349bc58e8c66 by Mark Dickinson in branch 'default':
Issue #12965: Merge from 3.2.
http://hg.python.org/cpython/rev/349bc58e8c66 

Docs mostly fixed now for Python 3.2 and Python 3.3. That leaves 2.7, where there are some additional complications (e.g., __long__ in addition to __int__, when / whether short ints are accepted, etc.).
While it would be good to fix the 2.7 docs as well, I don't see myself having time for this in the near future, so I'm unassigning for now; Stefan, I think should feel free to take this issue and check in clarifications for 2.7, if you want to.

OK, I'll see if I find some time for the 2.7 docs.

This seems like too much trouble for 2.7. Closing, since I was the
one who opened the issue (just reopen if you think it is still worth
it).