Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 6446408

Browse filesBrowse files
vstinnerskirpichevzoobapicnixz
authored
gh-102471, PEP 757: Add PyLong import and export API (#121339)
Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com> Co-authored-by: Steve Dower <steve.dower@microsoft.com> Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
1 parent d05a4e6 commit 6446408
Copy full SHA for 6446408

File tree

Expand file treeCollapse file tree

9 files changed

+576
-0
lines changed
Filter options
Expand file treeCollapse file tree

9 files changed

+576
-0
lines changed

‎Doc/c-api/long.rst

Copy file name to clipboardExpand all lines: Doc/c-api/long.rst
+174Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -653,3 +653,177 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
653653
654654
.. versionadded:: 3.12
655655
656+
657+
Export API
658+
^^^^^^^^^^
659+
660+
.. versionadded:: next
661+
662+
.. c:struct:: PyLongLayout
663+
664+
Layout of an array of "digits" ("limbs" in the GMP terminology), used to
665+
represent absolute value for arbitrary precision integers.
666+
667+
Use :c:func:`PyLong_GetNativeLayout` to get the native layout of Python
668+
:class:`int` objects, used internally for integers with "big enough"
669+
absolute value.
670+
671+
See also :data:`sys.int_info` which exposes similar information in Python.
672+
673+
.. c:member:: uint8_t bits_per_digit
674+
675+
Bits per digit. For example, a 15 bit digit means that bits 0-14 contain
676+
meaningful information.
677+
678+
.. c:member:: uint8_t digit_size
679+
680+
Digit size in bytes. For example, a 15 bit digit will require at least 2
681+
bytes.
682+
683+
.. c:member:: int8_t digits_order
684+
685+
Digits order:
686+
687+
- ``1`` for most significant digit first
688+
- ``-1`` for least significant digit first
689+
690+
.. c:member:: int8_t digit_endianness
691+
692+
Digit endianness:
693+
694+
- ``1`` for most significant byte first (big endian)
695+
- ``-1`` for least significant byte first (little endian)
696+
697+
698+
.. c:function:: const PyLongLayout* PyLong_GetNativeLayout(void)
699+
700+
Get the native layout of Python :class:`int` objects.
701+
702+
See the :c:struct:`PyLongLayout` structure.
703+
704+
The function must not be called before Python initialization nor after
705+
Python finalization. The returned layout is valid until Python is
706+
finalized. The layout is the same for all Python sub-interpreters
707+
in a process, and so it can be cached.
708+
709+
710+
.. c:struct:: PyLongExport
711+
712+
Export of a Python :class:`int` object.
713+
714+
There are two cases:
715+
716+
* If :c:member:`digits` is ``NULL``, only use the :c:member:`value` member.
717+
* If :c:member:`digits` is not ``NULL``, use :c:member:`negative`,
718+
:c:member:`ndigits` and :c:member:`digits` members.
719+
720+
.. c:member:: int64_t value
721+
722+
The native integer value of the exported :class:`int` object.
723+
Only valid if :c:member:`digits` is ``NULL``.
724+
725+
.. c:member:: uint8_t negative
726+
727+
``1`` if the number is negative, ``0`` otherwise.
728+
Only valid if :c:member:`digits` is not ``NULL``.
729+
730+
.. c:member:: Py_ssize_t ndigits
731+
732+
Number of digits in :c:member:`digits` array.
733+
Only valid if :c:member:`digits` is not ``NULL``.
734+
735+
.. c:member:: const void *digits
736+
737+
Read-only array of unsigned digits. Can be ``NULL``.
738+
739+
740+
.. c:function:: int PyLong_Export(PyObject *obj, PyLongExport *export_long)
741+
742+
Export a Python :class:`int` object.
743+
744+
*export_long* must point to a :c:struct:`PyLongExport` structure allocated
745+
by the caller. It must not be ``NULL``.
746+
747+
On success, fill in *\*export_long* and return ``0``.
748+
On error, set an exception and return ``-1``.
749+
750+
:c:func:`PyLong_FreeExport` must be called when the export is no longer
751+
needed.
752+
753+
.. impl-detail::
754+
This function always succeeds if *obj* is a Python :class:`int` object
755+
or a subclass.
756+
757+
758+
.. c:function:: void PyLong_FreeExport(PyLongExport *export_long)
759+
760+
Release the export *export_long* created by :c:func:`PyLong_Export`.
761+
762+
.. impl-detail::
763+
Calling :c:func:`PyLong_FreeExport` is optional if *export_long->digits*
764+
is ``NULL``.
765+
766+
767+
PyLongWriter API
768+
^^^^^^^^^^^^^^^^
769+
770+
The :c:type:`PyLongWriter` API can be used to import an integer.
771+
772+
.. versionadded:: next
773+
774+
.. c:struct:: PyLongWriter
775+
776+
A Python :class:`int` writer instance.
777+
778+
The instance must be destroyed by :c:func:`PyLongWriter_Finish` or
779+
:c:func:`PyLongWriter_Discard`.
780+
781+
782+
.. c:function:: PyLongWriter* PyLongWriter_Create(int negative, Py_ssize_t ndigits, void **digits)
783+
784+
Create a :c:type:`PyLongWriter`.
785+
786+
On success, allocate *\*digits* and return a writer.
787+
On error, set an exception and return ``NULL``.
788+
789+
*negative* is ``1`` if the number is negative, or ``0`` otherwise.
790+
791+
*ndigits* is the number of digits in the *digits* array. It must be
792+
greater than 0.
793+
794+
*digits* must not be NULL.
795+
796+
After a successful call to this function, the caller should fill in the
797+
array of digits *digits* and then call :c:func:`PyLongWriter_Finish` to get
798+
a Python :class:`int`.
799+
The layout of *digits* is described by :c:func:`PyLong_GetNativeLayout`.
800+
801+
Digits must be in the range [``0``; ``(1 << bits_per_digit) - 1``]
802+
(where the :c:struct:`~PyLongLayout.bits_per_digit` is the number of bits
803+
per digit).
804+
Any unused most significant digits must be set to ``0``.
805+
806+
Alternately, call :c:func:`PyLongWriter_Discard` to destroy the writer
807+
instance without creating an :class:`~int` object.
808+
809+
810+
.. c:function:: PyObject* PyLongWriter_Finish(PyLongWriter *writer)
811+
812+
Finish a :c:type:`PyLongWriter` created by :c:func:`PyLongWriter_Create`.
813+
814+
On success, return a Python :class:`int` object.
815+
On error, set an exception and return ``NULL``.
816+
817+
The function takes care of normalizing the digits and converts the object
818+
to a compact integer if needed.
819+
820+
The writer instance and the *digits* array are invalid after the call.
821+
822+
823+
.. c:function:: void PyLongWriter_Discard(PyLongWriter *writer)
824+
825+
Discard a :c:type:`PyLongWriter` created by :c:func:`PyLongWriter_Create`.
826+
827+
*writer* must not be ``NULL``.
828+
829+
The writer instance and the *digits* array are invalid after the call.

‎Doc/data/refcounts.dat

Copy file name to clipboardExpand all lines: Doc/data/refcounts.dat
+7Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1299,6 +1299,13 @@ PyLong_GetSign:int:::
12991299
PyLong_GetSign:PyObject*:v:0:
13001300
PyLong_GetSign:int*:sign::
13011301

1302+
PyLong_Export:int:::
1303+
PyLong_Export:PyObject*:obj:0:
1304+
PyLong_Export:PyLongExport*:export_long::
1305+
1306+
PyLongWriter_Finish:PyObject*::+1:
1307+
PyLongWriter_Finish:PyLongWriter*:writer::
1308+
13021309
PyMapping_Check:int:::
13031310
PyMapping_Check:PyObject*:o:0:
13041311

‎Doc/whatsnew/3.14.rst

Copy file name to clipboardExpand all lines: Doc/whatsnew/3.14.rst
+11Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1018,6 +1018,17 @@ New features
10181018

10191019
(Contributed by Victor Stinner in :gh:`107954`.)
10201020

1021+
* Add a new import and export API for Python :class:`int` objects (:pep:`757`):
1022+
1023+
* :c:func:`PyLong_GetNativeLayout`;
1024+
* :c:func:`PyLong_Export`;
1025+
* :c:func:`PyLong_FreeExport`;
1026+
* :c:func:`PyLongWriter_Create`;
1027+
* :c:func:`PyLongWriter_Finish`;
1028+
* :c:func:`PyLongWriter_Discard`.
1029+
1030+
(Contributed by Victor Stinner in :gh:`102471`.)
1031+
10211032
* Add :c:func:`PyType_GetBaseByToken` and :c:data:`Py_tp_token` slot for easier
10221033
superclass identification, which attempts to resolve the `type checking issue
10231034
<https://peps.python.org/pep-0630/#type-checking>`__ mentioned in :pep:`630`

‎Include/cpython/longintrepr.h

Copy file name to clipboardExpand all lines: Include/cpython/longintrepr.h
+38Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,44 @@ _PyLong_CompactValue(const PyLongObject *op)
139139
#define PyUnstable_Long_CompactValue _PyLong_CompactValue
140140

141141

142+
/* --- Import/Export API -------------------------------------------------- */
143+
144+
typedef struct PyLongLayout {
145+
uint8_t bits_per_digit;
146+
uint8_t digit_size;
147+
int8_t digits_order;
148+
int8_t digit_endianness;
149+
} PyLongLayout;
150+
151+
PyAPI_FUNC(const PyLongLayout*) PyLong_GetNativeLayout(void);
152+
153+
typedef struct PyLongExport {
154+
int64_t value;
155+
uint8_t negative;
156+
Py_ssize_t ndigits;
157+
const void *digits;
158+
// Member used internally, must not be used for other purpose.
159+
Py_uintptr_t _reserved;
160+
} PyLongExport;
161+
162+
PyAPI_FUNC(int) PyLong_Export(
163+
PyObject *obj,
164+
PyLongExport *export_long);
165+
PyAPI_FUNC(void) PyLong_FreeExport(
166+
PyLongExport *export_long);
167+
168+
169+
/* --- PyLongWriter API --------------------------------------------------- */
170+
171+
typedef struct PyLongWriter PyLongWriter;
172+
173+
PyAPI_FUNC(PyLongWriter*) PyLongWriter_Create(
174+
int negative,
175+
Py_ssize_t ndigits,
176+
void **digits);
177+
PyAPI_FUNC(PyObject*) PyLongWriter_Finish(PyLongWriter *writer);
178+
PyAPI_FUNC(void) PyLongWriter_Discard(PyLongWriter *writer);
179+
142180
#ifdef __cplusplus
143181
}
144182
#endif

