Add `PyTuple_FromPair`

Feature or enhancement

Proposal:

Rationale

We have had quite a few PRs lately suggesting replacing PyTuple_New (which requires manually setting the items) with PyTuple_FromArray.
Many of them have been rejected because of (maybe excessive) requirements for the authors to do benchmarking, even though the code is IMO a clear improvement. Almost all of these have been for pairs.
I propose adding PyTuple_FromPair to provide an idiomatic, fast and safe way to create 2-tuples.
We should also add a "steal" variant as well to simplify replacing PyTuple_New() ... PyTuple_SET_ITEM.

Note: I originally wanted to call this PyTuple_MakePair, but I'm taking PyTuple_FromPair from https://github.com/capi-workgroup/decisions/issues/84#issuecomment-3529843707

Here's all the relevant PRs I could easily find:
https://github.com/python/cpython/pull/144529
https://github.com/python/cpython/pull/144531
https://github.com/python/cpython/pull/144532
https://github.com/python/cpython/pull/144760
https://github.com/python/cpython/pull/144771
https://github.com/python/cpython/pull/144772
https://github.com/python/cpython/pull/144773
https://github.com/python/cpython/pull/144829

Prior abandoned issue:
https://github.com/python/cpython/issues/140052 which also proposes adding PyTuple_FromSingle and which links to https://github.com/capi-workgroup/decisions/issues/84.
https://github.com/capi-workgroup/decisions/issues/84 rejects the idea without any clear rationale.

Clarity

t = PyTuple_New(2);
// error handling here 

// Care must be taken not to leak the invalid tuple
PyTuple_SET_ITEM(t, a);
PyTuple_SET_ITEM(t, b);

compare with

t = PyTuple_FromPair(a, b);
// error handling here

Performance

Compared to PyTuple_New

PyTuple_FromPair can allocate directly from the free list without additional checks. It does not need to check for weird sizes, or special case size zero. It does not need to NULL out the items before they are set. It can determine whether the tuple needs to be tracked or not at construction without the overhead of tracking it, then later untracking it.

Compared to PyTuple_FromArray

The advantage is less than for PyTuple_New, but still significant, as it reduces memory traffic by not storing the items in an array, then reading them out again.

Safety

This has the same safety advantages as PyTuple_FromArray, as it never produces an incomplete tuple. Since much of the code it will replace is using PyTuple_New, this is a worthwhile improvement

Implementation

We should make this a private API to start with. Once it proves it use, then we can make it public.

PyObject *_PyTuple_MakePair(PyObject *a, PyObject *b);

PyObject *_PyTuple_MakePairSteal(PyObject *a, PyObject *b);

Linked PRs

• gh-145325
• gh-145842
• gh-145884
• gh-145910
• gh-146538
• gh-146537
• gh-148000
• gh-148003