Tracking issue for free-threading docs

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-142519
• gh-144184
• gh-144716
• gh-145224

C API thread safety annotations (gh-145254)

• Define five annotation levels: incompatible, compatible, distinct, shared, atomic
• gh-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-145225
• gh-145226
• gh-145911
• gh-145875
• gh-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.

asyncio free-threaded guide

• https://github.com/python/cpython/pull/150456

Other documentation gaps

• Review and improve queue module docs w.r.t. free-threaded builds
• Address gh-84992
• Address gh-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 gh-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

Start by choosing one unchecked, self-contained item from the remaining work, such as documenting a stdlib type or creating Doc/howto/free-threading-guide.rst. Read the related existing documentation, including free-threading-python.rst and threadsafety.rst, then complete the selected checklist item and add the requested cross-references or annotations.