[New-bugs-announce] [issue36045] Help function is not much help with async functions

[Dan Rose]

New submission from Dan Rose <daniel.buchoff at gmail.com>:

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]
```

----------
components: asyncio
messages: 336025
nosy: Dan Rose, asvetlov, yselivanov
priority: normal
severity: normal
status: open
title: Help function is not much help with async functions
versions: Python 3.7

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