‎Lib/test/test_capi/test_long.py

Copy file name to clipboardExpand all lines: Lib/test/test_capi/test_long.py
+91Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010

1111
NULL = None
1212

13+
1314
class IntSubclass(int):
1415
pass
1516

@@ -714,5 +715,95 @@ def test_long_asuint64(self):
714715
self.check_long_asint(as_uint64, 0, UINT64_MAX,
715716
negative_value_error=ValueError)
716717

718+
def test_long_layout(self):
719+
# Test PyLong_GetNativeLayout()
720+
int_info = sys.int_info
721+
layout = _testcapi.get_pylong_layout()
722+
expected = {
723+
'bits_per_digit': int_info.bits_per_digit,
724+
'digit_size': int_info.sizeof_digit,
725+
'digits_order': -1,
726+
'digit_endianness': -1 if sys.byteorder == 'little' else 1,
727+
}
728+
self.assertEqual(layout, expected)
729+
730+
def test_long_export(self):
731+
# Test PyLong_Export()
732+
layout = _testcapi.get_pylong_layout()
733+
base = 2 ** layout['bits_per_digit']
734+
735+
pylong_export = _testcapi.pylong_export
736+
737+
# value fits into int64_t
738+
self.assertEqual(pylong_export(0), 0)
739+
self.assertEqual(pylong_export(123), 123)
740+
self.assertEqual(pylong_export(-123), -123)
741+
self.assertEqual(pylong_export(IntSubclass(123)), 123)
742+
743+
# use an array, doesn't fit into int64_t
744+
self.assertEqual(pylong_export(base**10 * 2 + 1),
745+
(0, [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2]))
746+
self.assertEqual(pylong_export(-(base**10 * 2 + 1)),
747+
(1, [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2]))
748+
self.assertEqual(pylong_export(IntSubclass(base**10 * 2 + 1)),
749+
(0, [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2]))
750+
751+
self.assertRaises(TypeError, pylong_export, 1.0)
752+
self.assertRaises(TypeError, pylong_export, 0+1j)
753+
self.assertRaises(TypeError, pylong_export, "abc")
754+
755+
def test_longwriter_create(self):
756+
# Test PyLongWriter_Create()
757+
layout = _testcapi.get_pylong_layout()
758+
base = 2 ** layout['bits_per_digit']
759+
760+
pylongwriter_create = _testcapi.pylongwriter_create
761+
self.assertRaises(ValueError, pylongwriter_create, 0, [])
762+
self.assertRaises(ValueError, pylongwriter_create, -123, [])
763+
self.assertEqual(pylongwriter_create(0, [0]), 0)
764+
self.assertEqual(pylongwriter_create(0, [123]), 123)
765+
self.assertEqual(pylongwriter_create(1, [123]), -123)
766+
self.assertEqual(pylongwriter_create(1, [1, 2]),
767+
-(base * 2 + 1))
768+
self.assertEqual(pylongwriter_create(0, [1, 2, 3]),
769+
base**2 * 3 + base * 2 + 1)
770+
max_digit = base - 1
771+
self.assertEqual(pylongwriter_create(0, [max_digit, max_digit, max_digit]),
772+
base**2 * max_digit + base * max_digit + max_digit)
773+
774+
# normalize
775+
self.assertEqual(pylongwriter_create(0, [123, 0, 0]), 123)
776+
777+
# test singletons + normalize
778+
for num in (-2, 0, 1, 5, 42, 100):
779+
self.assertIs(pylongwriter_create(bool(num < 0), [abs(num), 0]),
780+
num)
781+
782+
def to_digits(num):
783+
digits = []
784+
while True:
785+
num, digit = divmod(num, base)
786+
digits.append(digit)
787+
if not num:
788+
break
789+
return digits
790+
791+
# round trip: Python int -> export -> Python int
792+
pylong_export = _testcapi.pylong_export
793+
numbers = [*range(0, 10), 12345, 0xdeadbeef, 2**100, 2**100-1]
794+
numbers.extend(-num for num in list(numbers))
795+
for num in numbers:
796+
with self.subTest(num=num):
797+
data = pylong_export(num)
798+
if isinstance(data, tuple):
799+
negative, digits = data
800+
else:
801+
value = data
802+
negative = int(value < 0)
803+
digits = to_digits(abs(value))
804+
self.assertEqual(pylongwriter_create(negative, digits), num,
805+
(negative, digits))
806+
807+
717808
if __name__ == "__main__":
718809
unittest.main()

‎Misc/NEWS.d/next/C_API/2024-07-03-17-26-53.gh-issue-102471.XpmKYk.rst

Copy file name to clipboard
+10Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Add a new import and export API for Python :class:`int` objects (:pep:`757`):
2+
3+
* :c:func:`PyLong_GetNativeLayout`;
4+
* :c:func:`PyLong_Export`;
5+
* :c:func:`PyLong_FreeExport`;
6+
* :c:func:`PyLongWriter_Create`;
7+
* :c:func:`PyLongWriter_Finish`;
8+
* :c:func:`PyLongWriter_Discard`.
9+
10+
Patch by Victor Stinner.

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.