Dec 13, 2024 · Jul 2, 2024 · Jul 23, 2024 · Sep 3, 2024 · Sep 3, 2024 · Sep 3, 2024
diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst

 .. 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.
   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.


   .. 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.


 .. 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
 .. 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
 * 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
 #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
 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
        // PyLong_FreeExport() is not needed in this case
    }

    assert(PyLong_GetNativeLayout()->digit_size == sizeof(Py_digit));
    constPy_digit *export_long_digits = export_long.digits;
    assert(PyLong_GetNativeLayout()->digit_size == sizeof(digit));
    constdigit *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);
    }
    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;
    for (Py_ssize_t i=0; i < ndigits; i++) {
        PyObject *item = PyList_GET_ITEM(list, i);

        longdigit = PyLong_AsLong(item);
        if (digit == -1 && PyErr_Occurred()) {
        longnum = PyLong_AsLong(item);
        if (num == -1 && PyErr_Occurred()) {
            goto error;
        }

        if (digit < 0 ||digit >= PyLong_BASE) {
            PyErr_SetString(PyExc_ValueError, "digit doesn't fit intoPy_digit");
        if (num < 0 ||num >= PyLong_BASE) {
            PyErr_SetString(PyExc_ValueError, "digit doesn't fit intodigit");
            goto error;
        }
        digits[i] = (Py_digit)digit;
        digits[i] = (digit)num;
    }

    void *writer_digits;
    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);
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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`.
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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.

Expand Down
Original file line number	Diff line number	Diff line change
		@@ -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`.
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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));
		constPy_digit *export_long_digits = export_long.digits;
		assert(PyLong_GetNativeLayout()->digit_size == sizeof(digit));
		constdigit *export_long_digits = export_long.digits;

		PyObject *digits = PyList_New(0);
vstinner marked this conversation as resolved. Show resolvedHide resolved
		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);
vstinner marked this conversation as resolved. Show resolvedHide resolved
Expand DownExpand Up		@@ -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));
skirpichev marked this conversation as resolved. OutdatedShow resolvedHide resolved
		if (digits == NULL) {
		PyErr_NoMemory();
		return NULL;
Expand All		@@ -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);

		longdigit = PyLong_AsLong(item);
		if (digit == -1 && PyErr_Occurred()) {
		longnum = PyLong_AsLong(item);
		if (num == -1 && PyErr_Occurred()) {
		goto error;
		}

		if (digit < 0 \|\|digit >= PyLong_BASE) {
		PyErr_SetString(PyExc_ValueError, "digit doesn't fit intoPy_digit");
		if (num < 0 \|\|num >= PyLong_BASE) {
		PyErr_SetString(PyExc_ValueError, "digit doesn't fit intodigit");
		goto error;
		}
		digits[i] = (Py_digit)digit;
		digits[i] = (digit)num;
		}

		void *writer_digits;
Expand All		@@ -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));
skirpichev marked this conversation as resolved. OutdatedShow resolvedHide resolved
		PyObject *res = PyLongWriter_Finish(writer);
		PyMem_Free(digits);

Expand Down