Repository navigation
Add thread safety annotations for C API functions #145254
Description
Activity
- added a commit that references this issue
on Feb 26, 2026 I've decided to increase the number of levels to the following:
- incompatible: Not safe even with external locking
- compatible: Safe if the caller serializes all access with external locks
- distinct: Safe to call without external synchronization on distinct objects
- shared: Safe to call without external synchronization on the same shared object
- atomic: Appears atomic to all threads
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:
Each annotation links to the corresponding glossary term. The
thread-safeterm already exists in the glossary,thread-compatibleandthread-incompatiblewould be added.I have PRs ready for both CPython and python-docs-theme. Feedback welcome, especially on the choice and naming of levels.
Linked PRs