Add `PyObject_GetItemData()` and `PyObject_GetItemData_DuringGC()` to the stable ABI

[vstinner]

Functions requested by @wjakob who works on nanobind. Copy/paste of PR python/cpython#148324 description.

---

This PR promotes PyObject_GetItemData() and PyObject_GetItemData_DuringGC() to the stable ABI (analogous to PyObject_GetTypeData() and PyObject_GetTypeData_DuringGC() that are already in the stable ABI).

The function PyObject_GetItemData() is needed to access the entries of variable sized objects (PyVarObject).

Why this change?

• PyVarObject becomes opaque in abi3t.
• nanobind (used by large-scale ML and compiler projects like Google's JAX, Apple's MLX, LLVM, MLIR, ...) uses a variable sized function object
• Ergo: without access to PyObject_GetItemData(), nanobind cannot run on abi3t.

---

The function was added by PEP 697 "Limited C API for Extending Opaque Types" to Python 3.12. The function is documented and tested (by test_capi.test_misc). IMO it makes sense to add it to the stable ABI. Without this function, it's not possible to access data of PyVarObject objects in the stable ABI.

Vote:

• @encukou (-1)
• @erlend-aasland
• @serhiy-storchaka
• @vstinner
• @zooba

[encukou]

I don't think these functions are useful without a way to define PyVarObject-based types in abi3t.

[zooba]

Is there a scenario where we might allow direct access to items in a type that you didn't define? (Genuine question, I'm not up to speed on using these APIs right now.) If it's really like GetTypeData then I'd assume not.

Are there types we provide that require callers to use GetItemData (or else a generic API like PyObject_GetItem)?

This request is a reasonable one, but it's deliberately pushing on our boundary of stability for the stable ABI so we're allowed to push back and say "for stability you need to use a slower API here; if you can't afford the slower API then use the unstable ABI".

[encukou]

Is there a scenario where we might allow direct access to items in a type that you didn't define?

Yes. But, in that case the defining type needs to provide API for that. (And if that API comes with longer-term ABI stability guarantees, you'll want to provide the equivalent of PyTuple_GetItem rather than give out a contiguous buffer that the receiver picks apart.)

[zooba]

in that case the defining type needs to provide API for that

That's what I assumed.

I think we should explicitly define PyVarObject as excluded from the stable ABI, and recommend implementers who need the stability should implement their own variable length allocator (with whatever additional indirection that entails).

[wjakob]

A comment to this thread and @zooba's message on the discussion forum.

[..] that will help avoid the message we keep hearing that we need to provide 100% speed, 100% flexibility and 100% stability all at once. It’s taken years, but we’ve landed on a stable option and a fast/flexible option, but you can’t have them both at once.

My 2cts would be that the stable ABI is already at a point where it enables both speed and stability. I have been working towards this end, by

• adding the vector call functions to the limited API: Add vector call functions to the limited API python/cpython#98586 (merged in Python 3.12).
• requesting a way to receive vector calls in the limited API: Receiving vector calls in the Py_LIMITED_API python/cpython#93274 (implemented by @encukou , merged in Python 3.12)
• adding an limited API function to instantiate classes with custom metaclasses: gh-60074: add new stable API function PyType_FromMetaclass python/cpython#93012 (merged in Python 3.12)

With these changes, it became possible to build fast C++ wheels when targeting the Python 3.12 stable ABI, which I find incredibly exciting.

The new free-threaded stable ABI design now breaks my binding library. But I want to emphasize that this is a quite isolated technical issue, and that the gulf between "fast" and "forward-compatible" is not as big as these comments make them sound.

If PyVarObject is explicitly excluded from the stable ABI (which I can totally get on board on, it seems like somewhat of a relic), then the other way to resolve it is by "blessing" PyUnstable_Object_GC_NewWithExtraData() and promoting this to the limited API.

The ability to allocate a Python object with some extra scratch space does not seem like such an outlandish thing, and it enables everyone else to design their own variable sized objects in extensions. I find this direction prettier than having to deal with PyVarObject that is entangled with Py_SIZE(), Py_SET_SIZE() -- better to leave how the size is stored completely up to the user.

[zooba]

The ability to allocate a Python object with some extra scratch space does not seem like such an outlandish thing, and it enables everyone else to design their own variable sized objects in extensions.

Yeah, I agree with this. Do we not have a slot to specify extra object space when creating a new type? That's probably where it should go.

[encukou]

The ability to allocate a Python object with some extra scratch space does not seem like such an outlandish thing, and it enables everyone else to design their own variable sized objects in extensions. I find this direction prettier than having to deal with PyVarObject that is entangled with Py_SIZE(), Py_SET_SIZE() -- better to leave how the size is stored completely up to the user.

Yes!
GUPOL does that (in my interpretation at least), and I want to turn it into a PEP for 3.16.
I do not want to bless the current crutch. The reason PyUnstable_Object_GC_NewWithExtraData was added as unstable is because it depends too much on the current object layout.

[wjakob]

Yeah, I agree with this. Do we not have a slot to specify extra object space when creating a new type? That's probably where it should go.

One can specify the tp_basicsize when allocating a new type. The lost feature discussed here is the ability to have one type (e.g. a tuple-like object) and then request allocations with varying sizes. (E.g. please allocate a Python object of type MyTuple and ensure that are N bytes of payload for this particular tuple instance). This was possible in abi3 but is now disappearing in abi3t.

I've opened a separate issue and PR for the alternative direction of promoting PyUnstable_Object_GC_NewWithExtraData() to a stable API function named PyObject_GC_NewWithExtraData(). See issue python/cpython#148498, PR python/cpython#148499

[encukou]

The new free-threaded stable ABI design now breaks my binding library.

It prevents you from adding the feature to the library.

This was possible in abi3 but is now disappearing in abi3t.

It was not in abi3t to begin with.

---

Except not! The use case does have a replacement -- separate allocation & pointer chasing. Yes, this is slower. But isn't it the same situation as PEP-697 replacing pointer+offset memory access with PyObject_GetTypeData?

We can solve both speed issues, in 3.16.