docs(easy): Document that heap types need to support garbage collection

[Fidget-Spinner]

Documentation

In https://docs.python.org/3/c-api/typeobj.html#c.Py_TPFLAGS_HEAPTYPE, it does not mention that the heap type must support GC. However this is actually the case. The type itself needs to be visited by the GC because it forms a reference cycle with its own module object. We should document this.

Linked PRs

• gh-116935: Document that heap types need to support garbage collection #118021
• [3.12] gh-116935: Document that heap types need to support garbage collection (GH-118021) #118092

[neonene]

I think this is true when a heap type is created by PyType_From*() with a module explicitly specified. As to #116934, thread_handle_type in _threadmodule.c does not hold a module, so switching from tp_alloc() back to PyObject_New() at the object creation would also fix the refleaks when GC cannot be respected.

[savannahostrowski]

I'd be happy to open a PR to update the docs but wanted to make sure I understand the comment above.

@neonene Are you suggesting that heap types wouldn't have this requirement if PyObject_New() was used, making this documentation update unnecessary? If so, is that a favourable or in progress change?

[neonene]

As long as not a few heap types work in Python without tp_traverse, I think the docs can require us to follow the GC-protocol as a current rule. If the docs really need to mention technical reasons, tp_dict and tp_mro would be stronger than ht_module.