From b661e0ee7ee0f12edc61f457b109c4c1939491a9 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Mon, 23 Jan 2023 14:43:21 -0800 Subject: [PATCH 1/5] Mention how to get a bigint PyLong in C. We don't need direct C APIs to get at a bigint representation of PyLong but we do want the few people who need to understand how. --- Doc/c-api/long.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index 4f6f865db8be13..93ff9491c862cc 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -318,3 +318,9 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. with :c:func:`PyLong_FromVoidPtr`. Returns ``NULL`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. + + +If you want to convert to or from a binary big integer array of bytes +representation, call the Python :meth:`int.to_bytes` or :meth:`int.from_bytes` +methods using one of the :func:`PyObject_CallMethod` C APIs. + From 3db2aadfd78f36f88fb8ab65dee7afb03585790b Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Mon, 23 Jan 2023 14:57:32 -0800 Subject: [PATCH 2/5] proper ReST tag for a C function. --- Doc/c-api/long.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index 93ff9491c862cc..4af5b763278e64 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -322,5 +322,5 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. If you want to convert to or from a binary big integer array of bytes representation, call the Python :meth:`int.to_bytes` or :meth:`int.from_bytes` -methods using one of the :func:`PyObject_CallMethod` C APIs. +methods using one of the :c:func:`PyObject_CallMethod` C APIs. From 4ad00ed5f1a9dbb7ed736cb7d30911f7a9dc006a Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Mon, 23 Jan 2023 20:09:40 -0800 Subject: [PATCH 3/5] CAM's rewording and placement. --- Doc/c-api/long.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index 4af5b763278e64..c388a8a0a216af 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -13,6 +13,11 @@ All integers are implemented as "long" integer objects of arbitrary size. On error, most ``PyLong_As*`` APIs return ``(return type)-1`` which cannot be distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. +.. seealso:: Python methods :meth:`int.to_bytes` and :meth:`int.from_bytes` + (called via one of the :c:func:`PyObject_CallMethod` APIs), + to convert a :c:type:`PyLongObject` of arbitrary size + to or from an array of bytes. + .. c:type:: PyLongObject This subtype of :c:type:`PyObject` represents a Python integer object. @@ -318,9 +323,3 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. with :c:func:`PyLong_FromVoidPtr`. Returns ``NULL`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. - - -If you want to convert to or from a binary big integer array of bytes -representation, call the Python :meth:`int.to_bytes` or :meth:`int.from_bytes` -methods using one of the :c:func:`PyObject_CallMethod` C APIs. - From 2e5b2cc1e1b25d0a382ddd6a583a11969e570e21 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Mon, 23 Jan 2023 21:09:38 -0800 Subject: [PATCH 4/5] move the seealso down near FromString --- Doc/c-api/long.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index c388a8a0a216af..7b453a3e2df666 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -13,11 +13,6 @@ All integers are implemented as "long" integer objects of arbitrary size. On error, most ``PyLong_As*`` APIs return ``(return type)-1`` which cannot be distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. -.. seealso:: Python methods :meth:`int.to_bytes` and :meth:`int.from_bytes` - (called via one of the :c:func:`PyObject_CallMethod` APIs), - to convert a :c:type:`PyLongObject` of arbitrary size - to or from an array of bytes. - .. c:type:: PyLongObject This subtype of :c:type:`PyObject` represents a Python integer object. @@ -99,6 +94,10 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. ignored. If there are no digits or *str* is not NULL-terminated following the digits and trailing whitespace, :exc:`ValueError` will be raised. + .. seealso:: Python methods :meth:`int.to_bytes` and :meth:`int.from_bytes` + to convert a :c:type:`PyLongObject` to or from an array of bytes in base + ``256``. You can call those from C using :c:func:`PyObject_CallMethod`. + .. c:function:: PyObject* PyLong_FromUnicodeObject(PyObject *u, int base) From 43482798b177cf6e611049662da54f82ef9a6343 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Mon, 23 Jan 2023 21:10:33 -0800 Subject: [PATCH 5/5] or -> / --- Doc/c-api/long.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index 7b453a3e2df666..41b5632d23003f 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -95,7 +95,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. digits and trailing whitespace, :exc:`ValueError` will be raised. .. seealso:: Python methods :meth:`int.to_bytes` and :meth:`int.from_bytes` - to convert a :c:type:`PyLongObject` to or from an array of bytes in base + to convert a :c:type:`PyLongObject` to/from an array of bytes in base ``256``. You can call those from C using :c:func:`PyObject_CallMethod`.