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

Philip Semanchuk philip at semanchuk.com
Mon Feb 1 23:56:57 CET 2010

On Feb 1, 2010, at 5:27 AM, M.-A. Lemburg wrote:

> Philip Semanchuk wrote:
>> 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).
> I'm not sure how you searched for these, but I get somewhat
> different counts:
> 33 PyObject_HEAD
> 10 PyObject_VAR_HEAD
> in the Include/ dir of Python 3 (SVN)
>> Is the documentation wrong, or am I misreading it? Suggestions  
>> appreciated.
> The docs are correct.
> PyObject_HEAD does not include the field ob_size, PyObject_VAR_HEAD
> does.
> Perhaps you are confusing this with PyVarObject_HEAD_INIT() ?!

THanks for your reply. You're right, I should have said that it is  
PyVarObject_HEAD_INIT that's used hundreds of times while  
PyObject_HEAD_INIT is hardly used at all (according to `grep -r`).  
Actually, I can state that even more strongly: PyObject_HEAD_INIT is  
only used once -- in the #define for PyVarObject_HEAD_INIT.

After spending another hour reading the Python source, I think I get  
it now. As is often the case, the problem came from not reading  
carefully. When I saw this:

    PyTypeObject PyFloat_Type = {
	   PyVarObject_HEAD_INIT(&PyType_Type, 0)

I saw PyVarObject_HEAD_INIT being used to initialize a PyFloatObject,  
which is not the case -- it's initializing a PyTypeObject. Since the  
PyTypeObject struct definition uses PyObject_VAR_HEAD, it makes sense  
that PyVarObject_HEAD_INIT is used to initialize it.

That also explains why PyVarObject_HEAD_INIT shows up so much in the  
Python source -- it's all those PyTypeObjects getting initialized.

This brings up two more questions that I could probably answer with  
more reading, but if you have time for some further explanation I'd  
appreciate it. First, in what context would one use  
PyObject_HEAD_INIT? Second, why does the PyTypeObject struct  
definition use PyObject_VAR_HEAD when a type object has no concept of  


More information about the capi-sig mailing list