Documentation

I've used Python's asyncio a couple times now, but never really felt confident in my mental model of how it fundamentally works and therefore how I can best leverage it. The official docs provide decent documentation for each specific function in the package, but, in my opinion, lack a cohesive overview of the systems design and architecture. Something that could help the user understand the why and how behind the recommended patterns. And a way to help the user make informed decisions about which tool in the asyncio toolkit they ought to grab, or to recognize when asyncio is the entirely wrong toolkit.

I spent a long time digging into the internals and then decided to take a stab at filling that perceived gap by writing a fairly thorough long-form article: A conceptual overview of asyncio.

I also submitted the article to HackerNews where it got some traction: https://news.ycombinator.com/item?id=44638710

I imagine there's a few ways forward here.

• Linking to the Github article from the asyncio docs
• Integrating the article directly into the Python docs (along with stylistic & content modifications to match)
• Y'all decide the article's mediocre at best and you don't want it merged. (Fair enough!).

Either way, let me know what y'all figure makes the most sense. :)