Add `PyTuple_MakeSingle()` and `PyTuple_MakePair()` functions

[vstinner]

@sergey-miryanov analyzed the Python code base for tuple creation and identified that the most common tuple sizes are 1 and 2 items. He proposes adding PyTuple_MakeSingle() and PyTuple_MakePair() functions as the new way to create these tuples.

There are already other ways to build tuples of arbitrary size:

• PyTuple_New() + PyTuple_SET_ITEM()
• PyTuple_New() + PyTuple_SetItem()
• PyTuple_Pack()
• PyTuple_FromArray() -- new in Python 3.15

Proposed functions are a little bit faster, but it's matter of nanoseconds: benchmark on Linux. Fastest to slowest method:

• PyTuple_FromArray() -- PyTuple_MakeSingle() or PyTuple_MakePair() -- similar performance
• PyTuple_Pack()
• PyTuple_New() + PyTuple_SET_ITEM()
• PyTuple_New() + PyTuple_SetItem()

The difference with PyTuple_FromArray() is that you don't have to create a temporary array on the stack to build the tuple.

    PyObject *array[2] = {key, value};
    return PyTuple_FromArray(array, 2);

versus:

    return PyTuple_MakePair(key, value);

It's more convenient and natural to build a 2-tuple like that.

---

It's common to have to create strong references for items when building a new tuple. Example:

    PyObject *key = new_key();
    PyObject *value = new_value();
    if (!key || !value) {
        Py_XDECREF(key);
        Py_XDECREF(value);
        return NULL;
    }

    PyObject *tuple = PyTuple_MakePair(key, value);
    Py_DECREF(key);
    Py_DECREF(value);
    return tuple;

It was also proposed to add PyTuple_MakeSingleSteal() and PyTuple_MakePairSteal() variants which transfer the items ownership. The example becomes:

    PyObject *key = new_key();
    PyObject *value = new_value();
    if (!key || !value) {
        Py_XDECREF(key);
        Py_XDECREF(value);
        return NULL;
    }

    return PyTuple_MakePairSteal(key, value);

Using Steal variant, the final DECREF is no longer needed. But these variants were put aside for now.

@kumaraditya303 added:

I would prefer to have only steal versions because there are less redundant reference counting operations. decrefs are expensive on hot paths and users can easily incref before passing to steal function as needed.

Considering that reference counting is more expensive on free-threading, I think we should encourage the use of Steal functions to avoid redundant reference counting operations.

[encukou]

PyTuple_FromArray() -- PyTuple_MakeSingle() or PyTuple_MakePair() -- similar performance

That means that in C99, these functions could be replaced by the following, right?

#define PyTuple_MakeSingle(A) (PyTuple_FromArray((PyObject*[]){(A)}, 1))
#define PyTuple_MakePair(A, B) (PyTuple_FromArray((PyObject*[]){A, B}, 2))

(In C++ it's, AFAIK, different but similar. Code that needs to be compatible with both can use the explicit variable.)

I don't think this is worth adding new API/ABI.

[davidhewitt]

If the performance difference between these APIs and PyTuple_FromArray is negligible, it's probably the case that for PyO3 we wouldn't bother to add code complexity to special case creating 1- or 2- tuples.

@kumaraditya303 added:

I would prefer to have only steal versions because there are less redundant reference counting operations. decrefs are expensive on hot paths and users can easily incref before passing to steal function as needed.
Considering that reference counting is more expensive on free-threading, I think we should encourage the use of Steal functions to avoid redundant reference counting operations.

I support steal versions of tuple constructors being desirable, in Rust it's relatively easy to use stealing APIs correctly. Sounds like PyTuple_FromArraySteal would be enough.

[vstinner]

Sounds like PyTuple_FromArraySteal would be enough.

I looked at the CPython code base. There are 21 calls to "FromArray": 17 PyTuple_FromArray() and 4 _PyTuple_FromArraySteal(). So 19% of calls use Steal. Well, there are few calls, so I don't know if it's relevant :-) (I didn't count code generated by Argument Clinic in my stats.)

Example of Steal usage (simplified, I removed error handling):

    obja = PyLong_FromLong(a);
    objb = PyLong_FromLong(b);
    objc = PyLong_FromLong(c);
    PyObject *array[3] = { obja, objb, objc };
    return _PyTuple_FromArraySteal(array, 3);

Another example (also simplified):

    PyObject *oname = _PyUnicode_FromASCII(name, strlen(name));
    PyObject *oparg = PyLong_FromUnsignedLong(self->trace[index].oparg);
    PyObject *target = PyLong_FromUnsignedLong(self->trace[index].target);
    PyObject *operand = PyLong_FromUnsignedLongLong(self->trace[index].operand0);
    PyObject *args[4] = { oname, oparg, target, operand };
    return _PyTuple_FromArraySteal(args, 4);

[vstinner]

@erlend-aasland @serhiy-storchaka @zooba: Do you have an opinion on these tuple APIs?

[zooba]

My strongest opinion is to use "FromSingle" and "FromPair" rather than "Make". We use "From" everywhere else.

I don't see any particular benefit to adding stable ABI for this - a pointer and count is sufficient - and I don't particularly think we need public API either (MakeSingle(a) and FromArray(&a, 1) are identical). Making a pair is in a weird area where _Pack(2, a, b) is fine for C users and FromArray is more consistent and likely just as efficient for everyone else (we can add a fast path for n == 2 if it helps, without changing the ABI).

We have to draw a line somewhere or else our public API grows uncontrolled in all directions. So I'd rather draw it here and say we don't need every single specialisation to be permanently guaranteed. Show some compelling third-party benchmarks (50%+ improvement in a microbenchmark would do it) to justify making it public. It isn't that hard to define a two-member array or struct and pass it, and I suspect most code isn't performance sensitive enough to care.

[sergey-miryanov]

As a little note about microbenchmarks - results show that the MakeTuple version is a bit faster than FromArray one on the Windows build for non-tracked items - about 10-12%, in case that matters to anyone. :) (python/cpython#140132 (comment))

[zooba]

FromArray currently doesn't have any fast paths for n == 1 or n == 2, which I think would make a more fair comparison with the proposed additions. We can add that optimisation whenever we like without changing the ABI or signing ourselves up for more API.

10-12% isn't enough for me, though I can imagine it being enough for some people. A bit of optimisation ought to be able to get that under 10%, at which point I don't think anyone can care. (Also, did your Windows benchmark use PGO? The current FromArray implementation would likely benefit from it - a couple of the function calls will likely get inlined differently.)

[sergey-miryanov]

did your Windows benchmark use PGO?

No, if we use PGO for PyTuple_FromArray then PyTuple_MakeTuple will not use it (because PyTuple_MakeTuple not used in source except benchmarks). IMHO it is bit unfair :)

Anyway, add special cases for n in (1,2) for PyTuple_FromArray looks interesting.

[vstinner]

Anyway, add special cases for n in (1,2) for PyTuple_FromArray looks interesting.

I don't think that it's worth it.

[zooba]

No, if we use PGO for PyTuple_FromArray then PyTuple_MakeTuple will not use it (because PyTuple_MakeTuple not used in source except benchmarks). IMHO it is bit unfair :)

Then add some uses so it gets some coverage. It only needs to be called a couple of times - the actual number of calls don't make that big a difference (something like 99% of the runtime gets compiled for size after PGO anyway).

Anyway, add special cases for n in (1,2) for PyTuple_FromArray looks interesting.

I don't think that it's worth it.

Assume that we block the new APIs you've proposed. Is it worth it now?

[vstinner]

I suggest closing this issue.