[Python-Dev] async/await behavior on multiple calls

[Nick Coghlan]

On 16 December 2015 at 11:41, Barry Warsaw <barry at python.org> wrote:
> The asyncio library documentation *really* needs a good overview and/or
> tutorial.  These are difficult concepts to understand and it seems like
> bringing experience from other languages may not help (and may even hinder)
> understanding of Python's model.  After a while, you get it, but I think it
> would be good to help folks get there sooner, especially if you're new to the
> whole area.
>
> Maybe those of you who have been steeped in asyncio for a long time could
> write that up?  I don't think I'm the right person to do that, but I'd be very
> happy to review it.

One smaller step that may be helpful is changing the titles of a
couple of the sections from:

* 18.5.4. Transports and protocols (low-level API)
* 18.5.5. Streams (high-level API)

to:

* 18.5.4. Transports and protocols (callback based API)
* 18.5.5. Streams (coroutine based API)

That's based on a sample size of one though (a friend for whom light
dawned once I explained that low-level=callbacks and
high-level=coroutines), which is why I hadn't written a patch for it.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia