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.

Linked PRs

• gh-145254: Add thread safety annotation #145255
• [3.14] gh-145254: Add thread safety annotation in docs (GH-145255) #145862
• gh-145254: Fix formatting of thread safety annotations #146111
• [3.14] gh-145254: Fix formatting of thread safety annotations (GH-146111) #146163