GH-140052: Add PyTuple_MakeSingle and PyTuple_MakePair

Doc/c-api/tuple.rst

@@ -58,6 +58,26 @@ Tuple Objects
    ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
 
 
+.. c:function:: PyObject* PyTuple_MakeSingle(PyObject *one)
+
+   Return a new tuple object of size 1,
+   or ``NULL`` with an exception set on failure. The tuple value
+   is initialized with a new reference to the *one* object.
+   ``PyTuple_MakeSingle(a)`` is equivalent to ``PyTuple_Pack(1, a)``.
+
+   *one* must not be ``NULL``.
+
+
+.. c:function:: PyObject* PyTuple_MakePair(PyObject *one, PyObject *two)
+
+   Return a new tuple object of size 2,
+   or ``NULL`` with an exception set on failure. The tuple values
+   are initialized with new references to the *one* and *two* objects.
+   ``PyTuple_MakePair(a, b)`` is equivalent to ``PyTuple_Pack(2, a, b)``.
+
+   *one* and *two* must not be ``NULL``.
+
+
 .. c:function:: Py_ssize_t PyTuple_Size(PyObject *p)
 
    Take a pointer to a tuple object, and return the size of that tuple.

Doc/data/refcounts.dat

@@ -2359,6 +2359,13 @@ PyTuple_GetSlice:PyObject*:p:0:
 PyTuple_GetSlice:Py_ssize_t:low::
 PyTuple_GetSlice:Py_ssize_t:high::
 
+PyTuple_MakePair:PyObject*::+1:
+PyTuple_MakePair:PyObject*:one:+1:
+PyTuple_MakePair:PyObject*:two:+1:
+
+PyTuple_MakeSingle:PyObject*::+1:
+PyTuple_MakeSingle:PyObject*:one:+1:
+
 PyTuple_New:PyObject*::+1:
 PyTuple_New:Py_ssize_t:len::
 

Include/cpython/tupleobject.h

@@ -42,3 +42,6 @@ PyTuple_SET_ITEM(PyObject *op, Py_ssize_t index, PyObject *value) {
 PyAPI_FUNC(PyObject*) PyTuple_FromArray(
     PyObject *const *array,
     Py_ssize_t size);
+
+PyAPI_FUNC(PyObject *) PyTuple_MakeSingle(PyObject *one);
+PyAPI_FUNC(PyObject *) PyTuple_MakePair(PyObject *one, PyObject *two);

Lib/test/test_capi/test_tuple.py

@@ -99,6 +99,64 @@ def test_tuple_pack(self):
         # CRASHES pack(1, NULL)
         # CRASHES pack(2, [1])
 
+    def test_tuple_make_single(self):
+        # Test PyTuple_MakeSingle()
+        make_single = _testcapi.tuple_make_single
+
+        self.assertEqual(make_single(1), (1,))
+        self.assertEqual(make_single(None), (None,))
+        self.assertEqual(make_single(True), (True,))
+
+        # user class supports gc
+        class Temp:
+            pass
+
+        temp = Temp()
+        self.assertEqual(make_single(temp), (temp,))
+
+        self.assertRaises(TypeError, make_single, 1, 2)
+        self.assertRaises(TypeError, make_single)
+
+        self.assertFalse(gc.is_tracked(make_single(1)))
+        self.assertFalse(gc.is_tracked(make_single(None)))
+        self.assertFalse(gc.is_tracked(make_single(True)))
+        self.assertTrue(gc.is_tracked(make_single(temp)))
+        self.assertTrue(gc.is_tracked(make_single([])))
+        self.assertTrue(gc.is_tracked(make_single({})))
+
+        # because we only check type for gc support can't untrack tuple of
+        # immutable tuples, see maybe_tracked
+        self.assertTrue(gc.is_tracked(make_single((1, 2))))
+
+    def test_tuple_make_pair(self):
+        # Test PyTuple_MakePair()
+        make_pair = _testcapi.tuple_make_pair
+
+        self.assertEqual(make_pair(1, 2), (1, 2))
+        self.assertEqual(make_pair(None, None), (None, None))
+        self.assertEqual(make_pair(True, False), (True, False))
+
+        # user class supports gc
+        class Temp:
+            pass
+        temp = Temp()
+        self.assertEqual(make_pair(temp, temp), (temp, temp))
+
+        self.assertRaises(TypeError, make_pair, 1, 2, 3)
+        self.assertRaises(TypeError, make_pair, 1)
+        self.assertRaises(TypeError, make_pair)
+
+        self.assertFalse(gc.is_tracked(make_pair(1, 2)))
+        self.assertFalse(gc.is_tracked(make_pair(None, None)))
+        self.assertFalse(gc.is_tracked(make_pair(True, False)))
+        self.assertTrue(gc.is_tracked(make_pair(temp, (1, 2))))
+        self.assertTrue(gc.is_tracked(make_pair(temp, 1)))
+        self.assertTrue(gc.is_tracked(make_pair([], {})))
+
+        # because we only check type for gc support can't untrack tuple of
+        # immutable tuples, see maybe_tracked
+        self.assertTrue(gc.is_tracked(make_pair((1, 2), (1, 2))))
+
     def test_tuple_size(self):
         # Test PyTuple_Size()
         size = _testlimitedcapi.tuple_size

Misc/NEWS.d/next/Core_and_Builtins/2025-10-15-01-30-28.gh-issue-140052.08spgX.rst

@@ -0,0 +1,2 @@
+Add :c:func:`PyTuple_MakeSingle` and :c:func:`PyTuple_MakePair` functions to
+create short-sized tuples. Patch by Sergey Miryanov.

Modules/_testcapi/tuple.c

@@ -130,6 +130,23 @@ tuple_fromarray(PyObject* Py_UNUSED(module), PyObject *args)
     return PyTuple_FromArray(items, size);
 }
 
