Since issue34616 is merged that allows using compile flags to support top level await statements I think it would be good to add support for top level await in doctest. This would help in concise examples in docs where await statements need to be wrapped in async def wrapper functions currently. This can be done using a doctest flag like ALLOW_TOP_LEVEL_AWAIT so that places where top level await is needed it can be explicitly marked as such so that when users copy paste code they are aware that it requires top level await statement.

I have implemented a simple patch where ALLOW_TOP_LEVEL_AWAIT flag (not to be confused with ast module flag) is added to doctest and if the doctest line has the flag then the ast flag is added th compileflags and then await eval(code_object) is used and then the awaitabe is executed with asyncio.run. Synchronous code has usual exec(code_object). I don't see any doctest failures with this patch against our Doc folder and test_doctest.

Few downsides is that it requires ast import for the flag value which could be little heavy but inspect module is already imported and I think it's an okay tradeoff for doctest. I have used asyncio.run and I am not sure if there is an efficient way to run awaitables. Feedback welcome.

Patch : https://github.com/python/cpython/compare/master...tirkarthi:asyncio-await-doctest

# await_flag_doctest.rst
>>> import asyncio
>>> await asyncio.sleep(1.0)  # doctest: +ALLOW_TOP_LEVEL_AWAIT

cpython git:(asyncio-await-doctest)   time ./python.exe -m doctest await_flag_doctest.rst
./python.exe -m doctest await_flag_doctest.rst  0.31s user 0.02s system 24% cpu 1.343 total

# await_no_flag_doctest.rst that will fail
>>> import asyncio
>>> await asyncio.sleep(1.0)

cpython git:(asyncio-await-doctest)   time ./python.exe -m doctest await_no_flag_doctest.rst
**********************************************************************
File "await_no_flag_doctest.rst", line 2, in await_no_flag_doctest.rst
Failed example:
    await asyncio.sleep(1.0)
Exception raised:
    Traceback (most recent call last):
      File "/Users/karthikeyansingaravelan/stuff/python/cpython/Lib/doctest.py", line 1338, in __run
        code = compile(example.source, filename, "single",
      File "<doctest await_no_flag_doctest.rst[1]>", line 1
    SyntaxError: 'await' outside function
**********************************************************************
1 items had failures:
   1 of   2 in await_no_flag_doctest.rst
***Test Failed*** 1 failures.
./python.exe -m doctest await_no_flag_doctest.rst  0.35s user 0.03s system 94% cpu 0.393 total