[capi-sig] Python 3.x PyObject_HEAD versus PyObject_VAR_HEAD

[Philip Semanchuk]

Hi all,
I'm trying to port my posix_ipc extension to Python 3, and I'm  
confused by the documentation for PyObject_HEAD and PyObject_VAR_HEAD.

My understanding is that a PyObject-derived type should begin its  
PyTypeObject struct with PyObject_HEAD and a PyVarObject-derived type  
with PyObject_VAR_HEAD. the documentation says of PyVarObject, "This  
type does not often appear in the Python/C API."
http://docs.python.org/3.1/c-api/structures.html#PyVarObject

The doc also says that PyObject_VAR_HEAD, "is used when declaring new  
types which represent objects with a length that varies from instance  
to instance."
http://docs.python.org/3.1/c-api/structures.html#PyObject_VAR_HEAD

I assumed, then, that PyObject_VAR_HEAD would also appear  
infrequently, but that's not the case at all. In fact, I can't find  
PyObject_HEAD used at all in the Python 3.1.1 source code, whereas  
PyObject_VAR_HEAD is used hundreds of times, including for objects  
that don't have a length (like the float type, for instance).

Is the documentation wrong, or am I misreading it? Suggestions  
appreciated.

THanks
Philip