gh-138072: Small clarifications and phrasing improvements to asyncio HOWTO #138073

anordin95 · 2025-08-22T19:18:20Z

Issue: Room for clarification and flow improvements in asyncio HOWTO #138072

📚 Documentation preview 📚: https://cpython-previews--138073.org.readthedocs.build/en/138073/howto/a-conceptual-overview-of-asyncio.html#a-conceptual-overview-of-asyncio

Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <[email protected]>

Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <[email protected]>

kumaraditya303 · 2025-08-24T11:13:56Z

Doc/howto/a-conceptual-overview-of-asyncio.rst

+:mod:`!asyncio` automatically associates tasks with the event loop for you.
+Typically there's only one event loop, so that's quite straightforward.
+It's uncommon, but some applications use multithreading and :mod:`!asyncio`
+together, where there's one event loop per thread, stored in thread-local


"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

kumaraditya303 · 2025-08-24T11:14:42Z

Doc/howto/a-conceptual-overview-of-asyncio.rst

@@ -251,6 +253,10 @@ different ways::
 In a crucial way, the behavior of ``await`` depends on the type of object
 being awaited.

+^^^^^^^^^^
+await task


Suggested change

await task

Awaiting Tasks

I prefer the original for a few reasons.

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

They offer a nudge to think about await beyond just the keyword itself and emphasize how the object await applies to is fundamentally important to the operation.

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

Suggested change

await task

Awaiting tasks

Hugo's suggestion would be my preference here and below.

kumaraditya303 · 2025-08-24T11:14:55Z

Doc/howto/a-conceptual-overview-of-asyncio.rst

@@ -282,6 +288,10 @@ This is a basic, yet reliable mental model.
 In practice, the control handoffs are slightly more complex, but not by much.
 In part 2, we'll walk through the details that make this possible.

+^^^^^^^^^^^^^^^
+await coroutine


Suggested change

await coroutine

Awaiting Coroutines

Use sentence case for headers:

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

Suggested change

await coroutine

Awaiting coroutines

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

FYI I fixed the other sentence-case examples you mentioned. But, I left await task and await coroutine for the reasons described here: #138073 (comment)

kumaraditya303 · 2025-08-26T15:32:57Z

Doc/howto/a-conceptual-overview-of-asyncio.rst

+:mod:`!asyncio` automatically associates tasks with the event loop for you.
+Typically there's only one event loop, so that's quite straightforward.
+It's uncommon, but some applications use multithreading and :mod:`!asyncio`
+together, where there's one event loop per thread, stored in thread-local


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

bedevere-app · 2025-08-26T15:33:11Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

willingc

With Hugo's suggested title changes, I am fine with the current state of this document.

Let's strive to keep this conceptual overview fairly high-level. The doc's purpose should stay focused on an overview and avoid going too far into a technical deep dive.

anordin95 · 2025-09-03T16:12:32Z

I think all requested changes have been addressed in this PR, besides modifications to the await task and await coroutine section titles requested by @hugovk & @willingc.

For ease of reference, the style guide says: "In the Python documentation, the use of sentence case in section titles is preferable, but consistency within a unit is more important than following this rule.".
I think it's fair to say these titles are consistent with the broader unit title: await.

Additionally, I think the use of "preferable" above implies there can be reasonable cases that ignore this guidance. I personally prefer the titles as they are now, for the reasons enumerated here.

With that in mind, I wonder if leaving them as is would be amenable for folks?

hugovk · 2025-09-04T09:36:17Z

Please do rename them to "Awaiting tasks" and "Awaiting coroutines".

For ease of reference, the style guide says: "In the Python documentation, the use of sentence case in section titles is preferable, but consistency within a unit is more important than following this rule.".
I think it's fair to say these titles are consistent with the broader unit title: await.

That's referring to the await keyword, so is lowercase. Should it be in code formatting, and/or reworded?

The next sentence of the devguide:

If you add a section to a chapter where most sections are in title case, you can either convert all titles to sentence case or use the dominant style in the new section title.

Well, the rest is already in sentence case, let's stick to it.

anordin95 · 2025-09-04T16:25:56Z

For reference, I interpreted the style guide as providing some leeway and more generally I think it can make sense to sometimes ignore strict adherence to style guides, in this case, for the sake of content/flow.

Either way, it seems my arguments fell short and failed to sway minds! I'll go ahead and change the section titles as requested.

P.S. The same idea regarding await came up in the original PR. Making it a code-block means it will be bolded in the table of contents on the sidebar, so we decided to leave it as is.

- Small clarifications and phrasing improvements

07d5a0a

anordin95 requested review from 1st1, asvetlov, kumaraditya303 and willingc as code owners August 22, 2025 19:18

bedevere-app bot added awaiting review docs Documentation in the Doc dir skip news labels Aug 22, 2025

github-project-automation bot added this to Docs PRs Aug 22, 2025

github-project-automation bot moved this to Todo in Docs PRs Aug 22, 2025

bedevere-app bot mentioned this pull request Aug 22, 2025

Room for clarification and flow improvements in asyncio HOWTO #138072

Open

StanFromIreland requested a review from ZeroIntensity August 22, 2025 19:52

nit

34f496f

ZeroIntensity reviewed Aug 23, 2025

View reviewed changes

anordin95 and others added 3 commits August 23, 2025 15:04

Apply suggestions from code review

b189b94

Co-authored-by: Peter Bierma <[email protected]>

clarify event loops when multi threading.

f97bfb6

nit

a389c09

ZeroIntensity reviewed Aug 24, 2025

View reviewed changes

Doc/howto/a-conceptual-overview-of-asyncio.rst Outdated Show resolved Hide resolved

Doc/howto/a-conceptual-overview-of-asyncio.rst Outdated Show resolved Hide resolved

anordin95 and others added 4 commits August 23, 2025 20:49

Update Doc/howto/a-conceptual-overview-of-asyncio.rst

2831208

Co-authored-by: Peter Bierma <[email protected]>

nit

274c727

nit

12d6e35

phrasing for threads & event loops.

176814e

kumaraditya303 reviewed Aug 24, 2025

View reviewed changes

kumaraditya303 requested changes Aug 26, 2025

View reviewed changes

bedevere-app bot added awaiting changes and removed awaiting review labels Aug 26, 2025

revert changes to event-loop/thread discussion.

e475aef

sentence case consistencty.

1391594

willingc reviewed Aug 28, 2025

View reviewed changes

slight re-arrange.

0692644

Sentence case consistency.

13843e9

Uh oh!

gh-138072: Small clarifications and phrasing improvements to asyncio HOWTO #138073

Are you sure you want to change the base?

gh-138072: Small clarifications and phrasing improvements to asyncio HOWTO #138073

Conversation

anordin95 commented Aug 22, 2025 • edited by hugovk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kumaraditya303 Aug 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anordin95 Aug 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anordin95 Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anordin95 Aug 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hugovk Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bedevere-app bot commented Aug 26, 2025

Uh oh!

willingc left a comment

Choose a reason for hiding this comment

Uh oh!

anordin95 commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hugovk commented Sep 4, 2025

Uh oh!

anordin95 commented Sep 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

anordin95 commented Aug 22, 2025 •

edited by hugovk

Loading

kumaraditya303 Aug 24, 2025 •

edited

Loading

anordin95 Aug 25, 2025 •

edited

Loading

anordin95 Aug 26, 2025 •

edited

Loading

anordin95 Aug 24, 2025 •

edited

Loading

hugovk Aug 27, 2025 •

edited

Loading

anordin95 commented Sep 3, 2025 •

edited

Loading

anordin95 commented Sep 4, 2025 •

edited

Loading