Author ikelly
Recipients ealfie, gilgamezh, gvanrossum, ikelly, vstinner, yselivanov
Date 2016-01-27.17:21:31
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1453915291.12.0.304098322777.issue25675@psf.upfronthosting.co.za>
In-reply-to
Content
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
History
Date User Action Args
2016-01-27 17:21:31ikellysetrecipients: + ikelly, gvanrossum, vstinner, yselivanov, gilgamezh, ealfie
2016-01-27 17:21:31ikellysetmessageid: <1453915291.12.0.304098322777.issue25675@psf.upfronthosting.co.za>
2016-01-27 17:21:31ikellylinkissue25675 messages
2016-01-27 17:21:31ikellycreate