< expLog

The Async Keyword

This note is part of a series on asyncio.

The very first change to start using asyncio is to insert the async keyword right in front of the function: but what does that do?

To keep things extremely focused, I'm only going to compare stripped versions of the hello world program:

async def hello_world():
    print("Hello, world")


def sync_hello_world():
    print("Hello, world")

Return values

The more obvious result is that calling the sync function immediately triggers a print, and returns nothing;


calling the async function returns a coroutine object, doesn't print any output (or run the underlying code), and also prints a warning about a coroutine that was never called:



So what makes Python behave so completely differently in this case?


The Python lexer has to deal with a new keyword to parse this variant of hello_world: we can look at it using the ast module.

import ast
import pprint
async def hello_world():
    print("Hello, world!")
("Module(body=[AsyncFunctionDef(name='hello_world', "
 'args=arguments(posonlyargs=[], args=[], kwonlyargs=[], kw_defaults=[], '
 "defaults=[]), body=[Expr(value=Call(func=Name(id='print', ctx=Load()), "
 "args=[Constant(value='Hello, world!')], keywords=[]))], decorator_list=[], "
 'type_params=[])], type_ignores=[])')

The function is explicitly detected as an AsyncFunctionDef to mark the addition of the async tag. 1

We can also look at the disassembly of the function definition to see what happens after compiling it down to bytecode. I've also included a plain function for comparison.

import ast
import dis

code = dis.Bytecode(compile("""
async def async_hello_world():
    print("Async Hello, world!")

def hello_world():
    print("Hello, world!")
""", filename='<string>', mode='exec'))

0           0 RESUME                   0

2           2 LOAD_CONST               0 (<code object async_hello_world at 0x7f0785bd9110, file "<string>", line 2>)
            4 MAKE_FUNCTION            0
            6 STORE_NAME               0 (async_hello_world)

5           8 LOAD_CONST               1 (<code object hello_world at 0x7f0785b11b50, file "<string>", line 5>)
           10 MAKE_FUNCTION            0
           12 STORE_NAME               1 (hello_world)
           14 RETURN_CONST             2 (None)

Surprisingly enough, the generated opcodes for defining the functions are exactly the same. Looking inside the functions themselves also gives the same result.

import dis

async def async_hello_world():
    print("Hello, world!")

def hello_world():
    print("Hello, world!")


  3           0 RETURN_GENERATOR
              2 POP_TOP
              4 RESUME                   0

  4           6 LOAD_GLOBAL              1 (NULL + print)
             16 LOAD_CONST               1 ('Hello, world!')
             18 CALL                     1
             26 POP_TOP
             28 RETURN_CONST             0 (None)
             32 RERAISE                  1
  4 to 28 -> 30 [0] lasti
  6           0 RESUME                   0

  7           2 LOAD_GLOBAL              1 (NULL + print)
             12 LOAD_CONST               1 ('Hello, world!')
             14 CALL                     1
             22 POP_TOP
             24 RETURN_CONST             0 (None)

The only difference is a flag set on the defined code: CO_COROUTINE which makers a function as a coroutine. The actual compiler code is somewhere around here; but it's worth explicitly looking at the flags.

Once more into the breach:

import dis

async def async_hello_world():
    print("Hello, world!")

def hello_world():
    print("Hello, world!")

async_flags = async_hello_world.__code__.co_flags
standard_flags = hello_world.__code__.co_flags

only_async_flags = async_flags & (~standard_flags)
print(f"{only_async_flags=}, aka {dis.COMPILER_FLAG_NAMES[only_async_flags]}")

only_standard_flags = standard_flags & (~async_flags)
only_async_flags=128, aka COROUTINE

And that's the literally the magic bit that makes the difference in how coroutines are evaluated.


Executing an async function doesn't directly run the inner function anymore, and instead returns a a coroutine object that wraps the computation.

Hello, world!



Just for contrast:

import ast
import pprint

def hello_world():
    print("Hello, world!")
("Module(body=[FunctionDef(name='hello_world', args=arguments(posonlyargs=[], "
 'args=[], kwonlyargs=[], kw_defaults=[], defaults=[]), '
 "body=[Expr(value=Call(func=Name(id='print', ctx=Load()), "
 "args=[Constant(value='Hello, world!')], keywords=[]))], decorator_list=[], "
 'type_params=[])], type_ignores=[])')

Normal functions are parsed, unsurprisingly, as FunctionDef.