Documentation

The "Thin Ice" section in Doc/extending/extending.rst explains a potential reference counting bug but it would be nice if it clarified the underlying CPython mechanism. Especially provides nice context for people learning about cpython internals.

Proposed solution:

Add 2-3 sentences explaining the call chain from PyList_SetItem -> Py_XDECREF -> tp_dealloc -> tp_finalize, and emphasizing that it happens synchronously.

Linked PRs

• gh-137740: Clarify __del__ invocation mechanism in reference counting #137741