[docs] [issue33649] asyncio docs overhaul

[Jim DeLaHunt]

Jim DeLaHunt <from.python at jdlh.com> added the comment:

I'm a developer using Python in my application. I just spent the last couple of weeks learning about asyncio with the present documentation. I am very happy to see that work is underway for improved documentation. 

I would be glad to take on writing tasks or to review drafts, if there is a way to plug myself into that work.

I like the general structure. 

Some specific topics which would have helped me in my recent learning:

* As an application developer using an event loop as part of the application, how do I develop a Protocol specific to my app, and use with Streams?  An important part of this is being clear what the interface is between Transport and Protocol. This interface resides in both classes; Protocol calls Transport methods, and Transport calls Protocol methods.

* As an application developer using an event loop as part of the application, how do I develop a Transport specific to my app, and use it with Streams?  (In my case, I have two transports in mind: a file, containing data archived from a TCP network port, and an RS232 serial connection, carrying data that might otherwise be sent via a TCP network port. It seems to me that I should be able at run-time to select from any of those three Transports, and apply my app-specific Protocol when creating my connection.)

* As an application developer, how do I give a function which is not a coroutine to the event loop for scheduling and execution?  (I think the answer is loop.call_soon(), but the docs don't say "to run your function call loop.call_soon(myfunc...)", they say "call_soon(): Arrange for a callback to be called as soon as possible". Not the same thing. And, is a "callback" different "an arbitrary function"? Not clear.)

* As an application developer, how do I make an syncio-based streaming server and streaming client respond cleanly to interrupts, e.g. control-C in a command-line app?  (Existing docs hints at catching signals, but don't show how to combine those with exception handlers in the coroutine to shut down connections cleanly.)

* As a Transport developer, what interface must I provide between Transport and Protocol? What services does the EventLoop provide to help implement my Transport? As mentioned before, to me it looks like the Transport-Protocol interface resides in both classes; Protocol calls Transport methods, and Transport calls Protocol methods.  The EventLoop services useful to Transports are not gathered in a discussion of Transports. There is only an enumeration of the EventLoop methods, regardless of purpose.

Editorial checks I suggest making to the revision:

Rewrite to describe the behaviour in the doc, instead of delegating to a PEP. No more "this class is almost like the thing in PEP xyz, except for these differences". Describe the asyncio class, and steal text from PEP xyz as needed to do that.

Every section about a thing must start by saying what that thing is and what it is used for.  There are some big counterexamples in the current text. 

e.g. "19.5.1.2. Calls" <https://docs.python.org/3/library/asyncio-eventloop.html#calls> starts out with: "Most asyncio functions don’t accept keywords. If you want to pass keywords to your callback, use functools.partial()."  That does not describe what "calls" are, nor what they are used for. And, in this case, a better title might be, "Getting the event loop to call regular functions".

e.g. "19.5.1.4. Futures" <https://docs.python.org/3/library/asyncio-eventloop.html#futures> has no starting text. This is the first heading mentioning Futures when reading sequentially in the asyncio doc, so I interpreted it as a place to learn about Futures. It is not. This section would be better titles "Eventloop methods for Futures". The proposed "Low-level APIs" section might solve this problem by explaining the nature and purpose of Futures before mentioning the EventLoop factory for Futures objects.

Consider separating the explanation of the nature and purpose of a thing from the reference to the methods of the thing. The proposed structure talks about "High-Level APIs" and "Low-Level APIs", but not "Architecture" and "API Reference". I would suggest injecting an "Architecture" section which can give the nature and purpose of each of the public classes in Asyncio, without enumerating their methods. Then the sections labelled "High-Level APIs" and "Low-Level APIs" can be the API reference.

I hope these suggestions are helpful. I'll be monitoring this issue to see how I can help.

----------
nosy: +JDLH

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue33649>
_______________________________________