[Jeremy Hylton]
I've been struggling with the meaning of the various TPFLAGS myself. I don't think it's documented anywhere, and I don't think anyone except Guido really understands what all the flags mean.
I agree that at this point Guido is the only one who fully understands what they were all *intended* to mean, but I don't believe even Guido can tell you (without the same kinds of study and experimentation and hair-pulling you're doing) what the flags actually do today in all circumstances and combinations. A consequence is that neither can he (or anyone else) always predict what you need to do to get a desired result. What shipped in 2.2 was solid to the extent that it supported everything used by the Python core. You and David are pushing it in other directions, and while it was intended to support them, this stuff was never really *tried* at the C level beyond the demo xxsubtype.c module and some ExtensionClass fiddling. Most "weird experiments" were tried at the Python level instead, just because it's so much more time-efficient to try stuff in Python, and time was in short supply. So you're pioneers, and you've got to draw your own maps of the new territory. Luckily, God isn't resting yet, so He can still create new lifeforms if needed <wink>.
One property of types that do not have define HEAPTYPE is that their __module__ attribute is always __builtin__. This makes them mighty hard to pickle. It further suggests that every type that isn't a builtin type should define HEAPTYPE.
Yup, all kinds of questions get answered by "does it have HEAPTYPE?" that don't have any obvious connection to heaps. One of my favorites is this seemingly straightforward branch in type_repr(): if (type->tp_flags & Py_TPFLAGS_HEAPTYPE) kind = "class"; else kind = "type"; The philosophical questions that raises could go on for pages <wink>.