gh-121403: Add notes for PyList_GetXXX APIs about the need for init

[corona10]

• Issue: Calling PyList_GetItemRef after PyList_New segfaults #121403

---

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

[corona10]

I am not sure if we have to add notes to all list-related APIs, but for me, this note looks more straightforward from the user side.

[vstinner]

I would prefer to only add a note to PyList_New() instead.

[colesbury]

I would prefer to only add a note to PyList_New() instead.

Yeah, I was going to suggest the same thing.

[corona10]

@vstinner cc @colesbury

Victor, if you are thinking about the comment that you wrote before. #121403 (comment)
So, how can we list all available APIs even if the list is not fully initialized?
Let's just mention that PyList_SetItem() and PyList_SET_ITEM are safe to use?
How about PyList_Clear()? It just call XDECREF internally, so it can be called even if the list is not fully initialized.
Do we have to except such APIs?

[vstinner]

I suggest to say that only PyList_SET_ITEM() is safe to call before the list is fully initialized.

[colesbury]

PyList_SET_ITEM is not part of the limited API, right? I think we also have to include PyList_SetItem so that users of the limited API can safely initialize a list created by PyList_New().

[vstinner]

The list is not rendered properly. Maybe just write: "The following ...: PyList_SetItem and PyList_SET_ITEM."

[vstinner]

Rendered doc: https://cpython-previews--121626.org.readthedocs.build/en/121626/c-api/list.html

[vstinner]

LGTM

[corona10]

Waiting @colesbury, who is the best English speaker in this place :)

[miss-islington-app]

Thanks @corona10 for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

[bedevere-app]

GH-121827 is a backport of this pull request to the 3.13 branch.

[lysnikolaou]

Sorry for missing this PR while it was still open. I don't think this makes it clear enough that these are the only APIs that can be used before a list is fully initialized. Maybe something like this would be better?

Suggested change

	:c:func:`PyList_SET_ITEM()`. The following APIs are safe APIs before
	the list is fully initialized: :c:func:`PyList_SetItem()` and :c:func:`PyList_SET_ITEM()`.
	:c:func:`PyList_SET_ITEM()`. The following APIs are the only safe APIs to use before
	the list is fully initialized: :c:func:`PyList_SetItem()` and :c:func:`PyList_SET_ITEM()`.