Repository navigation
[C API] Add PyList_AsTupleAndClear() function #161635
Description
Building a tuple when the size if known is advance is easy: allocate a new tuple with PyTuple_New(size) and then fill items using PyTuple_SetItem() or PyTuple_SET_ITEM().
Building a tuple when the final size is not known in advance is more complicated. It's possible to call _PyTuple_Resize() multiple time to resize the tuple. But it's more efficient to build a list, since the list is overallocated and so mutliple "resize" operations are more efficient.
The problem is that PyList_AsTuple() has to call Py_NewRef() on each time to create the tuple, and then call Py_DECREF() on each item when destroying the temporary list. I propose adding a new PyList_AsTupleAndClear() function to transfer items from the list to the tuple and so avoid the useless INCREF/DECREF dance.
PyList_AsTupleAndClear() should only be called when a temporary list is created in the same function and the list cannot be exposed to Python.
In fact, Python already has an internal _PyList_AsTupleAndClear() function, since it's the most efficient way to build a tuple from a list. I just propose to make the function public.
Activity
pythongh-161635: Add PyList_AsTupleAndClear() function
pythongh-161635: Add PyList_AsTupleAndClear() function
vstinner commentedon Nov 8, 2026
See also
PyDict_AsFrozenDictAndClear()function which was added recently: #153410.C API Working decision to add
PyDict_AsFrozenDictAndClear(): capi-workgroup/decisions#109.vstinner commentedon Nov 8, 2026
See also the discussion: Add a dict method to convert to a frozendict?
encukou commentedon Nov 9, 2026
The intended usage for
PyDict_AsFrozenDictAndClearis a “builder pattern”, but using a dict instead of a dedicated “DictWriter” type. This is aUnlike dicts, there's a proposal to add a
ListWriterAPI. If we add that, building a tuple then means filling a listwriter, finishing it (paying for GC registration), then callingPyList_AsTupleAndClearand discarding the list.IMO, if we add
PyListWriter, then it would be useful to addPyListWriter_FinishTupleto convert that directly to tuple without finalizing the intermediate list. And with that,PyList_AsTupleAndClearwouldn't be that useful (since as withPyDict_AsFrozenDictAndClear, it's mean to be used on a list you just created).Maybe we should rename
PyListWritertoPySequenceWriterbefore adding it, withPySequenceWriter_FinishListandPySequenceWriter_Finish tuple.vstinner commentedon Nov 9, 2026
See also #161694 "Add PyTupleWriter API".