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?

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.

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.

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().

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".