gh-114329: Add PyList_GetItemRef function

[colesbury]

The new PyList_GetItemRef is similar to PyList_GetItem, but returns a strong reference instead of a borrowed reference. Additionally, if the passed "list" object is not a list, the function sets a TypeError instead of calling PyErr_BadInternalCall().

• Issue: Add PyList_GetItemRef, a variant of PyList_GetItem that returns a strong reference #114329

---

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

[vstinner]

Additionally, if the passed "list" object is not a list, the function sets a TypeError instead of calling PyErr_BadInternalCall().

When I proposed such change, @serhiy-storchaka asked me to stick to RuntimeError, but I don't recall why :-D @serhiy-storchaka, do you prefer RuntimeError or TypeError?

[vstinner]

I suggest to make this function the new reference, and document PyList_GetItem() as: "Similar to PyList_GetItemRef(), but return a borrowed reference".

[vstinner]

Can you share most code between test_list_get_item() and test_list_get_item_ref()?

[serhiy-storchaka]

Move it to the end of the file.

[serhiy-storchaka]

When I proposed such change, @serhiy-storchaka asked me to stick to RuntimeError, but I don't recall why :-D @serhiy-storchaka, do you prefer RuntimeError or TypeError?

Is it RuntimeError or SystemError?

The only discussed difference was returning a strong reference instead of a weak reference. If we want to change also the exception type, it should be a separate discussion.

Most concrete type C API raises SystemError if they are called with wrong type. It is considered a programming error, not a data error.

[vstinner]

Most concrete type C API raises SystemError if they are called with wrong type. It is considered a programming error, not a data error.

I suggest to document that the function "parameter must be list" , without mentioning the exact exception type.

[colesbury]

Most concrete type C API raises SystemError if they are called with wrong type. It is considered a programming error, not a data error.

The TypeError behavior is explicitly stated in the C API WG discussion of this API. See also capi-workgroup/api-evolution#29 (comment) and PyWeakref_GetRef().

[colesbury]

I've removed the sentence mentioning TypeError from the PyList_GetItemRef documentation. I don't think saying that "parameter must be list" without describing the error return is helpful. That merely states the obvious and risks being confusing: it raises the question of why, out of all the functions that must take a list, only this one says "parameter must be list".

[vstinner]

LGTM.

The TypeError behavior is explicitly stated in the C API WG capi-workgroup/decisions#9 (comment). See also capi-workgroup/api-evolution#29 (comment) and PyWeakref_GetRef().

Oh ok, I didn't notice that TypeError was explicitly mentioned.

[corona10]

LGTM too.

I will merge the PR if @serhiy-storchaka approve.

[encukou]

If the WG does discuss the exception type, it'll take some time.
Let's merge this, the type can be changed later