classification
Title: builtins.help function is not much help with async functions
Type: enhancement Stage: resolved
Components: asyncio Versions: Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: Dan Rose, asvetlov, eamanu, miss-islington, rhettinger, yselivanov
Priority: normal Keywords: easy, patch

Created on 2019-02-19 23:36 by Dan Rose, last changed 2019-05-24 11:38 by asvetlov. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 12010 merged python-dev, 2019-02-24 06:31
Messages (5)
msg336025 - (view) Author: Dan Rose (Dan Rose) * Date: 2019-02-19 23:36
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]
```
msg336027 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-02-19 23:55
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).
msg336046 - (view) Author: Dan Rose (Dan Rose) * Date: 2019-02-20 07:10
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?
msg336047 - (view) Author: Dan Rose (Dan Rose) * Date: 2019-02-20 07:38
Note to future self: whatever solution should also play nice with functools.partial
msg343376 - (view) Author: miss-islington (miss-islington) Date: 2019-05-24 11:38
New changeset 2a37f8f55b543589cc77a67b5cd17cbd9d0311c9 by Miss Islington (bot) (Dan Rose) in branch 'master':
bpo-36045: builtins.help() now prefixes `async` for async functions (GH-12010)
https://github.com/python/cpython/commit/2a37f8f55b543589cc77a67b5cd17cbd9d0311c9
History
Date User Action Args
2019-05-24 11:38:46asvetlovsetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2019-05-24 11:38:14miss-islingtonsetnosy: + miss-islington
messages: + msg343376
2019-02-24 06:31:46python-devsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request12041
2019-02-20 07:38:48Dan Rosesetmessages: + msg336047
2019-02-20 07:10:16Dan Rosesetmessages: + msg336046
2019-02-20 02:44:52eamanusetnosy: + eamanu
2019-02-19 23:55:41rhettingersettype: enhancement
versions: + Python 3.8, - Python 3.7
keywords: + easy
nosy: + rhettinger

messages: + msg336027
stage: needs patch
2019-02-19 23:39:47Dan Rosesettitle: Help function is not much help with async functions -> builtins.help function is not much help with async functions
2019-02-19 23:36:27Dan Rosecreate