Skip to content

Commit 6e1a89a

Browse files
zoobazooba
committed
Rename to PyLong_AsNativeBytes
1 parent 22c2a64 commit 6e1a89a

File tree

8 files changed

+56
-48
lines changed

8 files changed

+56
-48
lines changed

‎Doc/c-api/long.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -113,18 +113,18 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
113113
retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`.
114114
115115
116-
.. c:function:: PyObject* PyLong_FromBits(const void* buffer, size_t n_bytes, int endianness)
116+
.. c:function:: PyObject* PyLong_FromNativeBytes(const void* buffer, size_t n_bytes, int endianness)
117117
118118
Create a Python integer from the value contained in the first *n_bytes* of
119-
*buffer*, interpreted as twos-complement.
119+
*buffer*, interpreted as a two's-complement signed number.
120120
121121
*endianness* may be passed ``-1`` for the native endian that CPython was
122122
compiled with, or ``0`` for big endian and ``1`` for little.
123123
124124
.. versionadded:: 3.13
125125
126126
127-
.. c:function:: PyObject* PyLong_FromUnsignedBits(const void* buffer, size_t n_bytes, int endianness)
127+
.. c:function:: PyObject* PyLong_FromUnsignedNativeBytes(const void* buffer, size_t n_bytes, int endianness)
128128
129129
Create a Python integer from the value contained in the first *n_bytes* of
130130
*buffer*, interpreted as an unsigned number.
@@ -354,7 +354,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
354354
Returns ``NULL`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.
355355
356356
357-
.. c:function:: int PyLong_CopyBits(PyObject *pylong, void* buffer, size_t n_bytes, int endianness)
357+
.. c:function:: int PyLong_AsNativeBytes(PyObject *pylong, void* buffer, size_t n_bytes, int endianness)
358358
359359
Copy the Python integer value to a native *buffer* of size *n_bytes*::
360360

‎Doc/whatsnew/3.13.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -560,6 +560,7 @@ Tier 2 IR by Mark Shannon and Guido van Rossum.
560560
Tier 2 optimizer by Ken Jin.)
561561

562562

563+
563564
Deprecated
564565
==========
565566

@@ -1490,9 +1491,9 @@ New Features
14901491
* Add :c:func:`Py_HashPointer` function to hash a pointer.
14911492
(Contributed by Victor Stinner in :gh:`111545`.)
14921493

1493-
* Add :c:func:`PyLong_CopyBits`, :c:func:`PyLong_FromBits` and
1494-
:c:func:`PyLong_FromUnsignedBits` functions to simplify converting between
1495-
native integer types and Python ``int`` objects.
1494+
* Add :c:func:`PyLong_AsNativeBytes`, :c:func:`PyLong_FromNativeBytes` and
1495+
:c:func:`PyLong_FromUnsignedNativeBytes` functions to simplify converting
1496+
between native integer types and Python ``int`` objects.
14961497
(Contributed by Steve Dower in :gh:`111140`.)
14971498

14981499

‎Include/cpython/longobject.h

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,14 @@
44

55
PyAPI_FUNC(PyObject*) PyLong_FromUnicodeObject(PyObject *u, int base);
66

