gh-145254: Add thread safety annotation by lysnikolaou · Pull Request #145255 · python/cpython

lysnikolaou · 2026-02-26T13:35:55Z

Implement annotation for different thread safety levels
Annotate PyMutex_* APIs

Issue: Add thread safety annotations for C API functions #145254

📚 Documentation preview 📚: https://cpython-previews--145255.org.readthedocs.build/en/145255/c-api/synchronization.html#c.PyMutex_Lock

- Implement annotation for different thread safety levels - Annotate PyMutex_* APIs

hugovk · 2026-02-27T15:07:38Z

python/python-docs-theme#297 is merged and released in https://github.com/python/python-docs-theme/releases/tag/2026.2

Fix the lint with uvx prek run --all-files or uvx prek run --all-files ruff-format.

And as a bonus, the docs will rebuild with the new theme.

encukou · 2026-03-04T15:12:46Z

+ refexplicit="True",
+ )
+ prefix = sphinx_gettext("Thread safety:") + " "
+ classes = [f"threadsafety-{level}"]


The CSS requires, as it should, the "threadsafety" class as well as "threadsafety-FOO".
Suggested change
classes= [f"threadsafety-{level}"]
classes= ["threadsafety", f"threadsafety-{level}"]

encukou

Adding some comments.

FWIW, I don't want to step on your toes, but I'd be happy to take over this PR & let you review, in case you'd prefer that.

- Change levels to include atomic and safe on distinct objects. - Add a section explaining the levels in the thread safety page - Cross reference levels section from annotation

lysnikolaou · 2026-03-06T13:45:20Z

I've addressed all feedback. Additionally, after some more discussions on this, I've settled on having five different thread safety levels. I've also opened python/python-docs-theme#299 for the changes required there.

lysnikolaou · 2026-03-10T13:05:39Z

@hugovk @encukou Another round of reviews would be great. I have a few annotations ready to go that all depend on this.

kumaraditya303 · 2026-03-10T13:41:02Z

+global state in an unsynchronized way and must only be called from a single
+thread throughout the program's lifetime.
+
+Example: a function that modifies process-wide state such as signal handlers


Another good example for this is APIs that return borrowed references

Not all of them :)
It would be nice to use specific functions as examples, like with PyList_GetItemRef and PyMutex_IsLocked below.

kumaraditya303 · 2026-03-10T14:07:33Z

+ # Name of the function.
+ name: str
+ # Thread safety level.
+ # One of: 'incompatible', 'compatible', 'safe'.


maybe use literal instead of str

encukou

This looks good, thank you!
Let's merge to unblock the other changes; details can always be adjusted afterwards.

encukou · 2026-03-11T14:28:38Z

+global state in an unsynchronized way and must only be called from a single
+thread throughout the program's lifetime.
+
+Example: a function that modifies process-wide state such as signal handlers


Not all of them :)
It would be nice to use specific functions as examples, like with PyList_GetItemRef and PyMutex_IsLocked below.

miss-islington-app · 2026-03-12T13:26:24Z

Thanks @lysnikolaou for the PR, and @kumaraditya303 for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

(cherry picked from commit 0dce4c6) Co-authored-by: Lysandros Nikolaou <lisandrosnik@gmail.com>

bedevere-app · 2026-03-12T13:26:36Z

GH-145862 is a backport of this pull request to the 3.14 branch.

…145862) Co-authored-by: Lysandros Nikolaou <lisandrosnik@gmail.com>

pythongh-145254: Add thread safety annotation
a270317
- Implement annotation for different thread safety levels - Annotate PyMutex_* APIs

lysnikolaou requested review from AA-Turner and hugovk as code owners February 26, 2026 13:35

bedevere-appBot added the awaiting core review label Feb 26, 2026

bedevere-appBot mentioned this pull request Feb 26, 2026
Add thread safety annotations for C API functions #145254
Closed

hugovk added the skip news label Feb 27, 2026

hugovk reviewed Feb 27, 2026
View reviewed changes

Comment threadDoc/tools/extensions/c_annotations.py Outdated

encukou reviewed Mar 4, 2026
View reviewed changes

lysnikolaou added the topic-free-threading label Mar 4, 2026

encukou reviewed Mar 5, 2026
View reviewed changes

Comment threadDoc/tools/extensions/c_annotations.py Outdated
Comment threadDoc/tools/extensions/c_annotations.py Outdated

lysnikolaou added 2 commits March 6, 2026 13:29

Address first round of feedback
d577860

Change levels and add new section to thread safety page
3ba0282
- Change levels to include atomic and safe on distinct objects. - Add a section explaining the levels in the thread safety page - Cross reference levels section from annotation

kumaraditya303 reviewed Mar 10, 2026
View reviewed changes

Comment threadDoc/library/threadsafety.rst Outdated

Use correct example for safe-shared level
0169478

kumaraditya303 reviewed Mar 10, 2026
View reviewed changes

encukou approved these changes Mar 11, 2026
View reviewed changes

bedevere-appBot added awaiting merge and removed awaiting core review labels Mar 11, 2026

encukou mentioned this pull request Mar 11, 2026
Thread safety of PyCapsule #145563
Closed

kumaraditya303 approved these changes Mar 12, 2026
View reviewed changes

kumaraditya303 merged commit 0dce4c6 into python:mainMar 12, 2026
32 checks passed

bedevere-appBot removed the awaiting merge label Mar 12, 2026

lysnikolaou added the needs backport to 3.14 bugs and security fixes label Mar 12, 2026

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Mar 12, 2026
pythongh-145254: Add thread safety annotation in docs (pythonGH-145255)
2ae998f
(cherry picked from commit 0dce4c6) Co-authored-by: Lysandros Nikolaou <lisandrosnik@gmail.com>

bedevere-appBot removed the needs backport to 3.14 bugs and security fixes label Mar 12, 2026

hugovk pushed a commit that referenced this pull request Mar 12, 2026
[3.14]gh-145254: Add thread safety annotation in docs (GH-145255) (#…
f9589cb
…145862) Co-authored-by: Lysandros Nikolaou <lisandrosnik@gmail.com>

lysnikolaou mentioned this pull request Mar 13, 2026
Tracking issue for free-threading docs #145912
Open
50 tasks

ljfp pushed a commit to ljfp/cpython that referenced this pull request Apr 25, 2026
pythongh-145254: Add thread safety annotation in docs (python#145255)
f9334fa

	classes= [f"threadsafety-{level}"]
	classes= ["threadsafety", f"threadsafety-{level}"]

Uh oh!

Uh oh!

Conversation

lysnikolaou commented Feb 26, 2026• edited by hugovk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hugovk commented Feb 27, 2026

Uh oh!

Uh oh!

encukouMar 4, 2026

Choose a reason for hiding this comment

Uh oh!

encukou left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

lysnikolaou commented Mar 6, 2026

Uh oh!

lysnikolaou commented Mar 10, 2026

Uh oh!

Uh oh!

kumaraditya303Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

encukouMar 11, 2026

Choose a reason for hiding this comment

Uh oh!

kumaraditya303Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

encukou left a comment

Choose a reason for hiding this comment

Uh oh!

encukouMar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-appBot commented Mar 12, 2026

Uh oh!

bedevere-appBot commented Mar 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lysnikolaou commented Feb 26, 2026•
edited by hugovk
Loading