[docs] [issue34701] Asyncio documentation for recursive coroutines is lacking

[Azaria Zornberg]

New submission from Azaria Zornberg <a.zornberg96 at gmail.com>:

When an asynchronous coroutine in asyncio awaits or yields from itself, any call to the function is executed somewhat synchronously.

Once the recursive coroutine begins, if it never awaits any other coroutines besides itself, nothing else will be scheduled to run until it has completely finished recursively calling itself and returning.
However, if it ever awaits a different coroutine (even something as small as asyncio.sleep(0)) then other coroutines will be scheduled to run.

It seems, from other documentation, that this is intentional. Other documentation sort of dances around the specifics of how coroutines work with recursion, and only examples of coroutines yielding from each other recursively are provided.

However, this behavior is never explicitly called out. This is confusing for people who write a recursive asyncio coroutine and are perplexed by why it seems to execute synchronously, assuming they ever notice.

I've attached a short script that can be run to exhibit the behavior.
A PR is going to be filed shortly against the python 3.7 branch (as the documentation page for asyncio in 3.8 does not fully exist right now).

----------
assignee: docs at python
components: Documentation, asyncio
files: asyncio_await_from_self_example.py
messages: 325468
nosy: asvetlov, azaria.zornberg, docs at python, yselivanov
priority: normal
severity: normal
status: open
title: Asyncio documentation for recursive coroutines is lacking
type: enhancement
versions: Python 3.4, Python 3.5, Python 3.6, Python 3.7
Added file: https://bugs.python.org/file47805/asyncio_await_from_self_example.py

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