I like this, great job!


Couple of thoughts on how we should organize this:

* I think we should stick to your structure and push things to docs.python.org as soon as every next section is somewhat ready.

* Every big section should probably have its own page, linking prev/next tutorial pages.

* I'd organize the tutorial in a dedicated directory like "Doc/library/asyncio-tutorial/".  Context: I wanted to reorganize all current "Doc/library/asyncio*.rst" files under one dir too, but decided to keep the existing file structure to avoid breaking links to the docs from SO/google).  We shouldn't repeat that mistake again.

BTW, maybe we should consider using the new iPythonn async repl: https://blog.jupyter.org/ipython-7-0-async-repl-a35ce050f7f7   What do you think about that?


Some comments on the proposed TOC:

>    - Reason #1: thread safety by not using threads at all.
>    - Reason #2: very many concurrent socket connections, which threads
>      make cumbersome.

This section is super important to get right, as I see people ask the "why and where should I use asyncio" _all_ _the_ _time_.  So I'll expand on this section in a detail.

Reason #1 and #2 are correct, but I think we should really focus on making #1 comprehensive and clear:

* async/await makes all context switches visible; that makes it easy to spot race conditions and reason about your code (think about ORMs that can make 100s of queries to render one web page); you've likely seen https://glyph.twistedmatrix.com/2014/02/unyielding.html

* in general, all datastructures are safe for async (we cannot say same for threads);

* an async/await library means that it's safe to use it in concurrent async/await code (you can never be sure if some library is thread-safe, even if it claims that);

* language constructs like 'async for' and 'async with' enable structured concurrency;

And on #2:

* high-throughput IO or 1000s of long-living connections are only doable with asyncio

* if you don't need to scale your code right now but might need in near future investing in async/await is wise


>- How to run `async def` functions
>    - point out there are two different issues: (a) `async def` functions
>      can call other functions, and other `async def` functions using
>      `await`, but also, (b) how to "get started" with the first
>      `async def` function? Answer: run the event loop.

Just a quick note: I'd try to not mention the low-level loop APIs as long as possible (e.g. no loop.run_until_complete() etc).


- Dealing with concurrent functions
    - (This is maybe too similar to the new docs in the section
      https://docs.python.org/3/library/asyncio-task.html?highlight=asyncio%20run#coroutines-and-tasks)

Right, we'll need to update the asyncio-task.rst file.  I think we'll collapse first two section into one ("Coroutines" and "Awaitables" into "Awaitables") and link the tutorial from that new section.


> - Case Study: chat server/client (my proposal)
> [..]
>     - server uses streams API

Yay for streams!

> [..]
>     - client implementation has some options:

I never use tkinter myself :( I remember trying to use it and it didn't work on my macOS.  So I'd try to either:

* build a simple browser app (that would require us to implement HTTP 0.9 which can be fun);
* build a terminal app;
* use iPython repl to connect to our asyncio server (might end up being more complicated than the first two options).