Showing content from http://mail.python.org/pipermail/python-dev/attachments/20150928/1afc0b0d/attachment.html below:
<div dir="ltr">Your comments make total sense -- we're just short on people who can write that kind of docs. :-(<br></div><div class="gmail_extra"><br><div class="gmail_quote">On Mon, Sep 28, 2015 at 2:15 PM, Barry Warsaw <span dir="ltr"><<a href="mailto:barry@python.org" target="_blank">barry@python.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">On Sep 28, 2015, at 08:22 AM, Guido van Rossum wrote:<br>
<br>
>I saw that you had a need for an asyncio tutorial. I wonder if the "500<br>
>lines" chapter on asyncio would help? I didn't write it; I only write the<br>
>500 lines of code, A. Jesse Jiryu Davis wrote the text, and it's wonderful:<br>
><a href="http://aosabook.org/en/500L/a-web-crawler-with-asyncio-coroutines.html" rel="noreferrer" target="_blank">http://aosabook.org/en/500L/a-web-crawler-with-asyncio-coroutines.html</a><br>
<br>
</span>It's a great article, and I particularly like how it starts from first<br>
principles and builds essentially the asyncio framework up from them, with<br>
nice explorations on how things like generators work.<br>
<br>
But it's not quite what I'm looking for. When I go to the stdlib asyncio docs<br>
page, I'm immediately thrown into (albeit good) reference documentation. I<br>
though that the page "Develop with asyncio" might give me what I want, but<br>
it's really not.<br>
<br>
What I'm looking for is a gentle introduction, assuming that the reader either<br>
understands the basics of asynchronous i/o or maybe comes from a background in<br>
threaded programming. It would then explain things like "this is a Future and<br>
this is what you use it for", "this is a Task and this is when you use a Task<br>
and when you use a Future", "this is when you want to define a Protocol, and<br>
this is how it hooks into the framework". I think that kind of high-level<br>
overview of the classes and how they hang together is what I think is missing.<br>
<br>
Take for example 18.5.3 Tasks and coroutines. Aside from the fact that the<br>
title would imply it would start explaining Tasks, it actually doesn't get to<br>
them until way later on the page!<br>
<br>
What's a Future? The first thing the asyncio page says is that the "class is<br>
almost compatible with concurrent.futures.Future". Okay, but that still<br>
doesn't tell me what it *is* or what it's used for. Following the link to<br>
that other class isn't really enlightening. ;)<br>
<br>
I hope my comments make sense. I know that when you already understand the<br>
concepts, it's difficult to distill them into the right documentation for very<br>
different audiences. What's there seems mostly great for reference, and maybe<br>
the stdlib docs aren't the right place for what I want, but as the 500 Lines<br>
chapter promotes, asyncio is pretty powerful so it would be nice to have<br>
Python documentation for newcomers.<br>
<br>
I'm sure I'm not the right person to write it though. ;)<br>
<br>
Cheers,<br>
-Barry<br>
<br>_______________________________________________<br>
Python-Dev mailing list<br>
<a href="mailto:Python-Dev@python.org">Python-Dev@python.org</a><br>
<a href="https://mail.python.org/mailman/listinfo/python-dev" rel="noreferrer" target="_blank">https://mail.python.org/mailman/listinfo/python-dev</a><br>
Unsubscribe: <a href="https://mail.python.org/mailman/options/python-dev/guido%40python.org" rel="noreferrer" target="_blank">https://mail.python.org/mailman/options/python-dev/guido%40python.org</a><br>
<br></blockquote></div><br><br clear="all"><br>-- <br><div class="gmail_signature">--Guido van Rossum (<a href="http://python.org/~guido" target="_blank">python.org/~guido</a>)</div>
</div>
RetroSearch is an open source project built by @garambo
| Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4