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