gh-111140: Improve PyLong_AsNativeBytes API doc example & improve the test

[gpshead]

This expands the examples to cover both realistic use cases for the API.

I noticed thing in the test that could be done better so I added those as well: We need to guarantee that all bytes of the result are overwritten and that too many are not written. Tests now pre-fills the result with data in order to ensure that. (assuming ctypes isn't undoing that behind the scenes...)

---

📚 Documentation preview 📚: https://cpython-previews--115380.org.readthedocs.build/

• Issue: C API: Consider adding public PyLong_AsByteArray() and PyLong_FromByteArray() functions #111140

[zooba]

I disagree with the example change - the intent is certainly to copy directly into simple types, but the difference is that the size of the type is explicit (once things have stabilised a bit I intend to try replacing the implementations of our various typed ones with calls to this function and benchmark).

Perhaps using long would be better, as that more obviously varies between platforms (reliably 32-bit on Windows; pointer-sized on POSIX)?

But this is absolutely a way to provide a single reliable function to replace all the others.

The edge case doesn't come up in the int example because int is signed, and so you would get the failure you expect if the sign bit doesn't fit. An unsigned int example would potentially trigger it, as values in [0x80000000, 0xFFFFFFFF] would fit, but this API will return 5 and so it looks like a failure. But for int, it does exactly the right thing for all values.

The additional test changes are good though. I like those

[zooba]

Alternatively, maybe use int32_t for the example?

[gpshead]

Take another look, I updated it to cover both use cases and try to be more specific.

[zooba]

LGTM with the change noted (I don't mind which way you go with it)