The attached patch greatly enhances the documentation
for the tp_clear and tp_traverse functions. The patch
is against Doc/api/newtypes.tex, r45562.

Logged In: YES 
user_id=31435

I agree the additional info is helpful (thanks!).

Alas, there's more to it, and it's hard to know when to stop
:-(.

For example, an author of a type may _want_ to visit, e.g.,
contained strings in tp_traverse, because they want
gc.get_referents() to return the contained strings
(typically as a debugging aid).

The issues wrt to tp_clear are subtler.  The real
requirement is that the aggregate of all tp_clears called
break all possible cycles.  For one thing, that means
there's no real reason for a tp_clear to touch a member
that's known to be a Python string or integer (since such an
object can't be in a cycle, clearing it can't help to break
a cycle).  It's only tp_dealloc that _must_ drop references
to all containees.

Subtler is that a gc'ed container type may choose not to
implement tp_clear at all.  If you look, you'll see that
Python's tuple type in fact leaves its tp_clear slot empty.
 This isn't a problem because it's impossible to have a
cycle composed _solely_ of tuples (that may not be obvious,
but it's true -- it derives from that tuples are immutable).
 Any cycle a tuple may be in will be broken if the non-tuple
objects in the cycle clear their containees, so there's no
actually need for tuples to have a tp_clear.

The possibility should be mentioned, although it's fine to
recommend playing it safe.  Indeed, I don't think it buys
anything worth having for tuples not to have an obvious
tp_clear implementation.

Logged In: YES 
user_id=1344176

I've enhanced the patch per Tim Peters' comment.

Logged In: YES 
user_id=34209

As Tim said, there is more to it :) I think this is a fine
start, though. One minor point: the use of Py_CLEAR() can do
with some extra explanation. It obviously isn't enough to
just 'NULL out' members, since that would leak references,
but the docs should also explain that it is in fact
important to set the actual member to NULL *before*
DECREFing the reference, and then point out that the
Py_CLEAR macro is a convenient way of doing that. That kind
of tweak can happen after it's checked in, though
(preferably by someone who can build documentation and see
that the result looks okay ;)

Logged In: YES 
user_id=31435

Thanks, Collin!  I applied the patch, beefed up the
explanations, and committed as revision 45970 on the trunk,
affecting files:

Doc/api/newtypes.tex
Misc/ACKS
Misc/NEWS