Make asyncio methods documented as coroutines - coroutines.

[1st1]

BPO	32327
Nosy	@asvetlov, @1st1
PRs	bpo-32327: Convert asyncio functions documented as coroutines to coroutines. #4872 bpo-32327: Fix check for run_in_executor on closed loop #4996 bpo-32327: Revert loop.run_in_executor behaviour: return a Future. #5392

^{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 = 'https://github.com/1st1'
closed_at = <Date 2017-12-15.01:53:44.371>
created_at = <Date 2017-12-14.20:58:58.531>
labels = ['3.7', 'expert-asyncio']
title = 'Make asyncio methods documented as coroutines - coroutines.'
updated_at = <Date 2018-01-28.19:09:42.262>
user = 'https://github.com/1st1'

bugs.python.org fields:

activity = <Date 2018-01-28.19:09:42.262>
actor = 'yselivanov'
assignee = 'yselivanov'
closed = True
closed_date = <Date 2017-12-15.01:53:44.371>
closer = 'yselivanov'
components = ['asyncio']
creation = <Date 2017-12-14.20:58:58.531>
creator = 'yselivanov'
dependencies = []
files = []
hgrepos = []
issue_num = 32327
keywords = ['patch']
message_count = 3.0
messages = ['308339', '308360', '310981']
nosy_count = 2.0
nosy_names = ['asvetlov', 'yselivanov']
pr_nums = ['4872', '4996', '5392']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue32327'
versions = ['Python 3.7']

[1st1]

There's a handful of event loop methods that are currently documented as coroutines, but in reality they return asyncio.Future:

• loop.sock_sendall,
• loop.sock_accept,
• loop.sock_recv, and
• loop.run_in_executor.

These methods need to become proper coroutines beacause:

1. loop.create_task(loop.sock_recv(..)) fails with a cryptic error.

2. It's harder for us to refactor the code keeping these functions as regular functions returning Futures. Once asyncio was broken because of the bug in loop.sock_connect() because of a complex refactoring. After we converted it to a coroutine in 3.6, we received 0 complaints, but the code became simpler.

3. It's easier to read the source code of asyncio, when all methods that are documented as coroutines are actually coroutines.

4. This downgrades the role of 'asyncio.ensure_future()' function. Basically, when a user needs a task, they can now use create_task() (which won't fail on some "coroutines" sometimes). asyncio users will be advised to design APIs in their programs and libraries around async/await and not Future objects.

[1st1]

New changeset 19a44f6 by Yury Selivanov in branch 'master':
bpo-32327: Convert asyncio functions documented as coroutines to coroutines. (bpo-4872)
19a44f6

[1st1]

New changeset bec2372 by Yury Selivanov in branch 'master':
bpo-32327: Revert loop.run_in_executor behaviour: return a Future. (bpo-5392)
bec2372