[docs] Mention how to get/set a bigint PyLong via the C API

[gpshead]

There isn't enough demand for a direct C API to get or set a binary byte array bigint representation of PyLong but we do want the people who need to understand how they can do that.

Background: https://discuss.python.org/t/add-portable-way-to-extract-all-digits-of-a-pylongobject-from-c/20045

[CAM-Gerlach]

Thanks. Two high-level comments:

• Given how this is rendered, as a small normal prose paragraph kinda buried at the end of a long list of APIs, it seems rather hard to find and easy to miss. I would suggest using the standard .. see-also:: directive to style it appropriately, and move it to the end of the top-level description on line 15.

• Additionally, until I looked at the linked thread, I didn't immediately grasp the actual significance of this from the wording here—that int.to_bytes is the (only supported) way to get the full bigint value of a PyLongObject, and int.from_bytes the (only supported) way to roundtrip an arbitrarily-long bigint value back into a PyLongObject. Rather, at least to me (as a decidedly non-expert), it just sounded like a way to convert a PyLongObject to/from one particular representation of many. Therefore, I would suggest explicitly mentioning this for the reader.

To address both of those, I suggest moving this to line 15, with something like the following text (I can't make it as a GitHub suggestion, though I could commit it to your branch, if desired):

.. seealso:: Python methods :meth:`int.to_bytes` and :meth:`int.from_bytes`
   (called via one of the :c:func:`PyObject_CallMethod` C APIs),
   to convert a :c:type:`PyLongObject` of arbitrary size
   to or from an array of bytes.

[CAM-Gerlach]

Also, is there a particular reason not to backport this to 3.10 as well? As far as I can tell, none of the referenced APIs have changed significantly since that version, and general docs policy (AFAIK) is to backport docs changes that aren't specific to any version to all bugfix-supported versions, to maximize benefit and minimize merge conflicts for future backports.

[CAM-Gerlach]

One small suggested tweak to my previous wording, otherwise LGTM. Thanks @gpshead !

[gpshead]

thanks, exactly the kind of docs feedback I needed. I'm trying it out moved down next to PyLong_FromString as that is the API it most resembles. With an explicit note of to/from bytes meaning base 256. the seealso at top looked a little too prominent and disconnected from other things.

[miss-islington]

Thanks @gpshead for the PR 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11.
🐍🍒⛏🤖

[bedevere-bot]

GH-101275 is a backport of this pull request to the 3.11 branch.

[bedevere-bot]

GH-101276 is a backport of this pull request to the 3.10 branch.

[CAM-Gerlach]

I'm trying it out moved down next to PyLong_FromString as that is the API it most resembles.

I put some thought toward proposing splitting the SeeAlso to having the from one under FromString and the to one under the most relevant to As function(s), perhaps PyLong_AsLongLongAndOverflow, to not draw too much attention to them while making them most proximate to the places users would likely go looking. I ended up not doing so as I was concerned users just skimming the functions for any that were relevant might not notice it, and there wasn't a single obvious candidate for the As/to side of it.

It's certainly a valid approach nonetheless, but the problem with the current implementation is that both the to and from methods are both listed under a from function, and nothing is listed under and of the As functions, thus users looking in that direction may never find it. This would seem to neglect the most probable and necessary use case, the one highlighted in the thread—needing to get the value of a bigint bigger than a long long—to which the current exposed APIs don't offer anything at all comparable (unlike FromString in the other direction, as you mention).