From my experiences, there is nothing more anoying than a bug report that says something is broken (when it's obvious, esspecially documentation) w/o any help. When the documentation is in as much disarray as Defining New Object Types there really isn't that much I can do about it. Either a bug report should already be there, or the group that is working on the documentation should already know about it. It has improved, but still, isn't usable unless you already know what's going on. As for reading the source code, that's what I do. But there always a point when the need/want to do a project isn't great enough to go through reading all the source code looking for good examples of what you want to do.
Also, if PyClass_* is internal, why is it publicly defined? And if it's private, then how are you suppose to create an object to pass back for maintaining a connection such as the state for a Z39.50 connection w/o using a class? Defining a new type seems a bit extreme, and defining a whole module wouldn't work as you don't instanciate that for each connection. So how else am I suppose to do that w/o using PyClass_*? Again, it really sounds like I should just do a blind wrapper around the functions and do all the glue code in Python. It'll be easier, and don't have to worry about as many coding bugs.
As for bitching to Advogato, don't forget that this is a diary entry. It's what happens to be on my mind when I'm writing the diary, and be frustrating for me.