> On Oct 30, 2016, at 1:58 PM, Guido van Rossum <gu...@python.org> wrote: > > Regarding the documentation, I doubt we can get it in shape just by > filing issues. We should really just have a tutorial written by > someone with a good understanding of asyncio and writing skills.
Yeah, I agree. I don’t want to promise anything, but this is something I wanted to do for a long time now. If no one tackles this in the next couple of months, I’ll try to start the process myself. > > I wonder how enlightening the chapter by A. Jesse Jiryu Davis here > really is for beginners? > http://aosabook.org/en/500L/a-web-crawler-with-asyncio-coroutines.html > (my name is on it because I wrote the original code -- Jesse wrote all > the text and rewrote the code several times over :-). I think it’s an excellent piece, but maybe it’s a tad more detailed than what we need for asyncio docs. IMO the opening page of asyncio docs should cover the following: 1. Why asyncio - one paragraph. 2. What is event loop - one p. 3. What is a coroutine - one p. 4. asyncio essentials: get_event_loop, run_until_complete, close, create_task, gather, open_connection, start_server. 5. Advanced topics: should I pass event loop explicitly? etc Speaking about APIs and passing working with the loop. One thing that people find attractive in curio is that it doesn’t really focus on the loop. You start your initial coroutine with the loop (called “kernel” in curio) and that’s it. What if we could do the following: 1. Provide an “asyncio.run(coro)” function to run your "main()” coroutine program and take care of everything loop-related for you. “asyncio.run” should create the loop, run the coroutine, cleanup asynchronous generators and unfinished tasks, close the loop etc. 2. There are some APIs that can’t be called without a loop: run_in_executor, sockets ops etc. What if we add “asyncio.run_in_background” coroutine that would get the event loop and call run_in_executor on it? 3. In 3.7 we can add a Socket-like object with asynchronous “recv”, “send”, etc coroutines. Turns out people want this, as it’s more convenient to use than loop.sock_sendall. Using streams is of course better, but sometimes you want to quickly make your existing program async without a full rewrite. Guido, what do you think? Yury