7-
/* PyLong_CopyBits: Copy the integer value to a native buffer.
7+
/* PyLong_AsNativeBytes: Copy the integer value to a native variable.
8+
buffer points to the first byte of the variable.
89
n_bytes is the number of bytes available in the buffer. Pass 0 to request
910
the required size for the value.
1011
endianness is -1 for native endian, 0 for big endian or 1 for little.
12+
Big endian mode will write the most significant byte into the address
13+
directly referenced by buffer; little endian will write the least significant
14+
byte into that address.
1115
1216
If an exception is raised, returns a negative value.
1317
Otherwise, returns the number of bytes that are required to store the value.
@@ -19,20 +23,20 @@ PyAPI_FUNC(PyObject*) PyLong_FromUnicodeObject(PyObject *u, int base);
1923
may be larger than necessary - this function is not an accurate way to
2024
calculate the bit length of an integer object.
2125
*/
22-
PyAPI_FUNC(int) PyLong_CopyBits(PyObject* v, void* buffer, size_t n_bytes,
26+
PyAPI_FUNC(int) PyLong_AsNativeBytes(PyObject* v, void* buffer, size_t n_bytes,
2327
int endianness);
2428

25-
/* PyLong_FromBits: Create an int value from a native integer
29+
/* PyLong_FromNativeBytes: Create an int value from a native integer
2630
n_bytes is the number of bytes to read from the buffer. Passing 0 will
2731
always produce the zero int.
28-
PyLong_FromUnsignedBits always produces a non-negative int.
32+
PyLong_FromUnsignedNativeBytes always produces a non-negative int.
2933
endianness is -1 for native endian, 0 for big endian or 1 for little.
3034
3135
Returns the int object, or NULL with an exception set. */
32-
PyAPI_FUNC(PyObject*) PyLong_FromBits(const void* buffer, size_t n_bytes,
33-
int endianness);
34-
PyAPI_FUNC(PyObject*) PyLong_FromUnsignedBits(const void* buffer, size_t n_bytes,
36+
PyAPI_FUNC(PyObject*) PyLong_FromNativeBytes(const void* buffer, size_t n_bytes,
3537
int endianness);
38+
PyAPI_FUNC(PyObject*) PyLong_FromUnsignedNativeBytes(const void* buffer,
39+
size_t n_bytes, int endianness);
3640

3741
PyAPI_FUNC(int) PyUnstable_Long_IsCompact(const PyLongObject* op);
3842
PyAPI_FUNC(Py_ssize_t) PyUnstable_Long_CompactValue(const PyLongObject* op);

‎Lib/test/test_capi/test_long.py

Lines changed: 21 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -424,9 +424,9 @@ def test_long_asvoidptr(self):
424424
self.assertRaises(OverflowError, asvoidptr, -2**1000)
425425
# CRASHES asvoidptr(NULL)
426426

427-
def test_long_copybits(self):
427+
def test_long_asnativebytes(self):
428428
import math
429-
from _testcapi import pylong_copybits as copybits, SIZE_MAX
429+
from _testcapi import pylong_asnativebytes as asnativebytes, SIZE_MAX
430430

431431
# Abbreviate sizeof(Py_ssize_t) to SZ because we use it a lot
432432
SZ = int(math.ceil(math.log(SIZE_MAX + 1) / math.log(2)) / 8)
@@ -451,8 +451,8 @@ def test_long_copybits(self):
451451
]:
452452
with self.subTest(f"sizeof-{v:X}"):
453453
buffer = bytearray(1)
454-
self.assertEqual(expect, copybits(v, buffer, 0, -1),
455-
"PyLong_CopyBits(v, NULL, 0, -1)")
454+
self.assertEqual(expect, asnativebytes(v, buffer, 0, -1),
455+
"PyLong_AsNativeBytes(v, NULL, 0, -1)")
456456

457457
# We request as many bytes as `expect_be` contains, and always check
458458
# the result (both big and little endian). We check the return value
@@ -507,16 +507,19 @@ def test_long_copybits(self):
507507
buffer = bytearray(n)
508508
expect_le = expect_be[::-1]
509509

510-
self.assertEqual(expect_n, copybits(v, buffer, n, 0),
511-
f"PyLong_CopyBits(v, buffer, {n}, <big>)")
510+
self.assertEqual(expect_n, asnativebytes(v, buffer, n, 0),
511+
f"PyLong_AsNativeBytes(v, buffer, {n}, <big>)")
512512
self.assertEqual(expect_be, buffer[:n], "<big>")
513-
self.assertEqual(expect_n, copybits(v, buffer, n, 1),
514-
f"PyLong_CopyBits(v, buffer, {n}, <little>)")
513+
self.assertEqual(expect_n, asnativebytes(v, buffer, n, 1),
514+
f"PyLong_AsNativeBytes(v, buffer, {n}, <little>)")
515515
self.assertEqual(expect_le, buffer[:n], "<little>")
516516

517-
def test_long_frombits(self):
517+
def test_long_fromnativebytes(self):
518518
import math
519-
from _testcapi import pylong_frombits as frombits, SIZE_MAX
519+
from _testcapi import (
520+
pylong_fromnativebytes as fromnativebytes,
521+
SIZE_MAX,
522+
)
520523

521524
# Abbreviate sizeof(Py_ssize_t) to SZ because we use it a lot
522525
SZ = int(math.ceil(math.log(SIZE_MAX + 1) / math.log(2)) / 8)
@@ -534,14 +537,14 @@ def test_long_frombits(self):
534537
n = len(v_be)
535538
v_le = v_be[::-1]
536539

537-
self.assertEqual(expect_s, frombits(v_be, n, 0, 1),
538-
f"PyLong_FromBits(buffer, {n}, <big>)")
539-
self.assertEqual(expect_s, frombits(v_le, n, 1, 1),
540-
f"PyLong_FromBits(buffer, {n}, <little>)")
541-
self.assertEqual(expect_u, frombits(v_be, n, 0, 0),
542-
f"PyLong_FromUnsignedBits(buffer, {n}, <big>)")
543-
self.assertEqual(expect_u, frombits(v_le, n, 1, 0),
544-
f"PyLong_FromUnsignedBits(buffer, {n}, <little>)")
540+
self.assertEqual(expect_s, fromnativebytes(v_be, n, 0, 1),
541+
f"PyLong_FromNativeBytes(buffer, {n}, <big>)")
542+
self.assertEqual(expect_s, fromnativebytes(v_le, n, 1, 1),
543+
f"PyLong_FromNativeBytes(buffer, {n}, <little>)")
544+
self.assertEqual(expect_u, fromnativebytes(v_be, n, 0, 0),
545+
f"PyLong_FromUnsignedNativeBytes(buffer, {n}, <big>)")
546+
self.assertEqual(expect_u, fromnativebytes(v_le, n, 1, 0),
547+
f"PyLong_FromUnsignedNativeBytes(buffer, {n}, <little>)")
545548

546549
if __name__ == "__main__":
547550
unittest.main()

‎Misc/NEWS.d/next/C API/2024-02-05-17-11-15.gh-issue-111140.WMEjid.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Adds :c:func:`PyLong_AsNativeBytes`, :c:func:`PyLong_FromNativeBytes` and
2+
:c:func:`PyLong_FromUnsignedNativeBytes` functions.

‎Misc/NEWS.d/next/Core and Builtins/2024-02-05-17-11-15.gh-issue-111140.WMEjid.rst

Lines changed: 0 additions & 2 deletions
This file was deleted.

‎Modules/_testcapi/long.c

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -777,7 +777,7 @@ pylong_asvoidptr(PyObject *module, PyObject *arg)
777777
}
778778

