Repository navigation
Add thread safety annotations for C API functions #145254
Description
Documentation
CPython's C API documentation has no systematic way to communicate the thread safety guarantees of individual APIs. As the free-threaded build matures, this information is increasingly important for extension authors.
This is analogous to how return value ownership is documented today, with automatically-inserted "Return value: New reference." / "Return value: Borrowed reference." annotations. We should do the same for thread safety.
Proposed levels
Three levels, ordered from least to most safe:
- Thread-incompatible: Not safe even with external locking
- Thread-compatible: Safe if the caller serializes all access with external locks
- Safe: Safe to call from multiple threads on shared objects
Each annotation links to the corresponding glossary term. The thread-safe term already exists in the glossary, thread-compatible and thread-incompatible would be added.
I have PRs ready for both CPython and python-docs-theme. Feedback welcome, especially on the choice and naming of levels.
Activity
pythongh-145254: Add thread safety annotation
lysnikolaou commentedon Mar 6, 2026
I've decided to increase the number of levels to the following:
gh-145254: Add thread safety annotation in docs (#145255)
pythongh-145254: Add thread safety annotation in docs (pythonGH-145255)
[3.14] gh-145254: Add thread safety annotation in docs (GH-145255) (#…
pythongh-145254: Fix formatting of thread safety annotations
pythongh-145254: Fix formatting of thread safety annotations
gh-145254: Fix formatting of thread safety annotations (#146111)
pythongh-145254: Fix formatting of thread safety annotations (pythonG…
[3.14] gh-145254: Fix formatting of thread safety annotations (GH-146111
pythongh-145254: Add thread safety annotation in docs (python#145255)
pythongh-145254: Fix formatting of thread safety annotations (python#…