[Python-Dev] Washington DC Python sprint report (original) (raw)

Guido van Rossum guido at python.org
Mon Sep 28 23:38:10 CEST 2015

Your comments make total sense -- we're just short on people who can write that kind of docs. :-(

On Mon, Sep 28, 2015 at 2:15 PM, Barry Warsaw <barry at python.org> wrote:

On Sep 28, 2015, at 08:22 AM, Guido van Rossum wrote:

>I saw that you had a need for an asyncio tutorial. I wonder if the "500 >lines" chapter on asyncio would help? I didn't write it; I only write the >500 lines of code, A. Jesse Jiryu Davis wrote the text, and it's wonderful: >http://aosabook.org/en/500L/a-web-crawler-with-asyncio-coroutines.html It's a great article, and I particularly like how it starts from first principles and builds essentially the asyncio framework up from them, with nice explorations on how things like generators work. But it's not quite what I'm looking for. When I go to the stdlib asyncio docs page, I'm immediately thrown into (albeit good) reference documentation. I though that the page "Develop with asyncio" might give me what I want, but it's really not. What I'm looking for is a gentle introduction, assuming that the reader either understands the basics of asynchronous i/o or maybe comes from a background in threaded programming. It would then explain things like "this is a Future and this is what you use it for", "this is a Task and this is when you use a Task and when you use a Future", "this is when you want to define a Protocol, and this is how it hooks into the framework". I think that kind of high-level overview of the classes and how they hang together is what I think is missing. Take for example 18.5.3 Tasks and coroutines. Aside from the fact that the title would imply it would start explaining Tasks, it actually doesn't get to them until way later on the page! What's a Future? The first thing the asyncio page says is that the "class is almost compatible with concurrent.futures.Future". Okay, but that still doesn't tell me what it is or what it's used for. Following the link to that other class isn't really enlightening. ;) I hope my comments make sense. I know that when you already understand the concepts, it's difficult to distill them into the right documentation for very different audiences. What's there seems mostly great for reference, and maybe the stdlib docs aren't the right place for what I want, but as the 500 Lines chapter promotes, asyncio is pretty powerful so it would be nice to have Python documentation for newcomers. I'm sure I'm not the right person to write it though. ;) Cheers, -Barry

Python-Dev mailing list Python-Dev at python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/guido%40python.org

-- --Guido van Rossum (python.org/~guido) -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.python.org/pipermail/python-dev/attachments/20150928/1afc0b0d/attachment.html>

More information about the Python-Dev mailing list