[C API] Add PyLong_FromInt64() and PyLong_ToInt64()

[vstinner]

Feature or enhancement

I propose to add functions to convert <stdint.h> integers to/from Python int objects:

PyObject* PyLong_FromInt32(int32_t value);
PyObject* PyLong_FromInt64(int64_t value);
PyObject* PyLong_FromUInt32(uint32_t value);
PyObject* PyLong_FromUInt64(uint64_t value);

int PyLong_ToInt32(PyObject *obj, int32_t *value);
int PyLong_ToInt64(PyObject *obj, int64_t *value);
int PyLong_ToUInt32(PyObject *obj, uint32_t *value);
int PyLong_ToUInt64(PyObject *obj, uint64_t *value);

Notes:

• I prefer to limit the API to 4 types for now: int32/64_t and uint32/64_t. Later, we can discuss add more types, but let's start with the most common ones. (UPDATE: I removed 8-bit and 16-bit types.)
• I prefer UInt to Uint since there are two words: Unsigned INTeger.
• To functions don't return the result, but a status: 0 on success, -1 on error (with an exception set). It's to solve the C API Problem #1: "Ambiguous return values". PyLong_AsLong() returns -1 on success and on error (with an exception set).

Related discussion: Avoid C-specific Types.

Linked PRs

• gh-120389: Add PyLong_FromInt64() and PyLong_AsInt64() #120390

[vstinner]

cc @encukou @serhiy-storchaka

[vstinner]

See also #117031 and #117032: "Support more integer types in PyMemberDef".

Add support for standard C and Posix integer types like Py_T_UINT32, Py_T_PTRDIFF, Py_T_OFF and Py_T_PID.
Add Py_T_SSIZE as alias of Py_T_PYSSIZET.

[serhiy-storchaka]

This conflicts with the interface of other PyLong_As* functions. If you want to use different convention, it is better to use different names.

There are some design questions:

• Should all these functions be separate functions or aliases of other functions with the same size and signness?
• Which functions should call __index__() (and therefore release the GIL) and which should be PyLong only?
• How to handle negative values for unsigned types?
• How to handle overflow?
• It is worth to make these function compatible with the O& format unit in PyArg_Parse -- returning 1 for success and 0 for failure.

See also #117031.

[vstinner]

This conflicts with the interface of other PyLong_As* functions. If you want to use different convention, it is better to use different names.

We can use PyLong_To*() convention. What do you think?

How to handle negative values for unsigned types?

They must fail with ValueError (or OverflowError).

How to handle overflow?

Raise a OverflowError.

It is worth to make these function compatible with the O& format unit in PyArg_Parse -- returning 1 for success and 0 for failure.

New API should follow new guidelines: 0 on success, -1 on error: https://devguide.python.org/developer-workflow/c-api/index.html#guidelines-for-expanding-changing-the-public-api

[GalaxySnail]

• I prefer UInt to Uint since there are two words: Unsigned INTeger.

bikeshedding: We have PyLong_AsSsize_t instead of PyLong_AsSSize_t for ssize_t/Py_ssize_t, so I personally prefer Uint to UInt because of consistency.

[serhiy-storchaka]

We can use PyLong_To*() convention. What do you think?

I was going to suggest the same. Or include Convert in the name.

New API should follow new guidelines: 0 on success, -1 on error: https://devguide.python.org/developer-workflow/c-api/index.html#guidelines-for-expanding-changing-the-public-api

Then we will end with two sets of functions with the same signature, but opposite meaning of the returned value. I am going to propose to make PyArg_Parse-compatible converters public.

[vstinner]

I renamed the functions to PyLong_ToInt64() and PyLong_ToUInt64().

[vstinner]

@serhiy-storchaka:

There are some design questions: (...)

You can now check #120390 implementation, especially the test suite, to get answers to your questions.

[vstinner]

I created capi-workgroup/decisions#32 "Add PyLong_FromInt64() and PyLong_ToInt64()" in the C API WG Decisions project.