Make `_PyTuple_FromArraySteal()` public: how should it be named?

[vstinner]

Hi,

I would like to make the _PyTuple_FromArraySteal() function public since it's efficient and useful. Problem: there is a disagreement on how to name this function. In 2023, the Terminology for managing ownership discussion proposed different terms and function names, but no agreement was reached.

The two main competitors are Steal and Move which give the function names PyTuple_FromArraySteal() or PyTuple_MoveFromArray(). Guido and Petr like Steal, I prefer Move. What others think about these terms?

Rust and C++ (std::move) use the term Move.

---

Vote for Steal term:

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

Vote for another term such as Move, please comment with your preferred term:

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

Victor

[encukou]

My reason for Steal is that it's unambiguously about refcounting. Move sounds too much like memmove or C++'s std::move which is are a different concept.
Rust does call this move, but it's much more of a core concept in the language.
(And for an exception to the guidelines, the negative connotation of steal is appropriate...)

In docs I'd prefer to spell out take ownership/transfer ownership, but that's too long for function names.

[davidhewitt]

I would support "steal" here, it's already a term we see in the documentation in other places I think?

In Rust (and I think C++) moves the whole container gets moved into the API but that's not really the case here. If you have allocated an array, you'll still need to carefully deallocate it once the object references have been consumed by this new API.

[vstinner]

Move sounds too much like memmove or C++'s std::move which is are a different concept.

FYI In my previous attempt, I tried to implement _PyTuple_FromArraySteal() by modifying the input array to clear items (set them to NULL), but it didn't go well. Existing code using the private _PyTuple_FromArraySteal() function expects that the input array remains unchanged and still valid after the call.

So you're right that the concept is different here.

[vstinner]

I would support "steal" here, it's already a term we see in the documentation in other places I think?

The term "steal" is not used currently in the public C API (in function names), but you're correct that it's used here and there in the documentation. Examples:

• PyErr_SetRaisedException(): This call steals a reference to exc, which must be a valid exception.
• PyException_SetContext(): This steals a reference to ctx.
• PyTuple_SetItem(): This function "steals" a reference to o and (...).
• PyObject_SetItem(): This function does not steal a reference to v.
• PyModule_Add(): Similar to PyModule_AddObjectRef() but steal a reference to 'value'.
• PyModule_AddObject(): Similar to PyModule_AddObjectRef() and PyModule_Add() but steal a reference to 'value' on success and only on success.

By the way, the term steal is not documeted itself. We might document it as we did for borrowed reference and strong reference.

[serhiy-storchaka]

I am not sure that we need such function in the public API at first place. This is just a microoptimization that saves few nanoseconds.

BTW, Py_BuildValue("N") also steals its argument.

[vstinner]

I am not sure that we need such function in the public API at first place. This is just a microoptimization that saves few nanoseconds.

This issue is only about the term for adding new functions taking ownership. I plan to open a new issue for _PyTuple_FromArraySteal() once we decide on the term. I will expose the rationale for adding such function there ;-)

[zooba]

I'm with Serhiy - this is such a small optimization that only matters for microbenchmarks, and doesn't really open up interesting ways to define a list without using the Python APIs. (By contrast, a PyList_FromUtf8Array(size_t n, const char **strings) would be interesting, because you can fully create that array outside the GIL and then construct the list inside of it.)

It also creates complicated failure scenarios, because now we have to decide how we're handling objects that have already been "stolen" and objects that haven't been stolen yet when we fail halfway through the array. With a non-stealing API, we can safely decref all the ones we've taken so far without worrying about initiating finalizers or similar, but in this case, we probably have to un-steal them and make the caller safely clean everything up.

On naming, we use "steal" and should stick with it. But I'd rather just leave this private until someone shows that it's genuinely their bottleneck. I'm highly skeptical that it would be.

[erlend-aasland]

Wrt. naming, I'm fine with "steal"¹; it's a term that is (should be) well known for most users of our C API.

Since this issue is strictly about the API naming, I don't have any other comments at the moment.

Footnotes

1. yes, I changed my mind since last time we had this discussion ↩

[vstinner]

Update: Oops, _PyList_FromArraySteal() doesn't exist, we're talking about _PyTuple_FromArraySteal() in fact.

[vstinner]

Ok so there is a strong preference for the Steal term, but @serhiy-storchaka and @zooba are against adding a _PyTuple_FromArraySteal() function since they consider that there is no performance benefits.

That's enough for me, I close the issue. Thanks for your participation :-)