Personally, I’m not sure why this design decision was made and find it rather confuses the meaning of await: asynchronously wait. If someone here does know, please tell me so I can update this section appropriately! I think providing such context can aid significantly with peoples understanding (myself included!).

For reference, I'd imagine either having coroutines yield in their __await__ or disallowing await coroutine entirely (thereby effectively mandating people who want to use coroutines must use coroutine.send()).

If I understand your question correctly, it's just that coroutines act as a wrapper over other tasks. Using await on a coroutine will cede control once that coroutine calls await on a task.

Yes, agreed! Coroutines will give up control once await is used on a task or future.

However, I think that coroutines not ceding on await is somewhat surprising behavior. One of the upsides of asyncio is the precise visibility into where control handoffs happen. This behavior muddles that insight a bit. The person reading the code can't just look for await's, they need to know the type of the object being awaited.

I imagine most coroutines do eventually call something which will await a task or future, but some may not. In a similar vein as that first point, this behavior feels like a sneaky gotcha that could surprise users and lead to implementations that unintentionally hog the event loop.

Finally, I don't really see a strong upside to the current behavior in the face of those downsides. I'd prefer entirely disallowing await coroutine and instead having authors rely on coroutine.send. But, of course, I might be missing something!

I imagine most coroutines do eventually call something which will await a task or future, but some may not.

It's not that intuitive, but if no future/task is called down the line, then there's no point in making it async. A function becomes async because it needs to await something else that is async, and that should go all the way down the line until you hit a case where someone made something async to await a future/task. If there isn't one, then there was no point in making anything async in the first place.

Yes, you can still write correct or incorrect programs either way. My concern is that a well designed tool should be hard to misuse. And I don't see an upside for the synchronous await coroutine behavior, despite this downside.

For a concrete example, consider someone working in a broader async codebase. They want to create functionality to asynchronously wait for a db request from their in-house, custom db. They write something like this. And fail to realize they're unwittingly going to stall the whole event loop, despite the various uses of await.

async def read_from_db():
    while True:
        is_db_ready = await check_is_db_ready()
        if is_db_ready:
            db_record = await fetch_db_record()
            return db_record

I think it's basically syntactic-sugar for yield from (i.e. the syntax that was originally used in 3.4). Therefore it's needed to enter the coroutine (which is basically another name for a generator) and run that code. In other words, anything async needs to use await, but it doesn't necessarily yield.

It would be more accurate to say that await is the only place in the code where we may yield back to the event loop, but there's no guarantee unless you are familiar with the functionality of that code. e.g. In aiohttp, some users may, on the rare occasion, get caught by code processing data slower than it arrives and therefore the code never actually needs to yield to the event loop (because we're never waiting for the socket).

Please see our style guide, new documentation should not have such text, as it discourages others from contributing.

This comment has yet to be addressed.

Hm, maybe we should make an exception to this rule here. This isn't getting a whatsnew or blurb entry, so @anordin95 has no other way to be acknowledged for his efforts.

The devguide doesn't do a great job of explaining why author attribution discourages other people from contributing; would you mind pointing me to the issue where this was discussed? I'm curious if this was based on actual contributor feedback or just speculation.

This was decided by the EB IIRC. It has been done for the latest HOWTO (which I think is the only one since the guide’s introduction).

Is there a link to the EB discussion/decision? I'm not really familiar with how their governance process works.

Yes, I'm ok with the "originally by". I'm actually not opposed to crediting the work. I'm just opposed to have the byline itself. I'm perfectly fine with having something citing a work upon which this is based. As a side note, I'm also not opposed to citing authors inside code comments in general as they are more low-level and help knowing who maintains what and who did what (it's more as a form of contact).

Folks,

Here's some context on.

First, thank you @anordin95 for this PR and the lovely work to make asyncio more understandable and accessible to users. 💐

The @python/editorial-board made a decision to update the style guide to strongly discourage any new documentation from having an author byline. Over the years, many contributors were discouraged from contributing to documents since the original author rejected pull requests to improve a doc. Since documentation is a community resource, the Editorial Board decided that the bylines discouraged contribution more than encouraged them.

In this particular situation, we definitely want to recognize @anordin95 for his good work. I could see several pathways to do so:

• a seealso block that links out to the external guide which also mentions that the guide inspired the HOWTO. ❤️
• recognition in What's New under documentation
• recognition in a Discourse thread about the availability of the HOWTO

I hope this clarifies the questions here.

P.S. Link to the Editorial Board Changelog

