gh-139772: Add PyDict_NewPresized() function

Author: vstinner

Doc/c-api/dict.rst

@@ -36,6 +36,14 @@ Dictionary Objects
    Return a new empty dictionary, or ``NULL`` on failure.
 
 
+.. c:function:: PyObject* PyDict_NewPresized(Py_ssize_t size)
+
+   Return a new empty dictionary with at least *size* preallocated items,
+   or ``NULL`` on failure.
+
+   .. versionadded:: next
+
+
 .. c:function:: PyObject* PyDictProxy_New(PyObject *mapping)
 
    Return a :class:`types.MappingProxyType` object for a mapping which

Doc/whatsnew/3.15.rst

@@ -852,6 +852,10 @@ New features
 
   (Contributed by Victor Stinner in :gh:`129813`.)
 
+* Add :c:func:`PyDict_NewPresized` function to create a new empty dictionary
+  with at least *size* preallocated items.
+  (Contributed by Victor Stinner in :gh:`139772`.)
+
 
 Porting to Python 3.15
 ----------------------

Include/cpython/dictobject.h

@@ -64,7 +64,12 @@ static inline Py_ssize_t PyDict_GET_SIZE(PyObject *op) {
 
 PyAPI_FUNC(int) PyDict_ContainsString(PyObject *mp, const char *key);
 
-PyAPI_FUNC(PyObject *) _PyDict_NewPresized(Py_ssize_t minused);
+PyAPI_FUNC(PyObject*) PyDict_NewPresized(Py_ssize_t size);
+Py_DEPRECATED(3.15) static inline PyObject*
+_PyDict_NewPresized(Py_ssize_t size)
+{
+    return PyDict_NewPresized(size);
+}
 
 PyAPI_FUNC(int) PyDict_Pop(PyObject *dict, PyObject *key, PyObject **result);
 PyAPI_FUNC(int) PyDict_PopString(PyObject *dict, const char *key, PyObject **result);

Lib/test/test_capi/test_dict.py

@@ -545,6 +545,17 @@ def test_dict_popstring(self):
         # CRASHES dict_popstring({}, NULL)
         # CRASHES dict_popstring({"a": 1}, NULL)
 
+    def test_dict_newpresized(self):
+        # Test PyDict_NewPresized()
+        dict_newpresized = _testcapi.dict_newpresized
+        d = dict_newpresized(3)
+        d[1] = 'a'
+        d[2] = 'b'
+        d[3] = 'c'
+        self.assertEqual(len(d), 3)
+        d[4] = 'd'
+        self.assertEqual(len(d), 4)
+
 
 if __name__ == "__main__":
     unittest.main()

Misc/NEWS.d/next/C_API/2025-10-08-15-26-21.gh-issue-139772.HBZeQA.rst

@@ -0,0 +1,2 @@
+Add :c:func:`PyDict_NewPresized` function to create a new empty dictionary with
+at least *size* preallocated items. Patch by Victor Stinner.

Modules/_testcapi/dict.c

@@ -258,6 +258,17 @@ test_dict_iteration(PyObject* self, PyObject *Py_UNUSED(ignored))
 }
 
 
+static PyObject *
+dict_newpresized(PyObject *self, PyObject *args)
+{
+    Py_ssize_t size;
+    if (!PyArg_ParseTuple(args, "n", &size)) {
+        return NULL;
+    }
+    return PyDict_NewPresized(size);
+}
+
+
 static PyMethodDef test_methods[] = {
     {"dict_containsstring", dict_containsstring, METH_VARARGS},
     {"dict_getitemref", dict_getitemref, METH_VARARGS},
@@ -268,7 +279,8 @@ static PyMethodDef test_methods[] = {
     {"dict_pop_null", dict_pop_null, METH_VARARGS},
     {"dict_popstring", dict_popstring, METH_VARARGS},
     {"dict_popstring_null", dict_popstring_null, METH_VARARGS},
-    {"test_dict_iteration",     test_dict_iteration,             METH_NOARGS},
+    {"test_dict_iteration", test_dict_iteration, METH_NOARGS},
+    {"dict_newpresized", dict_newpresized, METH_VARARGS},
     {NULL},
 };
 

Objects/dictobject.c

@@ -2220,9 +2220,9 @@ dict_new_presized(Py_ssize_t minused, bool unicode)
 }
 
 PyObject *
-_PyDict_NewPresized(Py_ssize_t minused)
+PyDict_NewPresized(Py_ssize_t size)
 {
-    return dict_new_presized(minused, false);
+    return dict_new_presized(size, false);
 }
 
 PyObject *