bpo-36045: builtins.help() now prefixes async for async functions

[rotu]

Previously, it was hard to tell whether a function should be awaited. It was also incorrect (per PEP 484) to put this in the type hint for coroutine functions. Added this info to the output of builtins.help and pydoc.

https://bugs.python.org/issue36045

[the-knights-who-say-ni]

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept your contribution by verifying you have signed the PSF contributor agreement (CLA).

Unfortunately we couldn't find an account corresponding to your GitHub username on bugs.python.org (b.p.o) to verify you have signed the CLA (this might be simply due to a missing "GitHub Name" entry in your b.p.o account settings). This is necessary for legal reasons before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

You can check yourself to see if the CLA has been received.

Thanks again for your contribution, we look forward to reviewing it!

[rotu]

Signed CLA

[asvetlov]

Please add news entry

[rotu]

I'm still not 100% confident I made the right call here in prefixing async generator functions with "async" in the output of help.

pros:

• You need to be in an async context to use them
• They are spelled with a leading async def, so it mirrors the syntax of the language

cons:

• This creates an ambiguity where you can't tell if async def iter_something() is an async function returning an iterable or an async generator function
• A type annotation is both redundant and ambiguous: async def iter_something(): AsyncIterable[...]. Is this a function returning an AsyncIterable or a coroutine function returning an AsyncIterable?

[asvetlov]

We have no prefix for regular generator functions.
I think the same rule is applied to async version.
A plain async function is different: there is a clear vision that the function should be called with await syntax.

[rotu]

We have no prefix for regular generator functions.
I think the same rule is applied to async version.

I'm sorry - I don't think I understand what you are saying. Which same rule is applied?

A plain async function is different: there is a clear vision that the function should be called with await syntax.

Why should await matter in particular? You don't call an async generator with await syntax - you use async for syntax (which also requires you to know the callee is meant to be used asynchronously). In the output of help, "async" just means async def ... was used to declare the callable. You might still need await, even for a regular function, as with def mysleep(): return asyncio.sleep(10).

If upon reading the above, you still feel strongly that async generator functions should not be prefixed with "async", I'll be happy to make that change.

[asvetlov]

Well, I'm ok with the change.
Thank you for your contribution!

[vstinner]

This is a cool change, thanks!