Tracking issue for free-threading docs

[lysnikolaou]

Documentation

Summary

This is a tracking issue for the ongoing effort to improve thread safety documentation in CPython, covering both Python-level guarantees for built-in types and C API-level annotations for extension authors.

Completed work

Thread safety page and built-in type guarantees (gh-142518)

• Define free-threading related terms in the glossary
• gh-142518: Document thread-safety guarantees of list operations #142519
• gh-142518: Document thread-safety guarantees of dict operations #144184
• gh-142518: Move thread safety sections into a new page #144716
• gh-142518: Improve mimalloc allocator docs #145224

C API thread safety annotations (gh-145254)

• Define five annotation levels: incompatible, compatible, distinct, shared, atomic
• gh-145254: Add thread safety annotation #145255
• Add thread safety levels reference section to threadsafety.rst
• Open python-docs-theme PR for rendering support

In progress (at the time of writing)

• gh-142518: Document thread-safety guarantees of set objects #145225
• gh-142518: Document thread-safety guarantees of bytearray objects #145226
• gh-142518: Add thread safety notes for the buffer protocol #145911
• gh-142518: Annotate PyDict_* C APIs for thread safety #145875 (awaiting review)
• gh-142518: Annotate PyList_* C APIs for thread safety #146109

Remaining work

stdlib type documentation

After built-in types, document thread-safety guarantees for stdlib types. Suggested priority:

• collections.deque - widely used as a thread-safe queue substitute; people already assume it's safe; heavily used in asyncio internals
• io types (BufferedReader, BufferedWriter, TextIOWrapper) - file I/O is inherently concurrent in real programs; existing thread-safety notes are scattered and incomplete
• collections.defaultdict - the __missing__ call introduces non-obvious concurrency questions (factory call is not atomic with insertion)
• collections.OrderedDict - has its own internal locking that differs from plain dict
• collections.Counter - commonly used for aggregation across threads
• array.array - mutable typed array, relevant for numeric/scientific code going parallel

Rationale: deque first because it's the most likely to be shared across threads today. io types next because concurrent file access is common and the current docs are inadequate. The collections types after that, ordered by usage frequency and concurrency risk. array.array last - niche usage, but mutable so still worth documenting.

Free-threading programming guide (new HOWTO)

A new Doc/howto/free-threading-guide.rst, alongside the existing two free-threading HOWTOs. The existing free-threading-python.rst stays focused on "what is free-threading / what changed." The new guide focuses on how to write correct concurrent code.

Topics to cover:

• Single operations vs. compound operations - why "thread-safe" doesn't mean "atomic"
• Common pitfalls: check-then-act, read-modify-write, iterating shared containers
• When and how to use threading.Lock and other synchronization primitives
• Practical patterns: queues, concurrent.futures, thread-local storage
• How to migrate existing threaded code that relied on the GIL
• Testing and debugging strategies (ThreadSanitizer, running under free-threaded builds)
• Summary reference table of built-in type thread safety (quick lookup, links to detailed per-type docs)

Cross-reference from free-threading-python.rst and from the per-type thread safety page.

Other documentation gaps

• Review and improve queue module docs w.r.t. free-threaded builds
• Address Multiprocessing docs don't describe thread-safety #84992
• Address Document os.environ[x] = y and os.putenv() as thread unsafe #83556

C API annotations

• Annotate PyObject_* APIs (creation, attribute access, comparison, etc.)
• Annotate abstract layer APIs
  • PySequence_*
  • PyMapping_*
  • PyNumber_*
  • PyIter_*
• Annotate reference counting APIs (Py_INCREF, Py_DECREF, Py_NewRef, etc.)
• Annotate GIL/critical-section APIs
• Annotate concrete type APIs
  • PyList_*
  • PyDict_*
  • PySet_*
  • PyTuple_*
  • PyUnicode_*
• Annotate buffer protocol APIs (PyObject_GetBuffer, PyBuffer_Release, etc.)
• Systematically work through remaining high-usage C API functions

Infrastructure improvements

• Coordinate with Audit all built-in modules for thread safety #116738 (audit all built-in modules for thread safety) - ensure doc annotations stay in sync with implementation fixes
• Add CI/linting to validate threadsafety.dat entries match actual function signatures
• Consider generating per-module thread safety summary tables - especially in modules where it makes sense like collections