Remove Py_digit type; update the doc

python · vstinner · Dec 13, 2024 · Jul 2, 2024 · Jul 23, 2024 · Sep 3, 2024
commit 4aa25f64eb01e00caa37bf4e9e445e47f1770993
diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
@@ -615,21 +615,6 @@ Export API
 
 .. versionadded:: 3.14
 
-.. c:type:: Py_digit
-
-   A single unsigned digit in the range [``0``; ``PyLong_BASE - 1``].
-
-   It is usually used in an *array of digits*, such as the
-   :c:member:`PyLong_DigitArray.digits` array.
-
-   Its size depend on the :c:macro:`!PYLONG_BITS_IN_DIGIT` macro:
-   see the ``configure`` :option:`--enable-big-digits` option.
-
-   See :c:member:`PyLongLayout.bits_per_digit` for the number of bits per
-   digit and :c:member:`PyLongLayout.digit_size` for the size of a digit (in
-   bytes).
-
-
 .. c:struct:: PyLongLayout
 
    Layout of an array of digits, used by Python :class:`int` object.
@@ -669,11 +654,23 @@ Export API
    See the :c:struct:`PyLongLayout` structure.
 
 
-.. c:struct:: PyLong_DigitArray
+.. c:struct:: PyLongExport
+
+   Export of a Python :class:`int` object.
 
-   A Python :class:`int` object exported as an array of digits.
+   There are two cases:
 
-   .. c:member:: int negative
+   * If :c:member:`digits` is ``NULL``, only use the :c:member:`value` member.
+     Calling :c:func:`PyLong_FreeExport` is optional in this case.
+   * If :c:member:`digits` is not ``NULL``, use :c:member:`negative`,
+     :c:member:`ndigits` and :c:member:`digits` members.
+     Calling :c:func:`PyLong_FreeExport` is mandatory in this case.
+
+   .. c:member:: int64_t value
+
+      Integer value if :c:member:`digits` is ``NULL``.
+
+   .. c:member:: uint8_t negative
 
       1 if the number is negative, 0 otherwise.
 
@@ -683,26 +680,26 @@ Export API
 
    .. c:member:: const void *digits
 
-      Read-only array of unsigned digits.
+      Read-only array of unsigned digits. Can be ``NULL``.
 
 
-.. c:function:: int PyLong_Export(PyObject *obj, PyLong_DigitArray *array)
+.. c:function:: int PyLong_Export(PyObject *obj, PyLongExport *export_long)
 
-   Export a Python :class:`int` object as an array of digits.
+   Export a Python :class:`int` object.
 
-   On success, set *\*array* and return 0.
+   On success, set *\*export_long* and return 0.
    On error, set an exception and return -1.
 
    This function always succeeds if *obj* is a Python :class:`int` object or a
    subclass.
 
-   :c:func:`PyLong_FreeExport` must be called once done with using
-   *array*.
+   If *export_long.digits* is not ``NULL, :c:func:`PyLong_FreeExport` must be
+   called when the export is no longer needed.
 
-
+
+    .. impl-detail::
+
+        This function always succeeds if *obj* is a Python :class:`int` object
+        or a subclass.
+
-
+
+    .. impl-detail::
+
+        This function always succeeds if *obj* is a Python :class:`int` object
+        or a subclass.
+
 
-.. c:function:: void PyLong_FreeExport(PyLong_DigitArray *array)
+.. c:function:: void PyLong_FreeExport(PyLongExport *export_long)
 
-   Release the export *array* created by :c:func:`PyLong_Export`.
+   Release the export *export_long* created by :c:func:`PyLong_Export`.
 
 
 PyLongWriter API
@@ -748,21 +745,3 @@ The :c:type:`PyLongWriter` API can be used to import an integer.
 .. c:function:: void PyLongWriter_Discard(PyLongWriter *writer)
 
    Discard the internal object and destroy the writer instance.
-
-
-Example creating an integer from an array of digits::
-
-    PyObject *
-    long_import(int negative, Py_ssize_t ndigits, Py_digit *digits)
-    {
-        void *writer_digits;
-        PyLongWriter *writer = PyLongWriter_Create(negative, ndigits,
-                                                   &writer_digits);
-        if (writer == NULL) {
-            return NULL;
-        }
-
-        assert(layout.digit_size == sizeof(Py_digit));
-        memcpy(writer_digits, digits, ndigits * sizeof(Py_digit));
-        return PyLongWriter_Finish(writer);
-    }
diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
@@ -531,8 +531,8 @@ New Features
 * Add a new import and export API for Python :class:`int` objects:
 
   * :c:func:`PyLong_GetNativeLayout`;
-  * :c:func:`PyLong_AsDigitArray`;
-  * :c:func:`PyLong_FreeDigitArray`;
+  * :c:func:`PyLong_Export`;
+  * :c:func:`PyLong_FreeExport`;
   * :c:func:`PyLongWriter_Create`;
   * :c:func:`PyLongWriter_Finish`;
   * :c:func:`PyLongWriter_Discard`.

