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

lysnikolaou · 2026-01-23T16:31:15Z

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

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

picnixz · 2026-01-24T02:34:37Z

Doc/library/stdtypes.rst

   .. versionchanged:: 3.8
      Dictionaries are now reversible.

+.. admonition:: Thread safety


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.

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.

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).

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

Doc/library/stdtypes.rst

lysnikolaou · 2026-01-30T13:27:47Z

Could we have some more reviews on the content here?

cc @encukou if you have some spare cycles

encukou · 2026-02-02T14:06:28Z

Doc/library/stdtypes.rst

+   argument is a :class:`dict`, :class:`tuple`, :class:`set` or
+   :class:`frozenset`.
+
+   The following operations and function are lock-free and


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.

encukou · 2026-02-02T14:08:19Z

Doc/library/stdtypes.rst

+   execute arbitrary Python code.  During such comparisons, the dictionary may
+   be modified by another thread.  For built-in types like :class:`str`,
+   :class:`int`, and :class:`float`, that implement :meth:`~object.__eq__` in C,
+   the underlying lock is not released during comparisons and this is not a


An “underlying lock” in lock-free operations is rather confusing.

encukou · 2026-02-02T14:13:28Z

Doc/library/stdtypes.rst

+   considerations as above apply.
+
+   The following operations return new objects and hold the per-object lock
+   for the duration:


Suggested change

for the duration:

for the duration of the operation:

encukou · 2026-02-02T14:14:38Z

Doc/library/stdtypes.rst

+   The equality comparison also compares values using :meth:`~object.__eq__`,
+   so for non-built-in types the lock may be released during comparison.


This goes for != as well, right? I'd either add a small hint:

Suggested change

The equality comparison also compares values using :meth:`~object.__eq__`,

so for non-built-in types the lock may be released during comparison.

The equality comparisons also compare values using :meth:`~object.__eq__`,

so for non-built-in types the lock may be released during comparison.

Or spell it out:

Suggested change

The equality comparison also compares values using :meth:`~object.__eq__`,

so for non-built-in types the lock may be released during comparison.

The equality and inequality comparison also compares values using

:meth:`~object.__eq__`, so for non-built-in types the lock may be released

during comparison.

encukou · 2026-02-02T14:20:38Z

Doc/library/stdtypes.rst

+      d.update(iterable)        # iterable is not a dict
+      d |= iterable             # iterable is not a dict
+      dict.fromkeys(iterable)   # iterable is not a dict/set/frozenset


This seems to rely too much on the :class: maybe. (The red/green distinction is completely invisible to colourblind people, not to mention screen reader users.)

Suggested change

d.update(iterable) # iterable is not a dict

d |= iterable # iterable is not a dict

dict.fromkeys(iterable) # iterable is not a dict/set/frozenset

d.update(iterable) # iterable is not a dict: only d locked

d |= iterable # iterable is not a dict: only d locked

dict.fromkeys(iterable) # iterable is not a dict/set/frozenset: only result locked

lysnikolaou added 2 commits January 23, 2026 17:20

Add dict thread safety docs

d817556

Address feedback

49293fb

bedevere-app bot added docs Documentation in the Doc dir skip news labels Jan 23, 2026

github-project-automation bot added this to Docs PRs Jan 23, 2026

github-project-automation bot moved this to Todo in Docs PRs Jan 23, 2026

bedevere-app bot added the awaiting core review label Jan 23, 2026

bedevere-app bot mentioned this pull request Jan 23, 2026

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

Open

picnixz reviewed Jan 24, 2026

View reviewed changes

Address feedback; move thread safety section below see-also

90cac54

encukou self-requested a review January 30, 2026 13:30

encukou reviewed Feb 2, 2026

View reviewed changes

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

		The equality comparison also compares values using :meth:`~object.__eq__`,
		so for non-built-in types the lock may be released during comparison.

Uh oh!

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

Are you sure you want to change the base?

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

Conversation

lysnikolaou commented Jan 23, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

lysnikolaou commented Jan 30, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lysnikolaou commented Jan 23, 2026 •

edited by github-actions bot

Loading