Title: Tracking issue for free-threading docs · Issue #145912 · python/cpython · GitHub
Open Graph Title: Tracking issue for free-threading docs · Issue #145912 · python/cpython
X Title: Tracking issue for free-threading docs · Issue #145912 · python/cpython
Description: 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. Complete...
Open Graph Description: 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 ann...
X Description: 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 ann...
Opengraph URL: https://github.com/python/cpython/issues/145912
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Tracking issue for free-threading docs","articleBody":"### Documentation\n\n## Summary\n\nThis 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.\n\n## Completed work\n\n### Thread safety page and built-in type guarantees (gh-142518)\n\n- [x] Define free-threading related terms in the glossary\n- [x] gh-142519\n- [x] gh-144184\n- [x] gh-144716\n- [x] gh-145224\n\n### C API thread safety annotations (gh-145254)\n\n- [x] Define five annotation levels: `incompatible`, `compatible`, `distinct`, `shared`, `atomic`\n- [x] gh-145255\n- [x] Add thread safety levels reference section to `threadsafety.rst`\n- [x] Open python-docs-theme PR for rendering support\n\n## In progress (at the time of writing)\n\n- [x] gh-145225\n- [x] gh-145226\n- [x] gh-145911\n- [x] gh-145875 \n- [x] gh-146109\n\n\n## Remaining work\n\n### stdlib type documentation\n\nAfter built-in types, document thread-safety guarantees for stdlib types. Suggested priority:\n\n- [ ] `collections.deque` - widely used as a thread-safe queue substitute; people already assume it's safe; heavily used in asyncio internals\n- [ ] `io` types (`BufferedReader`, `BufferedWriter`, `TextIOWrapper`) - file I/O is inherently concurrent in real programs; existing thread-safety notes are scattered and incomplete\n- [ ] `collections.defaultdict` - the `__missing__` call introduces non-obvious concurrency questions (factory call is not atomic with insertion)\n- [ ] `collections.OrderedDict` - has its own internal locking that differs from plain dict\n- [ ] `collections.Counter` - commonly used for aggregation across threads\n- [ ] `array.array` - mutable typed array, relevant for numeric/scientific code going parallel\n\nRationale: `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.\n\n### Free-threading programming guide (new HOWTO)\n\nA 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**.\n\nTopics to cover:\n\n- [ ] Single operations vs. compound operations - why \"thread-safe\" doesn't mean \"atomic\"\n- [ ] Common pitfalls: check-then-act, read-modify-write, iterating shared containers\n- [ ] When and how to use `threading.Lock` and other synchronization primitives\n- [ ] Practical patterns: queues, `concurrent.futures`, thread-local storage\n- [ ] Testing and debugging strategies (ThreadSanitizer, running under free-threaded builds)\n- [ ] Summary reference table of built-in type thread safety (quick lookup, links to detailed per-type docs)\n\nCross-reference from `free-threading-python.rst` and from the per-type thread safety page.\n\n### `asyncio` free-threaded guide\n\n- [ ] https://github.com/python/cpython/pull/150456\n\n### Other documentation gaps\n\n- [ ] Review and improve `queue` module docs w.r.t. free-threaded builds\n- [ ] Address gh-84992\n- [ ] Address gh-83556\n\n### C API annotations\n\n- [ ] Annotate `PyObject_*` APIs (creation, attribute access, comparison, etc.)\n- [ ] Annotate abstract layer APIs \n \t- [ ] `PySequence_*`\n \t- [ ] `PyMapping_*`\n \t- [ ] `PyNumber_*`\n \t- [ ] `PyIter_*`\n- [ ] Annotate reference counting APIs (`Py_INCREF`, `Py_DECREF`, `Py_NewRef`, etc.)\n- [ ] Annotate GIL/critical-section APIs\n- [ ] Annotate concrete type APIs\n\t- [x] `PyList_*`\n\t- [x] `PyDict_*`\n\t- [x] `PySet_*`\n\t- [x] `PyTuple_*`\n\t- [ ] `PyUnicode_*`\n- [ ] Annotate buffer protocol APIs (`PyObject_GetBuffer`, `PyBuffer_Release`, etc.)\n- [ ] Systematically work through remaining high-usage C API functions\n\n### Infrastructure improvements\n\n- [ ] Coordinate with gh-116738 (audit all built-in modules for thread safety) - ensure doc annotations stay in sync with implementation fixes\n- [ ] Add CI/linting to validate `threadsafety.dat` entries match actual function signatures\n- [ ] Consider generating per-module thread safety summary tables - especially in modules where it makes sense like `collections`\n\n\n\u003c!-- gh-linked-prs -->\n### Linked PRs\n* gh-161162\n* gh-161165\n* gh-161516\n\u003c!-- /gh-linked-prs -->\n","author":{"url":"https://github.com/lysnikolaou","@type":"Person","name":"lysnikolaou"},"datePublished":"2026-03-13T13:44:28Z","url":"https://github.com/python/cpython/issues/145912"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:4dcfc2f3-b7c7-ff35-7c63-f6f6a99f6ff8 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | ECD8:1F2F:18E95E7:21199FF:6B01FF19 |
| html-safe-nonce | 12f85cd6c02a64416996c79be69ca3756739187b32b53df292229a4e841cd05a |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJFQ0Q4OjFGMkY6MThFOTVFNzoyMTE5OUZGOjZCMDFGRjE5IiwidmlzaXRvcl9pZCI6IjgxNjkzMTUwODkxNDk3MjIzOTMiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | a8e5e5c97dc87ad3fa0e56079860e150fd47bc7ff0383c562f3fef84b8ce222b |
| hovercard-subject-tag | issue:4071213046 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/python/cpython/145912/issue_layout |
| twitter:image | https://opengraph.githubassets.com/047ebe7ed834a794fa60d74a5b45850fb49a7365d590c3509f0b50f758d645a9/python/cpython/issues/145912 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/047ebe7ed834a794fa60d74a5b45850fb49a7365d590c3509f0b50f758d645a9/python/cpython/issues/145912 |
| og:image:alt | 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 ann... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | lysnikolaou |
| hostname | github.com |
| expected-hostname | github.com |
| None | 87e774ee7c6b3bee0490394e4d3e57ec9dbc956f74b87ea685dc8996c1676456 |
| turbo-cache-control | no-preview |
| go-import | github.com/python/cpython git https://github.com/python/cpython.git |
| octolytics-dimension-user_id | 1525981 |
| octolytics-dimension-user_login | python |
| octolytics-dimension-repository_id | 81598961 |
| octolytics-dimension-repository_nwo | python/cpython |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 81598961 |
| octolytics-dimension-repository_network_root_nwo | python/cpython |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 423dbb54c5e7bfecc838eb387c1435eb3d0e760d |
| ui-target | canary-2 |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width