Ok, thanks Carol. I'm personally in favor of the seealso block.

Wow. That was an impressive showing of how to effectively, kindly manage disagreement! Thank you for the context :)

Ah, I see. Bylines can inadvertently embolden some authors to reject otherwise thoughtful, helpful contributions.

I modified to use a seealso block and removed the byline.

Such personalization is discouraged, see this issue

I generally agree that too much personalization or flourish can be distracting, but I think there's a balance to be struck. Sometimes, it can be of great use to the reader. Furthermore, of any place in the docs, I think explainers/HOWTOs are most suited for this kind of writing.

In the issue you referenced, someone also replied to this effect: #62480 (comment)

I agree that "you" adds a nice personal touch to tutorials, but I'll leave it up to the documentation experts.

I was not talking about the „you”, I was instead referring to this:

During my own asyncio learning process, a few aspects particually drove my
curiosity (read: drove me nuts).

Even if for some odd reason we do want to keep this, we should not have an idiom which will be problematic for translators and (as the devguide states, use simple language) readers.

I assume you want to remove the whole sentence, yes? The "odd reason" I think it should be kept is that it adds useful context and relates to the the user; getting confused and even frustrated by asyncio is okay and happened for the author of the article too. A bit of personality can likely help folks feel less intimidated by confusing subjects. And I feel it's a much more natural lead in to the list of learning objectives that follows.

Similarly I think something is lost when removing a bit of humor -- "(read: drove me nuts)", but I hear you on translation difficulties. I could replace it with something more straightforward like: "(read: confused the heck out of me)".

I think this has been addressed. For reference, here's the new text:

"You might be curious about some key asyncio concepts.
You'll be comfortably able to answer these questions by the end of this
article."

This comment has yet to be addressed.

Minor, but instead of the word "article", let's use "page".

Or “HOWTO,” since that is specifically what it is? That is what the Unicode HOWTO does, for example.

"HOWTO" is screaming at me a little too much. I like "page".

I'm actually a little hesitant. I think "article" emphasizes the style of writing and expected reading approach. Whereas "page" is much closer to other forms of documentation where you typically just jump to whatever you're looking for rather than reading each sentence one after the next.

Building on Stan's idea, I lean towards something like:

"This HOWTO article ..."

Which also gives a reference to the other HOWTO's.

Edit: Could also lowercase the howto, but that might be confused with how-to style articles which are a different part of the Diataxis documentation framework. And the link might make clearer that the reader is not being screamed at, but introduced to a quirky descriptor.

I see Peters point¹, I think linking is overkill, however. This is what Unicode has:

This HOWTO discusses Python’s support for the Unicode specification for representing textual data

I actually rather like the link. I wasn't aware Python even had this style of documentation (or that other HOWTOs already existed), despite having used the language for over 10 years, until I submitted the Github Issue a week ago. I think the kind of person who likes fundamental explainers is going to be happy to find more!

I think I suggested this before but the commit may have been lost:

I purposely held off linking to await until the await section which comes next. With that in mind, what do you think of leaving this as is?

I'd like to include the reference. The user doesn't have to click on it, but they can if they want some more general information rather than information suited for an asyncio tutorial.

Ok. Done 👍

This item should follow the argparse-tutorial. The section is alphabetized by standard library topic.

I agree re: alphabetization. But these are rendered without the dashes and become "A Conceptual..." and "Annotations..."

I think it was this way originally. If I recall correctly @ZeroIntensity suggested the switch. I now actually have a slight preference for awaited too, but I don't feel very strongly. Y'all should decide.

My original suggestion was to remove the dash from "await-ed". No preference from me on whether await should be in a code block.

Oh, shoot. My bad!

Turns out the only impediment was my bad memory lol. Will move the various occurrences out of code blocks 👍

I’m not a fan of this since when translating most languages will have to restructure the sentence to preserve the keyword.

@StanFromIreland Do you prefer keeping the backticks? I don't feel that strongly about it. If maintaining the backticks works better for translations, I'm cool with keeping them.

My apologies, my comment is not very clear. I am referring to the existing one with the backticks, since it can not be translated, and it is part of the sentence, it will not make sense in another language. The translator will either have to restructure the sentence to make it somewhat work, or juggle it around (e.g. in parenthesis) as they won't want to remove it. Your suggestion is simpler to translate.

So to be clear, we are removing the backticks. Correct?

(Apologies again, I should work on my clarity) Yes, I am in favour of removing them.