Description

vstinner

opened on Nov 8, 2026

Issue body actions

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.

Linked PRs

• gh-161635: Add PyList_AsTupleAndClear() function #161637

Activity

1. vstinner

   added

   type-featureA feature request or enhancementA feature request or enhancement

   topic-C-API

   on Nov 8, 2026
2. vstinner

   added 2 commits that reference this issue on Nov 8, 2026

   pythongh-161635: Add PyList_AsTupleAndClear() function

   d74e511

   pythongh-161635: Add PyList_AsTupleAndClear() function

   0823270
3. vstinner commented on Nov 8, 2026

   

   vstinner

   on Nov 8, 2026

   MemberAuthor

   More actions

   See also PyDict_AsFrozenDictAndClear() function which was added recently: #153410.

   C API Working decision to add PyDict_AsFrozenDictAndClear(): capi-workgroup/decisions#109.
4. vstinner commented on Nov 8, 2026

   

   vstinner

   on Nov 8, 2026

   MemberAuthor

   More actions

   See also the discussion: Add a dict method to convert to a frozendict?
5. picnixz

   added

   interpreter-core(Objects, Python, Grammar, and Parser dirs)(Objects, Python, Grammar, and Parser dirs)

   on Nov 8, 2026
6. encukou commented on Nov 9, 2026

   

   encukou

   on Nov 9, 2026

   Member

   More actions

   The intended usage for PyDict_AsFrozenDictAndClear is a “builder pattern”, but using a dict instead of a dedicated “DictWriter” type. This is a

   Unlike dicts, there's a proposal to add a ListWriter API. If we add that, building a tuple then means filling a listwriter, finishing it (paying for GC registration), then calling PyList_AsTupleAndClear and discarding the list.
   IMO, if we add PyListWriter, then it would be useful to add PyListWriter_FinishTuple to convert that directly to tuple without finalizing the intermediate list. And with that, PyList_AsTupleAndClear wouldn't be that useful (since as with PyDict_AsFrozenDictAndClear, it's mean to be used on a list you just created).

   Maybe we should rename PyListWriter to PySequenceWriter before adding it, with PySequenceWriter_FinishList and PySequenceWriter_Finish tuple.
7. vstinner commented on Nov 9, 2026

   

   vstinner

   on Nov 9, 2026

   MemberAuthor

   More actions

   See also #161694 "Add PyTupleWriter API".

Issue actions