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

[corona10]

• Issue: gh-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.

[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. https://github.com/python/cpython/issues/121403#issuecomment-2214035566 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().

[corona10]

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

[miss-islington-app[bot]]

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

[bedevere-app[bot]]

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