"stored in thread-local" is unnecesary implemenetation detail for the reader, just per thread seems sufficient.

See discussion here: #138073 (comment)

I'd also be OK with just "per thread". But, I don't totally understand the rationale to clarify thread-locality here -- what was wrong with the original wording?

This paragraph states asyncio automatically associates tasks with the event loop so you, the user, don't need to specify the loop in the asyncio.create_task constructor (nor are you even allowed to). The "per thread" part implies there can be multiple event loops (via multithreading) in the same memory space.

I think it's quite natural to then wonder how tasks will be associated with event loops when there are multiple event loops to choose from. And how you, the user, could manage which loop a task is assigned to. I see that as an easy way for the reader to get confused. The point of this article is to be explanatory.

While, yes, it is an implementation detail, it's not some arcane, fragile aspect. It's a fundamental design pattern exposed by the OS. And, it appears this usage of thread-local hasn't changed in the 12 years that asyncio has been around.

Thread locality is an implementation detail and should stay as an implementation detail, -1 for adding this.

Yes, that is largely what you wrote the first time around. The logical gap I highlighted would still exist and potentially confuse readers. I agree, implementation details should generally be kept in the code, but not always. Sparsely and judiciously exposing broad ideas can ultimately create more explanatory and helpful docs, as opposed to making many vague, abstract statements, especially since this is a HOWTO, not reference, doc. Could you clarify some of the reasoning behind why you feel this way?

Like I mentioned in the prior PR, perhaps you can see how it's difficult to productively engage with this style of feedback and discussion?

Alex, I sympathize with thread-locality being quite confusing, but I'm going to side with Kumar here. asyncio really isn't about multithreading at all, and as you said, this is an explanatory HOWTO article. We should try to avoid bringing up niche use-cases that make the reader think "oh, asyncio and multithreading are friends, let's do that more".

As a compromise for now, would you mind reverting these changes and putting them in a follow-up PR so we can argue about it there? The rest of the changes in this PR look good to me, and it would better for those to not be blocked by discussions about this.

(We really do value your article as a contribution, please don't take this the wrong way!)

Mhm fair enough :). Will do.

See: #138200

I prefer the original for two reasons.

The titles come from the references made in the broader await section intro.

And they fit more naturally in the broader table of contents:

Use sentence case for headers:

https://devguide.python.org/documentation/style-guide/#capitalization

(We could also fixA Conceptual Overview of asyncio" -> "A conceptual overview of asyncio" and "Event Loop" -> "Event loop".)

Thread locality is an implementation detail and should stay as an implementation detail, -1 for adding this.