René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"[C API] Add `PyTupleWriter` API","articleBody":"# Feature or enhancement\n\nHi,\n\nCreating a tuple with the current C API has multiple issues:\n\n* `PyTuple_SetItem()` and `PyTuple_SET_ITEM()` modify an **immutable** tuple.\n* `PyTuple_New()` creates an incomplete object: items are set to `NULL`. This is bad:\n  * https://github.com/capi-workgroup/problems/issues/56 \n  * https://github.com/capi-workgroup/api-evolution/issues/36\n* `PyTuple_New()` tracks directly the tuple in the garbage collector. For example, `gc.get_objects()` gives access to the incomplete tuple. Using the tuple, like calling `repr(tuple)`, can crash Python.\n* [`_PyTuple_Resize()`](https://docs.python.org/dev/c-api/tuple.html#c._PyTuple_Resize) is private which is surprising for a documented API. It stays private because it has issues.\n* `_PyTuple_Resize()` modifies an **immutable** tuple.\n* `_PyTuple_Resize()` must not be used of the refcount is greater than `1`: the API is fragile.\n\nI propose adding a new efficient `PyTupleWriter` API: work on a temporary \"writer\" object, and then call `Finish()` on it to get the tuple.\n\nI already proposed a similar API in 2023: [`_PyTupleBuilder`](https://github.com/python/cpython/pull/107139). Since that, Python C API got the [`PyUnicodeWriter` API](https://docs.python.org/dev/c-api/unicode.html#pyunicodewriter) and the [`PyBytesWriter` API](https://docs.python.org/dev/c-api/bytes.html#pybyteswriter) which are efficient writers for `str` and `bytes` objects, and the C API Working Group was created. The proposed API is now public and allocates the structure on the heap memory to hide the implementation details (the structure).\n\nMark Shannon asked if it would be possible to work on a list and then convert the list to a tuple, but it's [less efficient](https://github.com/python/cpython/issues/107137#issuecomment-1689718305). Tuples are commonly used in Python, and so creating a tuple should be efficient.\n\nMark Shannon also tried to initialize tuple items to `None` instead of `NULL` in `PyTuple_New()`. His attempt failed because of implementation issues. Also, this change only fix some of the issues that I listed, not all of them.\n\nAn alternative is to fill a C array of Python objects, call the new `PyTuple_FromArray()`, and then call `Py_DECREF()` on the array items. It requires to allocate and deallocate an array, and call `Py_DECREF()` on items. It can be less efficient.\n\n\u003c!-- gh-linked-prs --\u003e\n### Linked PRs\n* gh-139891\n* gh-140129\n\u003c!-- /gh-linked-prs --\u003e\n","author":{"url":"https://github.com/vstinner","@type":"Person","name":"vstinner"},"datePublished":"2025-10-10T07:43:53.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":7},"url":"https://github.com/139888/cpython/issues/139888"}