Documentation bugs in 3.1 - C-API - TypeObjects

[DreiJane]

Hello,

this page http://docs.python.org/3.1/c-api/typeobj.html has a bad
error:

"
PyTypeObject* PyObject.ob_type

This is the type’s type, in other words its metatype. It is
initialized by the argument to the PyObject_HEAD_INIT macro, and its
value should normally be &PyType_Type. However, for dynamically
loadable extension modules that must be usable on Windows (at least),
the compiler complains that this is not a valid initializer.
Therefore, the convention is to pass NULL to the PyObject_HEAD_INIT
macro and to initialize this field explicitly at the start of the
module’s initialization function, before doing anything else. This is
typically done like this:

Foo_Type.ob_type = &PyType_Type;
"

This cannot work, because Foo_Type is no PyObject but a PyVarObject
(independent
of the use of PyVarObject_HEAD_INIT or PyObject_HEAD_INIT). The code
line would
work so:

((PyObject *)&Foo_Type)->ob_type = &PyType_Type

But in the Tutorial for Extensions and Embedding we are advised as
follows:
"
This is so important that we’re going to pick the top of it apart
still further:
          PyVarObject_HEAD_INIT(NULL, 0)
This line is a bit of a wart; what we’d like to write is:
          PyVarObject_HEAD_INIT(&PyType_Type, 0)
as the type of a type object is “type”, but this isn’t strictly
conforming C and some compilers complain. Fortunately, this member
will be filled in for us by PyType_Ready().
"

What now ?

Another problem, which might be a documentation bug, is the last
sentence here:
"
destructor PyTypeObject.tp_dealloc

A pointer to the instance destructor function. This function must be
defined unless the type guarantees that its instances will never be
deallocated (as is the case for the singletons None and Ellipsis).

The destructor function is called by the Py_DECREF() and Py_XDECREF()
macros when the new reference count is zero. At this point, the
instance is still in existence, but there are no references to it. The
destructor function should free all references which the instance
owns, free all memory buffers owned by the instance (using the freeing
function corresponding to the allocation function used to allocate the
buffer), and finally (as its last action) call the type’s tp_free
function. If the type is not subtypable (doesn’t have the
Py_TPFLAGS_BASETYPE flag bit set), it is permissible to call the
object deallocator directly instead of via tp_free.
"

What ? Where do we "call" these methods ? Primarily we write them down
to get members
of the Foo_Type struct and our question is where. Shall this sentence
mean, that we
write the function, we'd normally use for tp_dealloc und which behaves
like it, to the place of tp_free ?

I've run into terrible trouble with extension classes, which have
neither members nor init.
They work (and i am quite happy about that) but finding out, that
tp_dictoffset had to be
set (for what i wanted) took more than a day of searching - including
öecture of typeobject.c and object.c - and i cannot derive from them.

class(my_extension_class): ... doesn't crash, but results in objects,
which have the type
my_extension_class, what means, that they do not call their __init__.
In certain
circumstances a correct tp_free seems to be a premise for inheritance,
thus i'd very like
to understand the quoted passage.

Joost