On 2015-12-16 1:11 AM, Nick Coghlan wrote:
On 16 December 2015 at 11:41, Barry Warsaw <ba...@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.
Nick, I've applied your suggested change in
https://hg.python.org/cpython/rev/f02c61f08333
I think it makes sense, as at least it gives some useful
information about the section. "low-level" and "high-level"
start to mean something when you already understand asyncio
pretty well.
Yury
_______________________________________________
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
