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).

Hm. @Dreamsorcerer, I'm not sure I totally follow. Let me make sure I understand!

It sounds like synchronous execution of await coroutine wasn't an explicit design goal. But moreso a side effect of building the coroutine functionality on top of yield from. Or, is there some upside to that design which I'm not seeing?

I don't know about explicit design, I wasn't involved. But, I assume this is related to how it was implemented (i.e. using generators and yield from). I don't think tasks existed originally, so that element was added later.

The upside is probably performance, I suspect asyncio would be a lot slower if we yielded to the event loop on every single coroutine (think that a single await in your code may result in several nested awaits through the call stack before reaching a coroutine that is actually meant to yield).

We actually have micro-optimisations in aiohttp where we avoid scheduling a task if we expect it to resolve without delay.

Ahhhh!! I initially figured performance wouldn't be a huge deal, but I hadn't really thought through the extent of deeply nested tasks vs. coros. Gosh that's been bugging me for a while. Thank you :)

I set up a harness to verify. The jist of it is below. One is coroutines all the way down, the other Tasks.

async def coro5(x: int):
    return x + 1
...
async def coro2(x: int):
    return await coro3(x) + 1
async def coro1(x: int):
    return await coro2(x) + 1

async def main():
    for _ in range(10_000):
        output = await coro1(7)
    return output

Time elapsed for the coroutine approach: 0.00419s.
Time elapsed for the Task approach: 1.48859s.

https://github.com/anordin95/a-conceptual-overview-of-asyncio/blob/20fe2ddbb375e55cc9e835fa3239cfc1ffc4ec68/hypotheses/9-await-perf-coro.py#L4-L22
https://github.com/anordin95/a-conceptual-overview-of-asyncio/blob/20fe2ddbb375e55cc9e835fa3239cfc1ffc4ec68/hypotheses/10-await-perf-task.py#L4-L22

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.

I'm going to point out some minor clarifications, feel free to disregard if you don't think it's appropriate in these docs:

It would be more accurate here to say that any code can queue a job, including third-party libraries etc.

Strictly speaking, it's not quite a simple queue. Maybe this only matters to low-level asyncio developers though, and general users don't need to understand the difference.

If I remember correctly, essentially, when tasks are being added, they get added to a list of tasks to be run on the next loop cycle. Once all tasks in the current list have been iterated through once (with incomplete tasks getting re-added to the next cycle's list), only then does it move to the next loop cycle, and create a new list for a future cycle.

This is probably roughly the same as the comment below: https://github.com/python/cpython/pull/137215/files#r2250000716

Typically we use asyncio.run(), so the loop continues until that task completes, not indefinitely.

I also don't think the loop cycles aimlessly, the application would basically sleep. e.g. If all your tasks are waiting on I/O (so there are no tasks queued), then it uses the OS's select() call (on the selector event loop) to tell the OS to wake it up when it's received data on those sockets. When it wakes up, it will reschedule the tasks associated with those sockets and run another cycle.

I would suggest we don't use the low-level APIs here if we're trying to teach users the correct way to utilise asyncio.

I like the clarity that this explicit approach provides. I think it helps users gain a broader understanding. But I hear you on also showing the suggested API usage. I've added a chunk to this effect in the Tasks section:

Earlier, we manually created the event loop and set it to run forever.
In practice, it's recommended to use (and common to see) :func:asyncio.run,
which takes care of managing the event loop and ensuring the provided
coroutine finishes before advancing.
For example, many async programs follow this setup::

   import asyncio

   async def main():
       ...

   if __name__ == "__main__":
       asyncio.run(main())
       # The program will not reach the following print statement until the
       # coroutine main() finishes.
       print("coroutine main() is done!")

I like the clarity that this explicit approach provides. I think it helps users gain a broader understanding.

I'll leave it to you, but personally I don't really understand what it's trying to explain.

Technically, as per my comment above, the comment here is not entirely accurate. This code in it's current state, creates an event loop and starts the first cycle of the loop and then basically sleeps indefinitely as I understand it. It does not cycle indefinitely, because there is no code that could cause it to move on to a second cycle.

I like the clarity that this explicit approach provides. I think it helps users gain a broader understanding. But I hear you on also showing the suggested API usage. I've added a chunk to this effect in the Tasks section:

For new docs, you should use asyncio.run or asyncio.Runner as the runner, -1 on using older APIs which are hard to use correctly.

I also like how mentioning the queue subtly reinforces the idea that execution is serial (i.e. not parallel).

I would additionally say that it's useful to understand that the order of execution is predictable. Many users are under the impression that "scheduled" means unpredictable order of execution. The tasks should start executing in the order they've been added.

It's essentially syntactic sugar for yield from (which was the actual syntax used in Python 3.4).

This is mentioned later.

Yeah, I guess to me this should just point to yield from in the docs elsewhere, rather than re-explaining how it works. But, probably doesn't matter much.

Curiously, I don't have permissions to resolve my own comments here...

I think it's useful to understand how it works, but I'd probably rename the header to something like "How coroutines work under-the-hood".

I use similar examples for talks explaining how asyncio works, where I start by showing the more complex things that can be done with generators (that many developers are unaware of) and end up with a very simplistic approximation of an event loop, without using any async/await syntax. (I use the functions interactively in a talk, but the code examples are at: https://gist.github.com/Dreamsorcerer/5c0ddafae6eed073a90cf52fd7cfaede)

By using generators alone with no actual asyncio code though, I think I avoid misleading anybody in thinking that the syntax they see is the appropriate way to write asyncio (which I cover with a couple of points at the end with actual asyncio examples).

It's probably worth an example of why this might be a problem and how to deal with it?

For example, if you await on things which don't yield or are processing some CPU-intensive data, you may need to add await asyncio.sleep(0) to the code to ensure the code does yield back to the event loop in a reasonable amount of time.

Additionally on that, it might be worth mentioning the debug features of asyncio, such as the ability to log anything that blocks the loop for more than (by default) 100ms.

Hm, yeah. Good callout! Lemme stew on this a bit.