[Python-3000] PyObject_HEAD_INIT

[Terry Reedy]

Roger Binns wrote:

> The problem is that unless you are clairvoyant you have no way of
> knowing about this change.  Even in rc3 the documentation shows the old
> (wrong) way:
> 
>   http://docs.python.org/dev/3.0/extending/newtypes.html
> 
> PyObject_HEAD_INIT is documented:
> 
>   http://docs.python.org/dev/3.0/search.html?q=PyObject_HEAD_INIT
> 
> PyVarObject_HEAD_INIT is not:
> 
>   http://docs.python.org/dev/3.0/search.html?q=PyVarObject_HEAD_INIT

Whatever happens to PyObject..., that should be fixed.  Is there are 
tracker item yet?  A doc person will copy, paste, and format if given 
raw text.

> So anyone porting from Python 2 to Python 3 is just going to compile
> their code.

A What's New in Py 3 API is needed that people could read first instead 
of digging through the source after.

 > There will be some warnings but if they consult the docs
> the code will still look correct.  They will just assume it is a Python
> quirk.  Then the code will run and crash and they will have to examine
> the Python 3 source to work out what the underlying issue is and how to
> fix it.
> 
> If PyObject_HEAD_INIT were removed/renamed then the code wouldn't even
> compile and so they would realize they have to fix it.
> 
>>  * PyNumberMethods have changed due to removal of the division,
> ...
>>  * PySequenceMethods have changed, but maintained binary compatibility
>>    (why ?) by replacing the removed slice functions with dummy pointers
> ...
>>  * PyBufferProcs is a completely new design
> 
> PyTypeObjects are used in every extension.  The above changes affect
> fewer extensions and the compiler error/warnings will be more
> meaningful.  I would have expected minor changes like these.
> 
>>  * A lot type flags were removed.

This seems like a start.