+static PyObject *
+tuple_make_single(PyObject *Py_UNUSED(module), PyObject *one)
+{
+    return PyTuple_MakeSingle(one);
+}
+
+static PyObject *
+tuple_make_pair(PyObject *Py_UNUSED(module), PyObject *args)
+{
+    PyObject *one, *two;
+    if (!PyArg_ParseTuple(args, "OO", &one, &two)) {
+        return NULL;
+    }
+
+    return PyTuple_MakePair(one, two);
+}
+
 
 static PyMethodDef test_methods[] = {
     {"tuple_get_size", tuple_get_size, METH_O},
@@ -138,6 +155,8 @@ static PyMethodDef test_methods[] = {
     {"_tuple_resize", _tuple_resize, METH_VARARGS},
     {"_check_tuple_item_is_NULL", _check_tuple_item_is_NULL, METH_VARARGS},
     {"tuple_fromarray", tuple_fromarray, METH_VARARGS},
+    {"tuple_make_single", tuple_make_single, METH_O},
+    {"tuple_make_pair", tuple_make_pair, METH_VARARGS},
     {NULL},
 };
 

Objects/tupleobject.c

@@ -202,6 +202,39 @@ PyTuple_Pack(Py_ssize_t n, ...)
     return (PyObject *)result;
 }
 
+PyObject *
+PyTuple_MakeSingle(PyObject *one)
+{
+    assert (one != NULL);
+
+    PyTupleObject *op = tuple_alloc(1);
+    if (op == NULL) {
+        return NULL;
+    }
+    op->ob_item[0] = Py_NewRef(one);
+    if (maybe_tracked(one)) {
+        _PyObject_GC_TRACK(op);
+    }
+    return (PyObject *)op;
+}
+
+PyObject *
+PyTuple_MakePair(PyObject *one, PyObject *two)
+{
+    assert (one != NULL);
+    assert (two != NULL);
+
+    PyTupleObject *op = tuple_alloc(2);
+    if (op == NULL) {
+        return NULL;
+    }
+    op->ob_item[0] = Py_NewRef(one);
+    op->ob_item[1] = Py_NewRef(two);
+    if (maybe_tracked(one) || maybe_tracked(two)) {
+        _PyObject_GC_TRACK(op);
+    }
+    return (PyObject *)op;
+}
 
 /* Methods */