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

[lysnikolaou]

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

---

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

[picnixz]

I

Suggested change

	.. admonition:: Thread safety
	.. _thread-safety-dict:
	.. rubric:: Thread safety for dict objects

Admonition will create a big box which will not be good considering the size of the text. A rubric is like a title but without being it in the sidebar and a label allows us to link it.

Alternatively we can have a real section.

[lysnikolaou]

Consistency with list is a tiny bit more important here, I feel. Especially since we're planning to migrate all of this content into a new page.

[picnixz]

I'd say that it is still wrong to have an admonition, especially considering how it is rendered online (it is, to me, disruptive to have a huge wall of text with borders and a colored background).

[lysnikolaou]

I tend to agree about the HTML rendering. Maybe removing it from list as well makes the most sense then?

[picnixz]

Yes

[lysnikolaou]

Opened #144548 for list and I'll do it here as well.

[lysnikolaou]

Could we have some more reviews on the content here?

cc @encukou if you have some spare cycles

[encukou]

Would it make sense to define “lock-free”? (And/or “per-object lock”?)
Like “thread-safe” and “atomic”, I kinda know what that means, but if this was underlined I'd click through to read the definition.

[lysnikolaou]

Yes, good idea! Opened #144548 for it.