diff --git a/Include/cpython/longintrepr.h b/Include/cpython/longintrepr.h
@@ -58,10 +58,8 @@ typedef long stwodigits; /* signed variant of twodigits */
 #else
 #error "PYLONG_BITS_IN_DIGIT should be 15 or 30"
 #endif
-#define PyLong_BASE     ((Py_digit)1 << PyLong_SHIFT)
-#define PyLong_MASK     ((Py_digit)(PyLong_BASE - 1))
-
-typedef digit Py_digit;
+#define PyLong_BASE     ((digit)1 << PyLong_SHIFT)
+#define PyLong_MASK     ((digit)(PyLong_BASE - 1))
 
 /* Long integer representation.
 

diff --git a/Misc/NEWS.d/next/C API/2024-07-03-17-26-53.gh-issue-102471.XpmKYk.rst b/Misc/NEWS.d/next/C API/2024-07-03-17-26-53.gh-issue-102471.XpmKYk.rst
@@ -1,8 +1,8 @@
 Add a new import and export API for Python :class:`int` objects:
 
 * :c:func:`PyLong_GetNativeLayout`;
-* :c:func:`PyLong_AsDigitArray`;
-* :c:func:`PyLong_FreeDigitArray`;
+* :c:func:`PyLong_Export`;
+* :c:func:`PyLong_FreeExport`;
 * :c:func:`PyLongWriter_Create`;
 * :c:func:`PyLongWriter_Finish`;
 * :c:func:`PyLongWriter_Discard`.

diff --git a/Modules/_testcapi/long.c b/Modules/_testcapi/long.c
@@ -186,21 +186,21 @@ pylong_export(PyObject *module, PyObject *obj)
         // PyLong_FreeExport() is not needed in this case
     }
 
-    assert(PyLong_GetNativeLayout()->digit_size == sizeof(Py_digit));
-    const Py_digit *export_long_digits = export_long.digits;
+    assert(PyLong_GetNativeLayout()->digit_size == sizeof(digit));
+    const digit *export_long_digits = export_long.digits;
 
     PyObject *digits = PyList_New(0);
     for (Py_ssize_t i=0; i < export_long.ndigits; i++) {
-        PyObject *digit = PyLong_FromUnsignedLong(export_long_digits[i]);
-        if (digit == NULL) {
+        PyObject *item = PyLong_FromUnsignedLong(export_long_digits[i]);
+        if (item == NULL) {
             goto error;
         }
 
-        if (PyList_Append(digits, digit) < 0) {
-            Py_DECREF(digit);
+        if (PyList_Append(digits, item) < 0) {
+            Py_DECREF(item);
             goto error;
         }
-        Py_DECREF(digit);
+        Py_DECREF(item);
     }
 
     PyObject *res = Py_BuildValue("(iN)", export_long.negative, digits);
@@ -230,7 +230,7 @@ pylongwriter_create(PyObject *module, PyObject *args)
     }
     Py_ssize_t ndigits = PyList_GET_SIZE(list);
 
-    Py_digit *digits = PyMem_Malloc(ndigits * sizeof(Py_digit));
+    digit *digits = PyMem_Malloc(ndigits * sizeof(digit));
     if (digits == NULL) {
         PyErr_NoMemory();
         return NULL;
@@ -239,16 +239,16 @@ pylongwriter_create(PyObject *module, PyObject *args)
     for (Py_ssize_t i=0; i < ndigits; i++) {
         PyObject *item = PyList_GET_ITEM(list, i);
 
-        long digit = PyLong_AsLong(item);
-        if (digit == -1 && PyErr_Occurred()) {
+        long num = PyLong_AsLong(item);
+        if (num == -1 && PyErr_Occurred()) {
             goto error;
         }
 
-        if (digit < 0 || digit >= PyLong_BASE) {
-            PyErr_SetString(PyExc_ValueError, "digit doesn't fit into Py_digit");
+        if (num < 0 || num >= PyLong_BASE) {
+            PyErr_SetString(PyExc_ValueError, "digit doesn't fit into digit");
             goto error;
         }
-        digits[i] = (Py_digit)digit;
+        digits[i] = (digit)num;
     }
 
     void *writer_digits;
@@ -257,8 +257,8 @@ pylongwriter_create(PyObject *module, PyObject *args)
     if (writer == NULL) {
         goto error;
     }
-    assert(PyLong_GetNativeLayout()->digit_size == sizeof(Py_digit));
-    memcpy(writer_digits, digits, ndigits * sizeof(Py_digit));
+    assert(PyLong_GetNativeLayout()->digit_size == sizeof(digit));
+    memcpy(writer_digits, digits, ndigits * sizeof(digit));
     PyObject *res = PyLongWriter_Finish(writer);
     PyMem_Free(digits);