classification
Title: Use async/await through asyncio docs
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.6
process
Status: closed Resolution: wont fix
Dependencies: Superseder:
Assigned To: docs@python Nosy List: asvetlov, brett.cannon, docs@python, ezio.melotti, giampaolo.rodola, gvanrossum, pitrou, vstinner, yselivanov
Priority: normal Keywords: easy

Created on 2015-10-28 22:30 by brett.cannon, last changed 2015-10-29 20:34 by brett.cannon. This issue is now closed.

Messages (6)
msg253636 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2015-10-28 22:30
The asyncio docs still use `yield from` and @asyncio.coroutine all over the place instead of async/await. It would be best to update the docs to follow best practices (unless there is some reason I can't think of as to why this hasn't happened yet).
msg253641 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2015-10-28 23:13
It makes it more awkward to keep the asyncio docs in sync between 3.4 and 3.5. Also it makes copying examples harder for users who need compatibility with 3.4 or 3.3.
msg253644 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2015-10-28 23:49
Also sphinx (pygments actually) still do not support async/await syntax highlighting yet.
msg253645 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2015-10-28 23:56
We have dropped 3.3 in aiohttp BTW.
Proper handling of resource leaks is too annoying without PEP 442 which don't crash with core dump starting from Python 3.4.1
msg253684 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2015-10-29 16:27
Once 3.4.4 launches the need to keep the docs synced with a version that doesn't support async/await goes away. And worrying about 3.3 isn't necessary since asyncio was added in 3.4.

So once 3.4.4 is released and we close the 3.4 branch to bugfixes can we update the docs in asyncio and add a note at the top saying the examples all use async/await from 3.5 and if you need 3.4 compatibility to please look at the 3.4 docs? Otherwise how long do you want to wait until we can start using async/await in the documentation? My worry is that people are going to blindly copy the examples and tweak them for their needs since the asyncio docs are a bit dense and thus just simply overlook the fact that async/await exists.
msg253692 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2015-10-29 20:12
Honestly I think it's better if most people keep using coroutine/yield-from instead of async/await for a few more releases; their code will be more portable, since it takes forever to update old datacenters. We put in async/await with an eye towards the future. But we're keeping yield-from around for a long time too. And that's also why we support asyncio for 3.3.
History
Date User Action Args
2015-10-29 20:34:26brett.cannonsetstatus: open -> closed
resolution: wont fix
2015-10-29 20:12:28gvanrossumsetmessages: + msg253692
2015-10-29 16:27:27brett.cannonsetmessages: + msg253684
2015-10-28 23:56:24asvetlovsetmessages: + msg253645
2015-10-28 23:49:19asvetlovsetnosy: + asvetlov
messages: + msg253644
2015-10-28 23:13:11gvanrossumsetmessages: + msg253641
2015-10-28 22:31:36ezio.melottisetkeywords: + easy
nosy: + ezio.melotti
type: enhancement
2015-10-28 22:30:53brett.cannoncreate