asyncio.iscoroutine() documentation is wrong

[abcd]

BPO	34802
Nosy	@asvetlov, @1st1, @miss-islington, @tirkarthi
PRs	bpo-34802: Fix asyncio.iscoroutine() docs #9611 [3.7] bpo-34802: Fix asyncio.iscoroutine() docs (GH-9611) #9612 bpo-34802: Fix docs for asyncio.iscoroutinefunction #9625

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2018-09-27.19:57:08.414>
created_at = <Date 2018-09-25.20:32:06.346>
labels = ['3.8', 'docs', '3.7', 'expert-asyncio']
title = 'asyncio.iscoroutine() documentation is wrong'
updated_at = <Date 2018-09-28.16:21:38.046>
user = 'https://bugs.python.org/abcd'

bugs.python.org fields:

activity = <Date 2018-09-28.16:21:38.046>
actor = 'yselivanov'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-09-27.19:57:08.414>
closer = 'yselivanov'
components = ['Documentation', 'asyncio']
creation = <Date 2018-09-25.20:32:06.346>
creator = 'abcd'
dependencies = []
files = []
hgrepos = []
issue_num = 34802
keywords = ['patch']
message_count = 6.0
messages = ['326404', '326415', '326587', '326588', '326589', '326591']
nosy_count = 6.0
nosy_names = ['asvetlov', 'docs@python', 'yselivanov', 'miss-islington', 'xtreak', 'abcd']
pr_nums = ['9611', '9612', '9625']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue34802'
versions = ['Python 3.7', 'Python 3.8']

[abcd]

The documentation states that "This method is different from inspect.iscoroutine() because it returns True for generator-based coroutines decorated with @coroutine."

It seems to be wrong, a method written as follow:

def test(): yield 1

will be evaluated as a coroutine by asyncio.iscoroutine(), even if not decorated. The old doc stated "Return True if obj is a coroutine object, which may be based on a generator or an async def coroutine.", which seems more correct.

[tirkarthi]

Thanks for the report. I believe this was done as part asyncio docs overhaul and I am adding Yury here. The current docs link to #coroutine from asyncio.iscoroutine whereas the previous docs had the definition inline. I think this is clarified in #awaitables section but takes a round-trip and it's not in #coroutines section which is linked in asyncio.iscoroutine. The below is present in important note in #awaitables and may be this can be added to #coroutine too so that it's not last? Suggestions welcome

asyncio also supports legacy generator-based coroutines

I would suggest below for #coroutines :

Coroutines declared with async/await syntax is the preferred way of writing asyncio applications but asyncio also supports legacy generator-based coroutines.

Thanks

[1st1]

I'll make a simple fix for the asyncio.coroutine decorator docs.

I would suggest below for #coroutines :

> Coroutines declared with async/await syntax is the preferred way of writing asyncio applications but asyncio also supports legacy generator-based coroutines.

I don't want to further emphasize generator-based coroutines beyond how they are covered right now. We'll drop support for them in a just a couple of versions anyways.

[1st1]

New changeset 59ee5b1 by Yury Selivanov in branch 'master':
bpo-34802: Fix asyncio.iscoroutine() docs (GH-9611)
59ee5b1

[miss-islington]

New changeset 85ccedc by Miss Islington (bot) in branch '3.7':
bpo-34802: Fix asyncio.iscoroutine() docs (GH-9611)
85ccedc

[abcd]

I think it's much clearer