gh-142518: Document thread-safety guarantees of list operations

[lysnikolaou]

I'm opening this to start a discussion on what we want the structure of such documentation to be, as well as how to balance detail with succinctness. Feedback very welcome!

• Issue: Document guarantees provided when sharing built-in types across threads #142518

---

📚 Documentation preview 📚: https://cpython-previews--142519.org.readthedocs.build/en/142519/library/stdtypes.html#lists

[emmatyping]

Merged main to fix CI

[emmatyping]

I think any note about the atomicity of list operations should probably go after the documentation about the type. I can imagine a beginner to Python going to the documentation to read about lists and being confused about what free-threading semantics are talking about.

I also wonder if this should not be a note. Perhaps it would be better to describe as part of the type description what operations are atomic and which are not?

[hugovk]

Less horizontal scrolling on mobile:

Suggested change

	lst.append(item) # atomically appends item
	lst.pop() # atomically removes and returns last item
	lst[i] = value # atomically replaces item at index i
	item = lst[i] # atomically retrieves item at index i
	lst.append(item) # atomically appends item
	lst.pop() # atomically removes and returns last item
	lst[i] = value # atomically replaces item at index i
	item = lst[i] # atomically retrieves item at index i