Documentation Community Team Meeting (November 4, 2025)¶
Roll call¶
(Name / @GitHubUsername [/ Discord, if different])
Hugo van Kemenade /
@hugovkAdam Turner /
@AA-TurnerNed Batchelder /
@nedbatNathan Goldblum /
@ngoldblumBlaise Pabon /
@blaisep/controlpl4n3Ryan Duve /
@ryan-duve
Introductions¶
If there are any new people, we should do a round of introductions.
We had a round.
Reports and celebrations¶
None this time.
Discussion¶
[Lysandros/Nathan] CPython free-threading (FT) docs
https://py-free-threading.github.io
gh-137232: Update free-threading HOWTOs with up-to-date info for 3.14
[Nathan] Lys is concentrating on improving CPython docs for FT, unfortunately couldn’t attend this meeting due to a conflict.
Steering Council said let’s make https://py-free-threading.github.io part of docs.python.org as a subdomain.
A big new batch of docs by the FT team was recently relicensed from MIT to 0BSD + MIT so we can upstream to the CPython docs.
It uses MKDocs.
Feedback from Sam Gross and Thomas Wouters: it would be best to avoid making huge changes to existing docs.
But what is as minimal as possible?
Feedback from docs editorial team: keep on own page.
Have already made PRs to improve glossary, how-tos, and more upstreamed from FT guide.
Want clarity on how to move forward.
The plan is in Quansight-Labs/free-threaded-compatibility#261.
[Adam] Would like to avoid the glossary being a general programming resource.
[Nathan] Good feedback, if entries need to exist, it’s because of CPython’s needs.
[Ned] Not so convinced if they should only relate to Python, it’s a difficult balance. Now we’re looking through that lens, how many other entries would be excluded with that rule?
[Adam] There was a general discussion on this topic at the Cambridge core sprint, no actions created. How tight do we make the FT docs its own area vs. putting them throughout general docs? For example, do we add notes on
listabout being atomic in stdtypes, or have an FT reference section somewhere with all the common container considerations? The latter was preferred. Is it realistic to put all the relevant concerns on a single page?[Nathan] The next big task for Lys is to look at the big types and work out safety guarantees. For example, it’s not safe to share iterators across threads, and memoryviews have considerations. Need to list them somewhere.
listanddictwill be pretty straightforward, atomic for the most part. Others will be complicated. It depends on how much there is to say for each. Some things are ready for 3.15, but weren’t for 3.14. At least for builtins, we’ll write this down in a big table, then it’ll be easier to figure out how to integrate it.[Adam] Yes, this will help. Also, a difference between thread-safety concerns in the abstract, and relating to free-threading. For example, sharing data structure between threads, already concerns in older versions. How do we document thread safety with a nod to FT, while not cluttering things up? Many programmers will only use single-threaded. We’ll want to point them to higher abstract things.
[Nathan] Should document it, people should assume types are not safe to share between threads.
list/dictbeing atomic should be clearly documented. Per-module docs can help a lot, if we can add a FT section. Matthias Bussonnier is looking to improve ecosystem docs, for example, the NumPy docs need an FT section. Need to figure out where to draw line.[Ned] Not sure about a regular thread-safety section, as Adam mentioned, tends to be an advanced topic and for the most part you don’t need to worry about it. For example,
listcould say threads are atomic, see elsewhere for more about this. Otherwise, spread throughout docs seems a bit lopsided. We’ve been fixing flaws in the language, but doesn’t need to be top of mind for most readers. For example, we don’t say list access is O(1) and so on. People say that’s an implementation detail. FT is also an implementation detail.[Nathan] The broader point is how to document implementation details. Will try and make minimal changes to docs, but add when thread-safe or not. How would readers get to a thread-safety page? How to get there from stdlib module pages? Are there links?
[Ned] Seems reasonable to have links sprinkled throughout docs to the main page: “Are you using FT? Go here”.
[Adam] We have availability notes: “Availability: Unix, not WASI”. We could do the same for FT. The concern is how far up the discoverability chain do we put it. A 12-year-old reading
listdocs don’t need to know about thread safety, an advanced programmer might. Should be aiming so using Python just works, keep simple things easy. Only when run into something complex do you need to go to thread-safety guarantees. So a link for every type with a tick or cross is an antipattern. I think this touches on the py-free-threading guide, I don’t think it should exist, it would be a shame to bifurcate the docs like that. Advanced topics should be in the main docs. Would rather make its way into main docs. The FT tracker is probably right to stay external, don’t need to upstream everything.[Adam] Want advanced docs there if needed, but don’t want to scare people with thread-safety warnings everywhere if not needed. Can mention
list/dictare safe. Extensions should have a statement like: “assume not thread-safety”.[Nathan] Idea: maybe a data model page, like in Java, that goes over things like thread-safety, and thinking about threading in Python.
[Ned] How to find it?
[Adam] Reasonable idea. Having more reference docs. Too much runtime init/model stuff are in C API docs and should be moved to the main reference. What are language/implementation guarantees? Docs about model seems reasonable. Once written, getting it in front of people is easier, when it exists. SEO will help.
[Nathan] Will start linking when it exists.
[Ned] Get the words written, then we can move and improve. Does Python have a crisp data model page, when we have 30 years of organic growth?
[Nathan] Java went the other way. No draft yet of the page. Lys is working on an overview of all builtins, which will inform this. We have https://docs.python.org/3/reference/datamodel.html, but it’s out of date, mentions GIL, some stuff is wrong. Will need to fix it as part of this.
[Ned] And it’s too long.
[Adam] Skimming the current FT guide, maybe about half make sense to upstream. Definitely the porting guide, and subinterpreters.
[Nathan] And Cython and pybind11?
[Adam] For the C API. Good to upstream frequently seen errors.
[Nathan] Almost all is ecosystem docs. It would be helpful to link to Cython docs on this and the others from CPython docs.
[Adam] Willing to link externally.
[Ned] If upstreamed, do we still need a separate guide?
[Nathan] Yes, because a lot is needed for details about Cython or PY03 etc. many building via bindings generators and not C API directly.
[Ned] Willing to upstream for the C API. Would we insist on this, or better to have it in one place if it only applies to C API?
[Nathan] The existing porting guide is pretty good, already upstreamed what makes sense. Maybe need general considerations, content not necessarily about C API, and extensions in general, what to avoid, using critical section, so you understand what it means. Some level of CPython docs for extension authors, doesn’t need to go into details about generators or C API.
[Adam] If FT becomes default, what’s the situation then? Would we still want a py-free-threading guide? We’ve not really done this for other language features. As a transition thing, it’s a really good resource. But from a 10-year perspective, wouldn’t I want to reach for projects’ own docs first? And C API docs directly?
[Nathan] the relevant stuff should be in the CPython docs. Would be good to have https://py-free-threading.github.io/porting-extensions/#working-with-the-free-threaded-cpython-interpreter-runtime in docs: detaching/attaching/GIL stuff. How to think about blocking calls, deadlock with interpreter, general content about how to work with C API but it’s for all extension authors. All can link to these docs.
[Adam] For consumers of C API. Have you spoken to the C API WG?
[Nathan] Not about docs. Thread-safety notes about C API are less pressing than notes that more will see. What’s your take on adding thread-safety to C API docs?
[Adam] Important, but less interested personally. Petr is an expert here. Can ask when Petr and Lys are both present next time.
[Nathan] Can convert to Sphinx if needed when upstreaming.
[Blaise] Petr has a weekly stream working on the grammar docs, can also do office hours stuff. No need to wait until next month’s meeting. The event in this Discord, welcome to drop in.
[Nathan] We want more eyes on this stuff. It would be helpful if you could chime in on the tracking issue above. More expert eyes on the docs before upstreaming will help. More about improving CPython docs than porting the whole thing over and overwhelming a 12-year-old. Better to document the positive things, can also mention some here-be-dragons.
[Ned] The current docs aren’t great at dealing with the implementation-specific aspect, so maybe we’ll flex those muscles getting these in.
[Nathan] Find a way to doc implementation details, subject to change, so people don’t rely on them.
[Ned] We have some, but in weird corners.
[Adam] Don’t have a policy.
[Ned] See python/devguide#1679 a PR on use of AI, in case you want to chime in.
[Blaise] tutorials: has there been a discussion on learning objectives for different scenarios.
[Ned] It’s difficult to speak with one voice, users are so diverse. So many paths.