[Python-ideas] Documenting asyncio methods as returning awaitables

[Ian Kelly]

The official asyncio documentation includes this note:

"""
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().
"""

Despite the note, this still causes confusion. See for example
https://mail.python.org/pipermail/python-list/2016-January/702342.html

As of Python 3.5, "awaitable" is a thing, and as of Python 3.5.1,
ensure_future is supposed to accept any awaitable. Would it be better
then to document these methods as returning awaitables rather than as
coroutines?