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 <ba...@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@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)
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
