GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-145254: Add thread safety annotation by lysnikolaou · Pull Request #145255 · python/cpython

Conversation

@lysnikolaou

@lysnikolaou lysnikolaou commented Feb 26, 2026 •
edited by hugovk
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member
  • 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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@lysnikolaou
pythongh-145254: Add thread safety annotation
a270317 
- Implement annotation for different thread safety levels
- Annotate PyMutex_* APIs
@lysnikolaou
lysnikolaou requested review from AA-Turner and hugovk as code owners February 26, 2026 13:35
@bedevere-app bedevere-app Bot added the awaiting core review label Feb 26, 2026
@bedevere-app bedevere-app Bot mentioned this pull request Feb 26, 2026
Add thread safety annotations for C API functions #145254
Closed
@hugovk hugovk added the skip news label Feb 27, 2026
@hugovk

hugovk commented Feb 27, 2026

Copy link
Copy Markdown
Member

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.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
hugovk
hugovk reviewed Feb 27, 2026
View reviewed changes
Comment thread Doc/tools/extensions/c_annotations.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
encukou
encukou reviewed Mar 4, 2026
View reviewed changes
Comment thread Doc/tools/extensions/c_annotations.py Outdated
refexplicit="True",
)
prefix = sphinx_gettext("Thread safety:") + " "
classes = [f"threadsafety-{level}"]

@encukou encukou Mar 4, 2026

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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}"]

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@lysnikolaou lysnikolaou added the topic-free-threading label Mar 4, 2026
encukou
encukou reviewed Mar 5, 2026
View reviewed changes

@encukou encukou left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/tools/extensions/c_annotations.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/tools/extensions/c_annotations.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
lysnikolaou added 2 commits March 6, 2026 13:29
@lysnikolaou
Address first round of feedback
d577860
@lysnikolaou
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
@lysnikolaou

lysnikolaou commented Mar 6, 2026

Copy link
Copy Markdown
Member Author

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.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@lysnikolaou

lysnikolaou commented Mar 10, 2026

Copy link
Copy Markdown
Member Author

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
kumaraditya303
kumaraditya303 reviewed Mar 10, 2026
View reviewed changes
Comment thread Doc/library/threadsafety.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@lysnikolaou
Use correct example for safe-shared level
0169478
kumaraditya303
kumaraditya303 reviewed Mar 10, 2026
View reviewed changes
Comment thread Doc/library/threadsafety.rst
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

@kumaraditya303 kumaraditya303 Mar 10, 2026

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another good example for this is APIs that return borrowed references

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@encukou encukou Mar 11, 2026

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not all of them :)

It would be nice to use specific functions as examples, like with PyList_GetItemRef and PyMutex_IsLocked below.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
kumaraditya303
kumaraditya303 reviewed Mar 10, 2026
View reviewed changes
Comment thread Doc/tools/extensions/c_annotations.py
# Name of the function.
name: str
# Thread safety level.
# One of: 'incompatible', 'compatible', 'safe'.

@kumaraditya303 kumaraditya303 Mar 10, 2026

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe use literal instead of str

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
encukou
encukou approved these changes Mar 11, 2026
View reviewed changes

@encukou encukou left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/library/threadsafety.rst
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

@encukou encukou Mar 11, 2026

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not all of them :)

It would be nice to use specific functions as examples, like with PyList_GetItemRef and PyMutex_IsLocked below.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@bedevere-app bedevere-app Bot added awaiting merge and removed awaiting core review labels Mar 11, 2026
@encukou encukou mentioned this pull request Mar 11, 2026
Thread safety of PyCapsule #145563
Closed
kumaraditya303
kumaraditya303 approved these changes Mar 12, 2026
View reviewed changes
@kumaraditya303
kumaraditya303 merged commit 0dce4c6 into python:main Mar 12, 2026
32 checks passed

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot removed the awaiting merge label Mar 12, 2026
@lysnikolaou lysnikolaou added the needs backport to 3.14 bugs and security fixes label Mar 12, 2026
@miss-islington-app

miss-islington-app Bot commented Mar 12, 2026

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Mar 12, 2026
@lysnikolaou @miss-islington
pythongh-145254: Add thread safety annotation in docs (pythonGH-145255)
2ae998f 
(cherry picked from commit 0dce4c6)

Co-authored-by: Lysandros Nikolaou <[email protected]>
@bedevere-app

bedevere-app Bot commented Mar 12, 2026

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot 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
@miss-islington @lysnikolaou
[3.14] gh-145254: Add thread safety annotation in docs (GH-145255) (#…
f9589cb 
…145862)

Co-authored-by: Lysandros Nikolaou <[email protected]>
@lysnikolaou lysnikolaou mentioned this pull request Mar 13, 2026
Tracking issue for free-threading docs #145912
Open
18 of 49 tasks
ljfp pushed a commit to ljfp/cpython that referenced this pull request Apr 25, 2026
@lysnikolaou @ljfp
pythongh-145254: Add thread safety annotation in docs (python#145255)
f9334fa
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@hugovk hugovk hugovk left review comments
@encukou encukou encukou approved these changes
@kumaraditya303 kumaraditya303 kumaraditya303 approved these changes
@AA-Turner AA-Turner Awaiting requested review from AA-Turner AA-Turner is a code owner

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

skip news topic-free-threading

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

4 participants

@lysnikolaou @hugovk @encukou @kumaraditya303
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.