PyTuple_SetItem documentation doesn't warn about refcount requirements

[Yhg1s]

The PyTuple_SetItem() function (correctly) raises a SystemError when used on a tuple whose refcount isn't 1. The PyTuple_SET_ITEM() macro doesn't have any checks on the refcount, but it's still really bad to use it on a tuple that already in use. However, the documentation doesn't mention this requirement. It could probably use a bright red flashing box with waving hands and a shouting man telling you not to use it on anything but newly created tuples.

By contrast, the docs for the _PyTuple_Resize() function, which also raises SystemErrow when used on a tuple whose refcount isn't 1, does warn about the refcount requirement, although it isn't clear how hard a requirement it is. (It says "should not be used" rather than "cannot be used".)

Linked PRs

• GH-117283: Add doc warning for PyTuple_SetItem refcount > 1 #117916

[savannahostrowski]

If no one is looking at this, I'd love to open a PR to update the docs.