Eric pointed me to this ticket after having raised the question on
python-dev: http://www.mail-archive.com/python-dev@python.org/msg43841.html

I think the discussion should be continued there instead of on this ticket.

Just for completeness, I'm copying my reply to Martin's reply here
(http://www.mail-archive.com/python-dev@python.org/msg43849.html):

"""
> For example, consider
> 
> if (PyInt_Check(o)){
>   long val = PyInt_AsLong(o);
>   // process
> } else if (PyLong_Check(o)) {
>   long long val = PyLong_AsLongLong(o);
>   // check for overflow
>   // process
> }
> 
> With intobject.h, this code would continue to compile, but work
> incorrectly, as the second case will never be executed. It would
> be better to port this as
> 
> #if Py2.x
> if (PyInt_Check(o)){
>   long val = PyInt_AsLong(o);
>   // process
> } else
> #endif
> if (PyLong_Check(o)) {
> 
> i.e. eliminating the int case altogether.

Sure, but that assumes that the original code already had support
for Python longs, which a lot of code doesn't.

In an ideal world, developers would add that code to their
extensions right away. In the real world, where developers only
have limited resources available, you'll get more 3.x ports
by making such ports as painless as possible while at the
same time not forcing them to alienate their 2.x user base.

The long support could then be added in later releases
of the extensions, giving the developers more time adapt.

> For another example,
> 
> long foo = PyInt_AsLong(Foo);
> 
> has a hidden error in 3.x, with intobject: PyLong_AsLong might
> overflow, which the 2.x case doesn't.

That's not quite true: PyInt_AsLong(obj) will try the
nb_int slot on non-integer objects which can return errors
(it returns -1 and sets the error message).

> So eliminating intobject.h likely helps avoiding subtle errors.

In the long run, yes. In the short run, other criteria are
more important, IMHO.
"""

IMO, it would be worthwhile collecting all Python 2.x compatibility C
APIs in two new files:

 * py2compat.h
 * py2compat.c

These could then be used in extensions and make the use of such
compatibility APIs explicit in the extension.