779779
static PyObject *
780-
pylong_copybits(PyObject *module, PyObject *args)
780+
pylong_asnativebytes(PyObject *module, PyObject *args)
781781
{
782782
PyObject *v;
783783
Py_buffer buffer;
@@ -795,13 +795,13 @@ pylong_copybits(PyObject *module, PyObject *args)
795795
PyBuffer_Release(&buffer);
796796
return NULL;
797797
}
798-
int res = PyLong_CopyBits(v, buffer.buf, n, (int)endianness);
798+
int res = PyLong_AsNativeBytes(v, buffer.buf, n, (int)endianness);
799799
PyBuffer_Release(&buffer);
800800
return res >= 0 ? PyLong_FromLong(res) : NULL;
801801
}
802802

803803
static PyObject *
804-
pylong_frombits(PyObject *module, PyObject *args)
804+
pylong_fromnativebytes(PyObject *module, PyObject *args)
805805
{
806806
Py_buffer buffer;
807807
Py_ssize_t n, endianness, signed_;
@@ -814,8 +814,8 @@ pylong_frombits(PyObject *module, PyObject *args)
814814
return NULL;
815815
}
816816
PyObject *res = signed_
817-
? PyLong_FromBits(buffer.buf, n, (int)endianness)
818-
: PyLong_FromUnsignedBits(buffer.buf, n, (int)endianness);
817+
? PyLong_FromNativeBytes(buffer.buf, n, (int)endianness)
818+
: PyLong_FromUnsignedNativeBytes(buffer.buf, n, (int)endianness);
819819
PyBuffer_Release(&buffer);
820820
return res;
821821
}
@@ -849,8 +849,8 @@ static PyMethodDef test_methods[] = {
849849
{"pylong_as_size_t", pylong_as_size_t, METH_O},
850850
{"pylong_asdouble", pylong_asdouble, METH_O},
851851
{"pylong_asvoidptr", pylong_asvoidptr, METH_O},
852-
{"pylong_copybits", pylong_copybits, METH_VARARGS},
853-
{"pylong_frombits", pylong_frombits, METH_VARARGS},
852+
{"pylong_asnativebytes", pylong_asnativebytes, METH_VARARGS},
853+
{"pylong_fromnativebytes", pylong_fromnativebytes, METH_VARARGS},
854854
{NULL},
855855
};
856856

