8000 gh-102471, PEP 757: Add PyLong import and export API by vstinner · Pull Request #121339 · python/cpython · GitHub
[go: up one dir, main page]

Skip to content

gh-102471, PEP 757: Add PyLong import and export API #121339

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 54 commits into from
Dec 13, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
54 commits
Select commit Hold shift + click to select a range
f4fdbf2
gh-102471: Add PyLong import and export API
vstinner Jul 2, 2024
c2e568e
Add layout
vstinner Jul 23, 2024
f0d9525
Merge branch 'main' into long_export
vstinner Sep 3, 2024
b19764f
Rename word_endian to digits_order
vstinner Sep 3, 2024
6f7fd11
Replace Py_digit* type with void*
vstinner Sep 3, 2024
080e079
Add PyLongWriter_Discard() function
vstinner Sep 4, 2024
1a7902f
Fixes
vstinner Sep 5, 2024
b70a6dd
Use unsigned type for ndigits
vstinner Sep 5, 2024
07552a7
Remove again layout
vstinner Sep 5, 2024
0d0f942
Revert "Use unsigned type for ndigits"
vstinner Sep 6, 2024
762c33a
doc: adjust ndigits documentation
vstinner Sep 6, 2024
20be7a3
Update doc
vstinner Sep 13, 2024
d92bf1e
Make PyLong_DigitArray.obj private
vstinner Sep 16, 2024
b3b02a2
Remove reserved documentation
vstinner Sep 16, 2024
caca2d7
PyLong_FreeDigitArray() only clears _reserved
vstinner Sep 16, 2024
4221a49 8000
Make PyLong_LAYOUT static
vstinner Sep 16, 2024
37b1d49
Add PyLong_AsDigitArray.value
vstinner Sep 16, 2024
d70a121
Inline PyLong_AsInt64() to avoid the exception
vstinner Sep 17, 2024
4aa25f6
Remove Py_digit type; update the doc
vstinner Sep 17, 2024
90973d4
Merge branch 'main' into long_export
vstinner Sep 17, 2024
5d3e224
Add long_asnativebytes() function
vstinner Sep 17, 2024
c7d7cb2
Remove reference to removed Py_digit type
vstinner Sep 17, 2024
a3d601a
Address Antoine's review
vstinner Sep 17, 2024
c049268
Merge branch 'main' into long_export
vstinner Sep 17, 2024
06b196b
Merge branch 'main' into long_export
skirpichev Sep 18, 2024
3e8d296
Apply suggestions from code review
skirpichev Sep 18, 2024
86c68c2
Merge branch 'main' into long_export
skirpichev Sep 18, 2024
a8fd669
Revert "Add long_asnativebytes() function"
vstinner Sep 18, 2024
a04f9d0
Use PyLong_AsLongAndOverflow()
vstinner Sep 18, 2024
b2be94a
Try PyLong_AsLongLongAndOverflow() first
vstinner Sep 18, 2024
ca98ad1
Merge branch 'main' into long_export
vstinner Sep 18, 2024
167d75e
Update Doc/c-api/long.rst
vstinner Sep 19, 2024
5e53a5b
Sync implementation with PEP (#8)
skirpichev Oct 16, 2024
c24789f
Merge branch 'main' into long_export
skirpichev Nov 13, 2024
0422f9d
fix NL in Doc/c-api/long.rst (sorry, damn web editor)
skirpichev Nov 13, 2024
a529a48
rename news
skirpichev Nov 13, 2024
3db44f3
Address Erlend's review
vstinner Nov 13, 2024
1d2863e
Address Sergey's review
vstinner Nov 13, 2024
d663511
Merge branch 'main' into long_export
vstinner Nov 13, 2024
816798d
Merge branch 'main' into long_export
vstinner Nov 28, 2024
033bd65
Update documentation from PEP 757
vstinner Nov 28, 2024
36b87d4
Update Modules/_testcapi/long.c
vstinner Nov 28, 2024
94d852e
Sync implementation with PEP (#9)
skirpichev Dec 9, 2024
a72ff83
Merge branch 'main' into long_export
vstinner Dec 9, 2024
53d584b
Cleanup
vstinner Dec 9, 2024
577598a
Update Doc/c-api/long.rst
vstinner Dec 9, 2024
b08cd55
Address Steve's review
vstinner Dec 9, 2024
eaebef3
Address Bénédikt's review
vstinner Dec 10, 2024
03248c7
Apply suggestions from code review
vstinner Dec 10, 2024
0a26f97
Address Steve's review
vstinner Dec 11, 2024
88a62fe
Add PyLong_Export to Doc/data/refcounts.dat
vstinner Dec 12, 2024
45517ab
Address Serhiy's review
vstinner Dec 12, 2024
92007d1
Address Petr's review
vstinner Dec 12, 2024
6d3cb80
Add PyLongWriter to Doc/data/refcounts.dat
vstinner Dec 12, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Address Petr's review
  • Loading branch information
vstinner committed Dec 12, 2024
commit 92007d1c2c0d58b4cefcda6c39a180a6c564c64e
46 changes: 29 additions & 17 deletions Doc/c-api/long.rst
Original file line number Diff line number Diff line change
Expand Up @@ -703,8 +703,8 @@ Export API

The function must not be called before Python initialization nor after
Python finalization. The returned layout is valid until Python is
finalized. The layout is the same for all Python sub-interpreters and
so it can be cached.
finalized. The layout is the same for all Python sub-interpreters
in a process, and so it can be cached.


.. c:struct:: PyLongExport
Expand All @@ -714,10 +714,8 @@ Export API
There are two cases:

* 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

Expand All @@ -743,20 +741,28 @@ Export API

Export a Python :class:`int` object.

*export_long* must not be ``NULL``.
*export_long* must point to a :c:struct:`PyLongExport` structure allocated
by the caller. It must not be ``NULL``.

On success, set *\*export_long* and return ``0``.
On success, fill in *\*export_long* and return ``0``.
On error, set an exception and return ``-1``.

If *export_long->digits* is not ``NULL``, :c:func:`PyLong_FreeExport` must
be called when the export is no longer needed. Otherwise, calling
:c:func:`PyLong_FreeExport` is optional.
: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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
.. impl-detail::
This function always succeeds if *obj* is a Python :class:`int` object
or a subclass.

Lets see if we can restore this in a that way. It might be helpful for e.g. Sage, which doesn't support PyPy.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer to not add this note. It was controversial during PEP 757 design.

@serhiy-storchaka @encukou: What do you think? Would you be ok to declare that the PyLong_Export() function cannot fail if the argument is a Python int?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was controversial during PEP 757 design.

It was proposed unconditionally, not as CPython's implementation detail.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm fine with it, as an implementation detail.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


.. c:function:: void PyLong_FreeExport(PyLongExport *export_long)

Release the export *export_long* created by :c:func:`PyLong_Export`.

.. impl-detail::
Calling :c:func:`PyLong_FreeExport` is optional if *export_long->digits*
is ``NULL``.


PyLongWriter API
^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -787,12 +793,18 @@ The :c:type:`PyLongWriter` API can be used to import an integer.

*digits* must not be NULL.

The caller can either initialize the array of digits *digits* and then
either call :c:func:`PyLongWriter_Finish` to get a Python :class:`int` or
:c:func:`PyLongWriter_Discard` to destroy the writer instance. Digits must
be in the range [``0``; ``(1 << bits_per_digit) - 1``] (where the
:c:struct:`~PyLongLayout.bits_per_digit` is the number of bits per digit).
The unused most significant digits must be set to ``0``.
After a successful call to this function, the caller should fill in the
array of digits *digits* and then call :c:func:`PyLongWriter_Finish` to get
a Python :class:`int`.
The layout of *digits* is described by :c:func:`PyLong_GetNativeLayout`.

Digits must be in the range [``0``; ``(1 << bits_per_digit) - 1``]
(where the :c:struct:`~PyLongLayout.bits_per_digit` is the number of bits
per digit).
Any unused most significant digits must be set to ``0``.

Alternately, call :c:func:`PyLongWriter_Discard` to destroy the writer
instance without creating an :class:`~int` object.


.. c:function:: PyObject* PyLongWriter_Finish(PyLongWriter *writer)
Expand All @@ -805,7 +817,7 @@ The :c:type:`PyLongWriter` API can be used to import an integer.
The function takes care of normalizing the digits and converts the object
to a compact integer if needed.

The writer instance is invalid after the call.
The writer instance and the *digits* array are invalid after the call.


.. c:function:: void PyLongWriter_Discard(PyLongWriter *writer)
Expand All @@ -814,4 +826,4 @@ The :c:type:`PyLongWriter` API can be used to import an integer.

*writer* must not be ``NULL``.

The writer instance is invalid after the call.
The writer instance and the *digits* array are invalid after the call.
1 change: 0 additions & 1 deletion Doc/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -158,7 +158,6 @@
('c:type', 'size_t'),
('c:type', 'ssize_t'),
('c:type', 'time_t'),
('c:type', 'int8_t'),
('c:type', 'uint8_t'),
('c:type', 'uint16_t'),
9E88 ('c:type', 'uint32_t'),
Expand Down
5 changes: 3 additions & 2 deletions Modules/_testcapi/long.c
Original file line number Diff line number Diff line change
Expand Up @@ -164,8 +164,9 @@ pylong_export(PyObject *module, PyObject *obj)
assert(export_long.negative == 0);
assert(export_long.ndigits == 0);
assert(export_long.digits == NULL);
return PyLong_FromInt64(export_long.value);
// PyLong_FreeExport() is not needed in this case
PyObject *res = PyLong_FromInt64(export_long.value);
PyLong_FreeExport(&export_long);
return res;
}

assert(PyLong_GetNativeLayout()->digit_size == sizeof(digit));
Expand Down
1 change: 1 addition & 0 deletions Objects/longobject.c
Original file line number Diff line number Diff line change
Expand Up @@ -6797,6 +6797,7 @@ int
PyLong_Export(PyObject *obj, PyLongExport *export_long)
{
if (!PyLong_Check(obj)) {
memset(export_long, 0, sizeof(*export_long));
PyErr_Format(PyExc_TypeError, "expect int, got %T", obj);
return -1;
}
Expand Down
Loading
0