Add `PyTuple_FromPair`

[markshannon]

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 capi-workgroup/decisions#84 (comment)

Here's all the relevant PRs I could easily find:
#144529
#144531
#144532
#144760
#144771
#144772
#144773
#144829

Prior abandoned issue:
#140052 which also proposes adding PyTuple_FromSingle and which links to capi-workgroup/decisions#84.
capi-workgroup/decisions#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);

[markshannon]

Minor correction:
Some of the above PR suggest replacing PyTuple_Pack.
In terms of clarity or safety there is no real improvement in using PyTuple_FromPair, but there is a significant performance advantage; PyTuple_Pack is quite cumbersome

[sergey-miryanov]

If we decide to add this, I would like to work on it, if no one minds.

[markshannon]

If we decide to add this, I would like to work on it, if no one minds.

Please, go ahead.

I think the only real debate is which, if any, of these functions should go in the public API.
If you make the functions private initially, then there should be no objection

If you do want to add FromSingle and FromTriplet, could you do them in separate PRs later to avoid making the initial PR too big or contentious.