This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: asyncio support in doctests
Type: behavior Stage: resolved
Components: asyncio, Library (Lib) Versions: Python 3.7
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: Nosy List: Stefan Tjarks, asvetlov, grantjenks, yselivanov
Priority: normal Keywords:

Created on 2018-08-20 17:30 by Stefan Tjarks, last changed 2022-04-11 14:59 by admin. This issue is now closed.

File name Uploaded Description Edit Stefan Tjarks, 2018-08-20 17:30 Reproduceable script
Messages (3)
msg323803 - (view) Author: Stefan Tjarks (Stefan Tjarks) Date: 2018-08-20 17:30
When writing a docstring for an async function I wrote a doctest for it.

async def hello_world():
    Will great the world with a friendly hello.

    >>> await hello_world()
    "hello world"
    return "hello world"

I kind of expected an error that no event loop is running but actually get a SyntaxError.

File "", line 5, in __main__.hello_world
Failed example:
    await hello_world()
Exception raised:
    Traceback (most recent call last):
      File "/usr/lib/python3.6/", line 1330, in __run
        compileflags, 1), test.globs)
      File "<doctest __main__.hello_world[0]>", line 1
        await hello_world()
    SyntaxError: invalid syntax
1 items had failures:
   1 of   1 in __main__.hello_world
***Test Failed*** 1 failures.

Is the SyntaxError intentional or does doctest simply not support asyncio syntax?
msg324398 - (view) Author: Grant Jenks (grantjenks) * Date: 2018-08-30 18:54
This is not a bug in Python. The SyntaxError matches expected behavior. According to the Python grammar, you can't have "await" outside of a function. You have "await" at the globals scope which is not permitted. You may only "await" functions from within other functions.

Doctest is designed to emulate what you would type into the Python shell. Your doctest snippet does not work there either:

$ python3
Python 3.7.0 (default, Jun 28 2018, 05:55:06) 
[Clang 9.1.0 (clang-902.0.39.2)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> async def hello_world():
...     return "Hello, world!"
>>> await hello_world()
  File "<stdin>", line 1
SyntaxError: 'await' outside function

To make your doctests work, use ```` like so:

import asyncio

async def hello_world():
    Will greet the world with a friendly hello.

    'hello world'

    return "hello world"

if __name__ == "__main__":
    import doctest

Stefan, you may get a quicker answer next time from a forum like StackOverflow.

Yury, it's probably a good idea to cover this case in your upcoming asyncio docs improvements.
msg324400 - (view) Author: Stefan Tjarks (Stefan Tjarks) Date: 2018-08-30 20:07
Thanks Grant! I expected that I am missing something.

You are right that I could have posted in many places to get help about this. Before posting I tried to find a doctest for asyncio but my google magic failed me. At the end I just felt that, at the very least, the bug tracker would show that the doctest documentation could be updated to cover this.

That doctest emulate a Python shell helps me understand its limitations a bit more.
Date User Action Args
2022-04-11 14:59:04adminsetgithub: 78626
2018-10-08 16:50:46asvetlovsetstatus: open -> closed
stage: resolved
2018-08-30 20:07:14Stefan Tjarkssetresolution: not a bug
messages: + msg324400
2018-08-30 18:54:26grantjenkssetnosy: + grantjenks
messages: + msg324398
2018-08-20 17:30:39Stefan Tjarkscreate