[Python-Dev] Washington DC Python sprint report

[Barry Warsaw]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 819 bytes
Desc: OpenPGP digital signature
URL: <http://mail.python.org/pipermail/python-dev/attachments/20150928/0b026195/attachment-0001.sig>