It is very important when using a callable to know whether it is async or not. It is expected that builtins.help function should provide the information needed to properly use the function, but it omits whether it is an async function or not.

import asyncio

def the_answer():
	return 42

async def the_answer2():
	await asyncio.sleep(100)
	return the_answer()

>>> help(the_answer)
Help on function the_answer in module __main__:

the_answer()

>>> help(the_answer2)
Help on function the_answer2 in module __main__:

the_answer2()

Note there is no way to tell whether the result of the function needs to be awaited.

In the similar case of generator functions versus regular functions, one obvious solution is to add a type annotation. That doesn't work here, since PEP-0484 indicates that the correct annotation for a coroutine function is the type that is awaited, not the coroutine object created when the function is called.

import typing
def non_answers() -> typing.Iterable[int]:
    yield from range(42)

>>> help(non_answers)
Help on function non_answers in module __main__:

non_answers() -> Iterable[int]

One awkward workaround is to wrap the coroutine function in a regular function:

def the_answer3() -> typing.Awaitable[int]:
    return the_answer2()

>>> help(the_answer3)
Help on function the_answer3 in module __main__:

the_answer3() -> Awaitable[int]

This would be a reasonable addition to help(). Would you like to make a PR?

An "async def" can be detected with inspect.iscoroutinefunction(the_answer2).

Thanks for the suggestion, Raymond. I was toying with the idea of a PR, but wasn’t sure what the resolution should be, and it’s a rather subtle decision for my first contribution.

It seems to me that this might be an oversight in PEP-0484, and the purest resolution is that either Generator and Coroutine should both be part of the type signature or neither should be.

If the PEP is indeed correct, the help output *could* look like:

async the_answer2() -> int

Which would be equivalent to the (functionally identical) wrapper:

the_answer3() -> Awaitable[int]

Philosophically, does asyncness belong on the left or right of the arrow? Should it change just because of how the function is expressed?

Note to future self: whatever solution should also play nice with functools.partial

New changeset 2a37f8f by Miss Islington (bot) (Dan Rose) in branch 'master':
bpo-36045: builtins.help() now prefixes async for async functions (GH-12010)
2a37f8f