[Python-Dev] GC, flags, and subtyping

[Martin v. Loewis]

"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