classification
Title: doc for BaseEventLoop.run_in_executor() says its a coroutine, but it is not
Type: enhancement Stage: resolved
Components: asyncio Versions: Python 3.6, Python 3.4, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: asvetlov, ealfie, gilgamezh, gvanrossum, ikelly, vstinner, yselivanov
Priority: low Keywords: easy

Created on 2015-11-19 21:56 by ealfie, last changed 2017-12-20 21:09 by asvetlov. This issue is now closed.

Messages (3)
msg254939 - (view) Author: Ezequiel Alfie (ealfie) Date: 2015-11-19 21:56
Doc says:

coroutine BaseEventLoop.run_in_executor(executor, func, *args)
...<more lines>...
    This method is a coroutine.

However, inspecting the code, I find that this function is not a coroutine. Also this function returns a Future instance, this fact should be mentioned in the doc.
msg259035 - (view) Author: Ian Kelly (ikelly) Date: 2016-01-27 17:21
The asyncio docs also have this note, so this is technically not a bug:

Note: In this documentation, some methods are documented as coroutines, even if they are plain Python functions returning a Future. This is intentional to have a freedom of tweaking the implementation of these functions in the future. If such a function is needed to be used in a callback-style code, wrap its result with ensure_future().

Since the intention seems to be to document something that can be awaited without specifying the implementation, I think that these functions should be documented as returning awaitables. However GvR in python-ideas said:

IMO [the docs] should be very clear about the distinction between functions that return Futures and functions that return coroutines (of either kind). I think it's fine if they are fuzzy about whether the latter return a PEP 492 style coroutine (i.e. defined with async def) or a pre-PEP-492 coroutine (marked with @asyncio.coroutine), since those are almost entirely interchangeable, and the plan is to eventually make everything a PEP 492 coroutine.

Source: http://thread.gmane.org/gmane.comp.python.ideas/38045/focus=38046
msg308816 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2017-12-20 21:09
It was always awaitable object, in Python 3.7 the method was converted into genuine coroutine.
History
Date User Action Args
2017-12-20 21:09:25asvetlovsetstatus: open -> closed
resolution: fixed
stage: resolved
2017-12-20 21:09:08asvetlovsetnosy: + asvetlov
messages: + msg308816
2016-01-27 17:21:31ikellysetnosy: + ikelly
messages: + msg259035
2015-11-19 22:02:49gilgamezhsetnosy: + gilgamezh
2015-11-19 22:01:24gvanrossumsetkeywords: + easy
priority: normal -> low
2015-11-19 21:56:01ealfiecreate