python
gh-142518: Document thread-safety guarantees of list operations
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: gh-142518
📚 Documentation preview 📚: https://cpython-previews--142519.org.readthedocs.build/en/142519/library/stdtypes.html#lists
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?
My general opinion: reference documentation needs to be precise first; complete second. Succinctness comes after that.
Edit: Also, IMO, it's fine to add information first, then reorganize when a better structure becomes more obvious.
I've addressed most of the feedback and added a lot more details.
I also inadvertently force-pushed. Sorry about that.