Newstyle Types Confounding!

[Pete Shinners]

I've been spending the last few night upgrading some 'classic' type
objects to the more modern 'newstyle' types. Unless I am not finding
some important page, this entire process is almost entirely
undocumented. I've found the "Noddy" example, which was a helping start.
But Noddy only gets you halfway there, and where it leaves off there is
no further assistance.

I've been using the builtin Python types source as example, but this
isn't answering most of my larger problems. Especially as the builtin
types seem inconsistent in how they do thing. I have a few questions and
am hoping to get a little guidance from those who understand this
process better.
First, I have found no comfortable way to create new type instances from
the C api. My types are wrappers for existing C structures. Originally
my code called PyObject_New and filled out the structure data. This
appears to be invalid with newstyle types, but I cannot discover the new
method. It appears there is no standard since all the builtin types do
this differently. I've ended up with something like this..

self = (PyMineObject*) PyMine_Type.tp_ new(&PyMine_Typ e, NULL, NULL);

Can this be serious? This is the first time I've ever had to dig into
the big Type structure to access function pointers. I find this to be
disturbing, but I can learn to accept it if someone confirms this is the
way to allocate newstyle type instances.
My second problem has to do with weakrefs. Again I cannot locate actual
documentation on this, and the Noddy example ends before discussing
weakrefs. I've created the PyObject* weakreflist in my structure, set
the offset in tp_weaklistoffs et, and initialized it to NULL. It took
many hours to figure out how this all works, mainly referring to
funcobject.c for examples. I believe I have this correct now, but I have
a lot of unexplained crashes that i suspect have to do with the weakref
list handling.
My third question comes to creating types that are inherited from other
types. I need the new subtype to add several of its own data fields to
its own structure. There are no examples of this in the Python source,
and there is no documentation referring to this. How can my new type
instances access structure data from its base. My only solution so far
is to duplicate all the structure members from the parent into the
child? Then duplicate all the code from the parent into the child. At
this point my child is actually a standalone type, except it refers to
the parent in tp_base.
Creating custom types in Python has become very difficult, if you intend
to support all the recent features of Python. Adding some documentation
and/or simple examples would go a long way towards a solution. I'm
wondering if some thought should be put into simplifying the interface.
Perhaps more macros and generic functions to help manage the new
features. It shocks me to find nearly every single "PyXXX_From XXX"
implements object allocation in entirely independent ways, and none of
the methods seem very clean to me.

At this point I'm really shooting into the dark. I assume I'll have it
right when things stop crashing.

If I were to collect a narrowed, specific list of problem topics, would
the documentation team be interested in looking?