GH-140052: Add PyTuple_MakeSingle and PyTuple_MakePair

Doc/c-api/tuple.rst

@@ -58,6 +58,34 @@ 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 the new reference to the *one* object.
+   ``PyTuple_MakeSingle(a)`` is equivalent to ``PyTuple_Pack(1, a)``.
+
+   .. warning::
+
+      This function expects non ``NULL`` object *one*.
+      Checking is performed as an assertion if Python is built in
+      :ref:`debug mode <debug-build>` or :option:`with assertions <--with-assertions>`.
+
+
+.. 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 the new references to the *one* and *two* objects.
+   ``PyTuple_MakePair(a, b)`` is equivalent to ``PyTuple_Pack(2, a, b)``.
+
+   .. warning::
+
+      This function expects non ``NULL`` objects *one* and *two*.
+      Checking is performed as an assertion if Python is built in
+      :ref:`debug mode <debug-build>` or :option:`with assertions <--with-assertions>`.
+
+
 .. 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/tupleobject.h

@@ -34,6 +34,9 @@ PyAPI_FUNC(int) PyTuple_SetItem(PyObject *, Py_ssize_t, PyObject *);
 PyAPI_FUNC(PyObject *) PyTuple_GetSlice(PyObject *, Py_ssize_t, Py_ssize_t);
 PyAPI_FUNC(PyObject *) PyTuple_Pack(Py_ssize_t, ...);
 
+PyAPI_FUNC(PyObject *) PyTuple_MakeSingle(PyObject *one);
+PyAPI_FUNC(PyObject *) PyTuple_MakePair(PyObject *one, PyObject *two);
+
 #ifndef Py_LIMITED_API
 #  define Py_CPYTHON_TUPLEOBJECT_H
 #  include "cpython/tupleobject.h"

Lib/test/test_capi/test_tuple.py

@@ -99,6 +99,35 @@ 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,))
+
+        temp = object()
+        self.assertEqual(make_single(temp), (temp,))
+
+        self.assertRaises(TypeError, make_single, 1, 2)
+        self.assertRaises(TypeError, make_single)
+
+    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))
+
+        temp = object()
+        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)
+
     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,4 @@
+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,29 @@ tuple_fromarray(PyObject* Py_UNUSED(module), PyObject *args)
     return PyTuple_FromArray(items, size);
 }
 
+static PyObject *
+tuple_make_single(PyObject *Py_UNUSED(module), PyObject *args)
+{
+    PyObject *one;
+    if (!PyArg_ParseTuple(args, "O", &one)) {
+        return NULL;
+    }
+
+    return PyTuple_MakeSingle(one);
+}
+
+static PyObject *
+tuple_make_pair(PyObject *Py_UNUSED(module), PyObject *args)
+{
+    PyObject *one;
+    PyObject *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 +161,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_VARARGS},
+    {"tuple_make_pair", tuple_make_pair, METH_VARARGS},
     {NULL},
 };
 

Objects/tupleobject.c

@@ -184,6 +184,35 @@ 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);
+    _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);
+    _PyObject_GC_TRACK(op);
+    return (PyObject *) op;
+}
 
 /* Methods */