homepage

There appears to be very little, if any, documentation about how to handle the list at tp_weaklistoffset for types supporting being weak referenced, particularly with respect to garbage collection.
Who owns the list? Who owns the objects in the list? Should the list be traversed by the extension type's tp_traverse? Should it ever be INCREF'd or DECREF'd? Does tp_dealloc have any responsibilities with respect to it?
From looking at CPython's own source, it appears that tp_traverse should not touch it (Yhg1s confirmed this on #python). Cython, at least, appears to have come to an alternate conclusion though - it generates tp_traverse functions which visit the list (and provoke gc assertions to fail on Python 2.7 in debug mode).
Some documentation about what is correct to do would be excellent, and would make it easier to explain to Cython developers what they're doing wrong (or confirm that they're doing something right, in which case there are some more bugs to file against the CPython stdlib, since they do something different from Cython).

I think Cython is wrong here. The only thing to do is to call PyObject_ClearWeakRefs() in the deallocator. Everything else is handled by the interpreter.
Agreed improving the documentation would be good.

Just as a quick update here: Cython has since then switched to only using PyObject_ClearWeakRefs() and otherwise leaves the handling of the weakref slot to CPython.