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_Type, 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_weaklistoffset, 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_FromXXX" 
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?