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