The current Python C API PyTuple_New() to build a tuple has multiple flaws:

• The Python tuple object is immediately tracked by the GC, whereas its items are initialized to NULL (inconsistent tuple)
• The PyTuple_SET_ITEM() function must only used on a tuple while is being created

I propose adding a new internal C API to build a tuple: _PyTupleBuilder.

• User of the API doesn't access the tuple directly but uses higher API
• Over-allocate the tuple (by 25%) to reduce the number of _PyTuple_Resize() calls
• _PyTupleBuild_Append() grows the tuple if needed
• _PyTupleBuild_AppendUnsafe() is a thin wrapper to PyTuple_SET_ITEM()
• Only track the tuple once its fully initialized: correct size, all items are set
• Less error-prone API

Later, once we will consider this API stable, we can add it to the public C API and deprecate the old API to create an incomplete tuple:

• PyTuple_New()
• PyTuple_SetItem()
• PyTuple_SET_ITEM()
• _PyTuple_Resize()

See capi-workgroup/problems#56 for details on problems caused by API which let creating incomplete/inconsistent objects.

Linked PRs

• gh-107137: Add _PyTupleBuilder API to the internal C API #107139
• gh-107137: Add _PyTuple_NewNoTrack() internal C API #107183