[Python-Dev] GC, flags, and subtyping (original) (raw)

Martin v. Loewis martin@v.loewis.de
05 Apr 2002 08:59:59 +0200

"David Abrahams" <david.abrahams@rcn.com> writes:

I'm willing to work something up, if I can get some guidance as to the most appropriate form. It's not clear to me that there's an appropriate place in the structure of the API docs (it's not even clear to me that the API docs are the right place for this).

I think the API docs are the right place, probably section 10. Notice that it is very easy to move text from one section to another, so don't worry too much about where this text ends up.

More worrying is the fact that new-style classes aren't documented at all. There is nothing wrong, IMO, to start with a piece as obscure as the PyType_Ready function, and I'm not asking that you produce a full newstyle classes specification. However, it would be good if you could allocate a subsection to all aspects of newstyle classes on the C level that you can think of, perhaps filling in the parts that you have been using.

Notice that the API documentation currently does not even list what the slots in a type object are, or what the possible flags are. Some of it is explained in the embedding and extending tutorial, but that is the wrong place if you want comprehensiveness. So I'd envision the following structure:

10.3: Type Objects Mentions all the slots; subsections elaborate 10.3.1 Mapping Object Structures (what is currently 10.3) ... 10.3.6 GC 10.3.7 Rich Comparisons 10.3.8 Weak references 10.3.9 Descriptors 10.3.10 Object lifecycle 10.4 Inheriting Type Objects

As I said, the precise structure can be shifted once the text is there.

Hope this can get you started.

Regards, Martin