‎Objects/longobject.c

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -971,9 +971,9 @@ _PyLong_AsByteArray(PyLongObject* v,
971971
It's crucial that every Python digit except for the MSD contribute
972972
exactly PyLong_SHIFT bits to the total, so first assert that the int is
973973
normalized.
974-
NOTE: PyLong_CopyBits() assumes that this function will fill in 'n' bytes
975-
even if it eventually fails to convert the whole number. Make sure you
976-
account for that if you are changing this algorithm to return without
974+
NOTE: PyLong_AsNativeBytes() assumes that this function will fill in 'n'
975+
bytes even if it eventually fails to convert the whole number. Make sure
976+
you account for that if you are changing this algorithm to return without
977977
doing that.
978978
*/
979979
assert(ndigits == 0 || v->long_value.ob_digit[ndigits - 1] != 0);
@@ -1081,7 +1081,7 @@ _fits_in_n_bits(Py_ssize_t v, Py_ssize_t n)
10811081
}
10821082

10831083
int
1084-
PyLong_CopyBits(PyObject* vv, void* buffer, size_t n, int endianness)
1084+
PyLong_AsNativeBytes(PyObject* vv, void* buffer, size_t n, int endianness)
10851085
{
10861086
PyLongObject *v;
10871087
union {
@@ -1097,7 +1097,7 @@ PyLong_CopyBits(PyObject* vv, void* buffer, size_t n, int endianness)
10971097
}
10981098

10991099
if ((size_t)(int)n != n || (int)n < 0) {
1100-
PyErr_SetString(PyExc_SystemError, "n_bytes too big to copy");
1100+
PyErr_SetString(PyExc_SystemError, "n_bytes too big to convert");
11011101
return -1;
11021102
}
11031103

@@ -1218,7 +1218,7 @@ PyLong_CopyBits(PyObject* vv, void* buffer, size_t n, int endianness)
12181218

12191219

12201220
PyObject *
1221-
PyLong_FromBits(const void* buffer, size_t n, int endianness)
1221+
PyLong_FromNativeBytes(const void* buffer, size_t n, int endianness)
12221222
{
12231223
if (!buffer) {
12241224
PyErr_BadInternalCall();
@@ -1240,7 +1240,7 @@ PyLong_FromBits(const void* buffer, size_t n, int endianness)
12401240

12411241

12421242
PyObject *
1243-
PyLong_FromUnsignedBits(const void* buffer, size_t n, int endianness)
1243+
PyLong_FromUnsignedNativeBytes(const void* buffer, size_t n, int endianness)
12441244
{
12451245
if (!buffer) {
12461246
PyErr_BadInternalCall();

0 commit comments

Comments
 (0)