gh-128863: Deprecate _PyLong_New() function (#129212)

skirpichev · web-flow · commit 5c9a63f62c9e · 2025-01-23T13:50:34.000+01:00
diff --git a/Doc/deprecations/c-api-pending-removal-in-3.18.rst b/Doc/deprecations/c-api-pending-removal-in-3.18.rst
@@ -7,6 +7,7 @@ Pending removal in Python 3.18
   * :c:func:`!_PyDict_GetItemStringWithError`: use :c:func:`PyDict_GetItemStringRef`.
   * :c:func:`!_PyDict_Pop()`: :c:func:`PyDict_Pop`.
   * :c:func:`!_PyLong_Sign()`: use :c:func:`PyLong_GetSign`.
+  * :c:func:`!_PyLong_New`: use :c:func:`PyLongWriter_Create`.
   * :c:func:`!_PyThreadState_UncheckedGet`: use :c:func:`PyThreadState_GetUnchecked`.
   * :c:func:`!_PyUnicode_AsString`: use :c:func:`PyUnicode_AsUTF8`.
   * :c:func:`!_Py_HashPointer`: use :c:func:`Py_HashPointer`.
diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
@@ -1396,6 +1396,7 @@ Deprecated
   * :c:func:`!_PyDict_GetItemStringWithError`: use :c:func:`PyDict_GetItemStringRef`.
   * :c:func:`!_PyDict_Pop()`: use :c:func:`PyDict_Pop`.
   * :c:func:`!_PyLong_Sign()`: use :c:func:`PyLong_GetSign`.
+  * :c:func:`!_PyLong_New`: use :c:func:`PyLongWriter_Create`.
   * :c:func:`!_PyThreadState_UncheckedGet`: use :c:func:`PyThreadState_GetUnchecked`.
   * :c:func:`!_PyUnicode_AsString`: use :c:func:`PyUnicode_AsUTF8`.
   * :c:func:`!_Py_HashPointer`: use :c:func:`Py_HashPointer`.
diff --git a/Include/cpython/longintrepr.h b/Include/cpython/longintrepr.h
@@ -100,7 +100,7 @@ struct _longobject {
     _PyLongValue long_value;
 };
 
-PyAPI_FUNC(PyLongObject*) _PyLong_New(Py_ssize_t);
+Py_DEPRECATED(3.14) PyAPI_FUNC(PyLongObject*) _PyLong_New(Py_ssize_t);
 
 // Return a copy of src.
 PyAPI_FUNC(PyObject*) _PyLong_Copy(PyLongObject *src);
diff --git a/Misc/NEWS.d/next/C_API/2025-01-15-11-42-07.gh-issue-128863.C9MkB_.rst b/Misc/NEWS.d/next/C_API/2025-01-15-11-42-07.gh-issue-128863.C9MkB_.rst
@@ -5,6 +5,7 @@ Python 3.18:
 * :c:func:`!_PyDict_GetItemStringWithError`: use :c:func:`PyDict_GetItemStringRef`.
 * :c:func:`!_PyDict_Pop()`: use :c:func:`PyDict_Pop`.
 * :c:func:`!_PyLong_Sign()`: use :c:func:`PyLong_GetSign`.
+* :c:func:`!_PyLong_New`: use :c:func:`PyLongWriter_Create`.
 * :c:func:`!_PyThreadState_UncheckedGet`: use :c:func:`PyThreadState_GetUnchecked`.
 * :c:func:`!_PyUnicode_AsString`: use :c:func:`PyUnicode_AsUTF8`.
 * :c:func:`!_Py_HashPointer`: use :c:func:`Py_HashPointer`.
diff --git a/Objects/longobject.c b/Objects/longobject.c
@@ -152,8 +152,8 @@ long_normalize(PyLongObject *v)
 # define MAX_LONG_DIGITS ((INT64_MAX-1) / PyLong_SHIFT)
 #endif
 
-PyLongObject *
-_PyLong_New(Py_ssize_t size)
+static PyLongObject *
+long_alloc(Py_ssize_t size)
 {
     assert(size >= 0);
     PyLongObject *result = NULL;
@@ -190,14 +190,20 @@ _PyLong_New(Py_ssize_t size)
     return result;
 }
 
+PyLongObject *
+_PyLong_New(Py_ssize_t size)
+{
+    return long_alloc(size);
+}
+
 PyLongObject *
 _PyLong_FromDigits(int negative, Py_ssize_t digit_count, digit *digits)
 {
     assert(digit_count >= 0);
     if (digit_count == 0) {
         return (PyLongObject *)_PyLong_GetZero();
     }
-    PyLongObject *result = _PyLong_New(digit_count);
+    PyLongObject *result = long_alloc(digit_count);
     if (result == NULL) {
         PyErr_NoMemory();
         return NULL;
@@ -268,7 +274,7 @@ _PyLong_FromLarge(stwodigits ival)
         ++ndigits;
         t >>= PyLong_SHIFT;
     }
-    PyLongObject *v = _PyLong_New(ndigits);
+    PyLongObject *v = long_alloc(ndigits);
     if (v != NULL) {
         digit *p = v->long_value.ob_digit;
         _PyLong_SetSignAndDigitCount(v, sign, ndigits);
@@ -341,7 +347,7 @@ PyLong_FromLong(long ival)
     }
 
     /* Construct output value. */
-    v = _PyLong_New(ndigits);
+    v = long_alloc(ndigits);
     if (v != NULL) {
         digit *p = v->long_value.ob_digit;
         _PyLong_SetSignAndDigitCount(v, ival < 0 ? -1 : 1, ndigits);
@@ -366,7 +372,7 @@ PyLong_FromLong(long ival)
             ++ndigits; \
             t >>= PyLong_SHIFT; \
         } \
-        PyLongObject *v = _PyLong_New(ndigits); \
+        PyLongObject *v = long_alloc(ndigits); \
         if (v == NULL) { \
             return NULL; \
         } \
@@ -443,7 +449,7 @@ PyLong_FromDouble(double dval)
     frac = frexp(dval, &expo); /* dval = frac*2**expo; 0.0 <= frac < 1.0 */
     assert(expo > 0);
     ndig = (expo-1) / PyLong_SHIFT + 1; /* Number of 'digits' in result */
-    v = _PyLong_New(ndig);
+    v = long_alloc(ndig);
     if (v == NULL)
         return NULL;
     frac = ldexp(frac, (expo-1) % PyLong_SHIFT + 1);
@@ -952,7 +958,7 @@ _PyLong_FromByteArray(const unsigned char* bytes, size_t n,
         return NULL;
     }
     ndigits = (numsignificantbytes * 8 + PyLong_SHIFT - 1) / PyLong_SHIFT;
-    v = _PyLong_New(ndigits);
+    v = long_alloc(ndigits);
     if (v == NULL)
         return NULL;
 
@@ -1482,7 +1488,7 @@ PyLong_FromLongLong(long long ival)
     }
 
     /* Construct output value. */
-    v = _PyLong_New(ndigits);
+    v = long_alloc(ndigits);
     if (v != NULL) {
         digit *p = v->long_value.ob_digit;
         _PyLong_SetSignAndDigitCount(v, ival < 0 ? -1 : 1, ndigits);
@@ -1525,7 +1531,7 @@ PyLong_FromSsize_t(Py_ssize_t ival)
         ++ndigits;
         t >>= PyLong_SHIFT;
     }
-    v = _PyLong_New(ndigits);
+    v = long_alloc(ndigits);
     if (v != NULL) {
         digit *p = v->long_value.ob_digit;
         _PyLong_SetSignAndDigitCount(v, negative ? -1 : 1, ndigits);
@@ -2015,7 +2021,7 @@ divrem1(PyLongObject *a, digit n, digit *prem)
     PyLongObject *z;
 
     assert(n > 0 && n <= PyLong_MASK);
-    z = _PyLong_New(size);
+    z = long_alloc(size);
     if (z == NULL)
         return NULL;
     *prem = inplace_divrem1(z->long_value.ob_digit, a->long_value.ob_digit, size, n);
@@ -2192,7 +2198,7 @@ long_to_decimal_string_internal(PyObject *aa,
         (10 * PyLong_SHIFT - 33 * _PyLong_DECIMAL_SHIFT);
     assert(size_a < PY_SSIZE_T_MAX/2);
     size = 1 + size_a + size_a / d;
-    scratch = _PyLong_New(size);
+    scratch = long_alloc(size);
     if (scratch == NULL)
         return -1;
 
@@ -2635,7 +2641,7 @@ long_from_binary_base(const char *start, const char *end, Py_ssize_t digits, int
         return 0;
     }
     n = (digits * bits_per_char + PyLong_SHIFT - 1) / PyLong_SHIFT;
-    z = _PyLong_New(n);
+    z = long_alloc(n);
     if (z == NULL) {
         *res = NULL;
         return 0;
@@ -2839,7 +2845,7 @@ long_from_non_binary_base(const char *start, const char *end, Py_ssize_t digits,
      */
     double fsize_z = (double)digits * log_base_BASE[base] + 1.0;
     if (fsize_z > (double)MAX_LONG_DIGITS) {
-        /* The same exception as in _PyLong_New(). */
+        /* The same exception as in long_alloc(). */
         PyErr_SetString(PyExc_OverflowError,
                         "too many digits in integer");
         *res = NULL;
@@ -2849,7 +2855,7 @@ long_from_non_binary_base(const char *start, const char *end, Py_ssize_t digits,
     /* Uncomment next line to test exceedingly rare copy code */
     /* size_z = 1; */
     assert(size_z > 0);
-    z = _PyLong_New(size_z);
+    z = long_alloc(size_z);
     if (z == NULL) {
         *res = NULL;
         return 0;
@@ -2912,7 +2918,7 @@ long_from_non_binary_base(const char *start, const char *end, Py_ssize_t digits,
                 PyLongObject *tmp;
                 /* Extremely rare.  Get more space. */
                 assert(_PyLong_DigitCount(z) == size_z);
-                tmp = _PyLong_New(size_z + 1);
+                tmp = long_alloc(size_z + 1);
                 if (tmp == NULL) {
                     Py_DECREF(z);
                     *res = NULL;
@@ -3333,12 +3339,12 @@ x_divrem(PyLongObject *v1, PyLongObject *w1, PyLongObject **prem)
     size_v = _PyLong_DigitCount(v1);
     size_w = _PyLong_DigitCount(w1);
     assert(size_v >= size_w && size_w >= 2); /* Assert checks by div() */
-    v = _PyLong_New(size_v+1);
+    v = long_alloc(size_v+1);
     if (v == NULL) {
         *prem = NULL;
         return NULL;
     }
-    w = _PyLong_New(size_w);
+    w = long_alloc(size_w);
     if (w == NULL) {
         Py_DECREF(v);
         *prem = NULL;
@@ -3360,7 +3366,7 @@ x_divrem(PyLongObject *v1, PyLongObject *w1, PyLongObject **prem)
        at most (and usually exactly) k = size_v - size_w digits. */
     k = size_v - size_w;
     assert(k >= 0);
-    a = _PyLong_New(k);
+    a = long_alloc(k);
     if (a == NULL) {
         Py_DECREF(w);
         Py_DECREF(v);
@@ -3758,7 +3764,7 @@ x_add(PyLongObject *a, PyLongObject *b)
             size_a = size_b;
             size_b = size_temp; }
     }
-    z = _PyLong_New(size_a+1);
+    z = long_alloc(size_a+1);
     if (z == NULL)
         return NULL;
     for (i = 0; i < size_b; ++i) {
@@ -3807,7 +3813,7 @@ x_sub(PyLongObject *a, PyLongObject *b)
         }
         size_a = size_b = i+1;
     }
-    z = _PyLong_New(size_a);
+    z = long_alloc(size_a);
     if (z == NULL)
         return NULL;
     for (i = 0; i < size_b; ++i) {
@@ -3932,7 +3938,7 @@ x_mul(PyLongObject *a, PyLongObject *b)
     Py_ssize_t size_b = _PyLong_DigitCount(b);
     Py_ssize_t i;
 
-    z = _PyLong_New(size_a + size_b);
+    z = long_alloc(size_a + size_b);
     if (z == NULL)
         return NULL;
 
@@ -4042,9 +4048,9 @@ kmul_split(PyLongObject *n,
     size_lo = Py_MIN(size_n, size);
     size_hi = size_n - size_lo;
 
-    if ((hi = _PyLong_New(size_hi)) == NULL)
+    if ((hi = long_alloc(size_hi)) == NULL)
         return -1;
-    if ((lo = _PyLong_New(size_lo)) == NULL) {
+    if ((lo = long_alloc(size_lo)) == NULL) {
         Py_DECREF(hi);
         return -1;
     }
@@ -4144,7 +4150,7 @@ k_mul(PyLongObject *a, PyLongObject *b)
      */
 
     /* 1. Allocate result space. */
-    ret = _PyLong_New(asize + bsize);
+    ret = long_alloc(asize + bsize);
     if (ret == NULL) goto fail;
 #ifdef Py_DEBUG
     /* Fill with trash, to catch reference to uninitialized digits. */
@@ -4294,13 +4300,13 @@ k_lopsided_mul(PyLongObject *a, PyLongObject *b)
     assert(2 * asize <= bsize);
 
     /* Allocate result space, and zero it out. */
-    ret = _PyLong_New(asize + bsize);
+    ret = long_alloc(asize + bsize);
     if (ret == NULL)
         return NULL;
     memset(ret->long_value.ob_digit, 0, _PyLong_DigitCount(ret) * sizeof(digit));
 
     /* Successive slices of b are copied into bslice. */
-    bslice = _PyLong_New(asize);
+    bslice = long_alloc(asize);
     if (bslice == NULL)
         goto fail;
 
@@ -4766,7 +4772,7 @@ long_true_divide(PyObject *v, PyObject *w)
                             "intermediate overflow during division");
             goto error;
         }
-        x = _PyLong_New(a_size + shift_digits + 1);
+        x = long_alloc(a_size + shift_digits + 1);
         if (x == NULL)
             goto error;
         for (i = 0; i < shift_digits; i++)
@@ -4780,7 +4786,7 @@ long_true_divide(PyObject *v, PyObject *w)
         digit rem;
         /* x = a >> shift */
         assert(a_size >= shift_digits);
-        x = _PyLong_New(a_size - shift_digits);
+        x = long_alloc(a_size - shift_digits);
         if (x == NULL)
             goto error;
         rem = v_rshift(x->long_value.ob_digit, a->long_value.ob_digit + shift_digits,
@@ -5360,7 +5366,7 @@ long_rshift1(PyLongObject *a, Py_ssize_t wordshift, digit remshift)
         /* Shifting all the bits of 'a' out gives either -1 or 0. */
         return PyLong_FromLong(-a_negative);
     }
-    z = _PyLong_New(newsize);
+    z = long_alloc(newsize);
     if (z == NULL) {
         return NULL;
     }
@@ -5475,7 +5481,7 @@ long_lshift1(PyLongObject *a, Py_ssize_t wordshift, digit remshift)
     newsize = oldsize + wordshift;
     if (remshift)
         ++newsize;
-    z = _PyLong_New(newsize);
+    z = long_alloc(newsize);
     if (z == NULL)
         return NULL;
     if (_PyLong_IsNegative(a)) {
@@ -5590,7 +5596,7 @@ long_bitwise(PyLongObject *a,
     size_a = _PyLong_DigitCount(a);
     nega = _PyLong_IsNegative(a);
     if (nega) {
-        z = _PyLong_New(size_a);
+        z = long_alloc(size_a);
         if (z == NULL)
             return NULL;
         v_complement(z->long_value.ob_digit, a->long_value.ob_digit, size_a);
@@ -5604,7 +5610,7 @@ long_bitwise(PyLongObject *a,
     size_b = _PyLong_DigitCount(b);
     negb = _PyLong_IsNegative(b);
     if (negb) {
-        z = _PyLong_New(size_b);
+        z = long_alloc(size_b);
         if (z == NULL) {
             Py_DECREF(a);
             return NULL;
@@ -5648,7 +5654,7 @@ long_bitwise(PyLongObject *a,
 
     /* We allow an extra digit if z is negative, to make sure that
        the final two's complement of z doesn't overflow. */
-    z = _PyLong_New(size_z + negz);
+    z = long_alloc(size_z + negz);
     if (z == NULL) {
         Py_DECREF(a);
         Py_DECREF(b);
@@ -5846,7 +5852,7 @@ _PyLong_GCD(PyObject *aarg, PyObject *barg)
         }
         else {
             alloc_a = size_a;
-            c = _PyLong_New(size_a);
+            c = long_alloc(size_a);
             if (c == NULL)
                 goto error;
         }
@@ -5862,7 +5868,7 @@ _PyLong_GCD(PyObject *aarg, PyObject *barg)
         }
         else {
             alloc_b = size_a;
-            d = _PyLong_New(size_a);
+            d = long_alloc(size_a);
             if (d == NULL)
                 goto error;
         }
@@ -6910,7 +6916,7 @@ PyLongWriter_Create(int negative, Py_ssize_t ndigits, void **digits)
     }
     assert(digits != NULL);
 
-    PyLongObject *obj = _PyLong_New(ndigits);
+    PyLongObject *obj = long_alloc(ndigits);
     if (obj == NULL) {
         goto error;
     }
