[issue39085] Improve docs for await expression

[Andrew Svetlov]

Andrew Svetlov <andrew.svetlov at gmail.com> added the comment:

Thanks for raising the very interesting question!

Sorry, my English is bad; I cannot help with docs too much.

Anyway, technically an awaited coroutine *can* be suspended but the suspension is not always necessary. The most deep awaited function decides. 

For example, if you want to read 16 bytes from a stream and these bytes are already fetched there is no suspension at this point  (at least libraries are designed in this way usually).

Also, technical speaking about awaits is hard without telling that a coroutine is a specialized version of generator object with (partially) overlapped methods and properties, e.g. send() and throw().

To run a coroutine you need a framework which calls these methods depending on the framework rules, the rules for asyncio are different from trio.

Not sure how long should be the section but looking on `yield expressions` https://docs.python.org/3/reference/expressions.html#yield-expressions above I expect that awaits can take two-three times longer.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue39085>
_______________________________________