documentation of tp_alloc and tp_free inheritance for heap types is incorrect #160749

Documentation

The documentation for tp_alloc currently reads:

Inheritance:

Static subtypes inherit this slot, which will be PyType_GenericAlloc() if inherited from object.

Heap subtypes do not inherit this slot.

Default:

For heap subtypes, this field is always set to PyType_GenericAlloc().

For static subtypes, this slot is inherited (see above).

The information for heap subtypes is not correct. If not set, the slot is inherited in inherit_slots unconditionally.

It appears that "heap subtypes" in this statement might incorrectly refer to those allocated by type() or class Python operations rather than via C-API constructors.

tp_free seems to have a similar issue. The documentation for "static types" seems to again apply to all types constructed through the C API, whether a static or heap type. The documentation for "heap types" seems to instead apply to Python-created types.

Should the behaviour be adjusted to match documentation, or the documentation corrected? cc @encukou @vstinner

Linked PRs

• gh-160749: Correct documentation of tp_alloc and tp_free inheritance for heap types #160821