asyncio, transports, protocols, etc.

[Hugh Sasse]

Hello,
I didn't get a response to this before, possibly because of lack of 
concision.   I'd like to ask whether (provided I'm understanding this):

https://docs.python.org/3/library/asyncio-protocol.html#tcp-echo-server

could be improved by adding:
"""
   Create a TCP echo server using the loop.create_server() method, send
   back received data.  This is done by defining the Protocol, which gets
   the transport from the server when it is created by asyncio.
"""
before it, because these concepts have only just been introduced, and 
also whether the echo server should really be closing the connection, 
given RFC 862 seems to suggest it should stay open.

Original message below.

Thank you,
Hugh


Hello,

I'm trying to get my head around asyncio, and I think I'm mostly there 
now, (but expect to be proved wrong :-)!).  It appears to be about the 
newest of the PEPs according to my searches, including PEP 0, so I don't 
expect a huge amount of supporting documentation out there yet.

Looking at:

https://docs.python.org/3/library/asyncio-protocol.html#tcp-echo-server

I know the page introduces the relationships between protocols, 
transports and the servers/clients that use them.  When I read this code 
it took me longer than I would wish :-) to realise that the example 
defining the Echo server was doing this through the protocol, (yes, it 
says it *right there* :-)!) and not a Server class, so for some time I 
was puzzled about where 'transport' was being defined.  Given these 
concepts are new on this page, at least ostensibly, would it make sense 
to introduce this example with something like:

"""
   Create a TCP echo server using the loop.create_server() method, send
   back received data.  This is done by defining the Protocol, which gets
   the transport from the server when it is created by asyncio.
"""

just to refresh the connection between the things in the mind of the reader?

Also, according to my reading of RFC 862, I don't think the Echo server 
should be closing the connection just after echoing:

"""
TCP Based Echo Service

    One echo service is defined as a connection based application on TCP.
    A server listens for TCP connections on TCP port 7.  Once a
    connection is established any data received is sent back.  This
    continues until the calling user terminates the connection.

"""

I could have missed something here though. (If it is this protocol that
is under discussion here, then a link might be useful, as well?)

Why does this matter?  Because it was not clear to me whether the 
closing of the connection was something that had to happen, as part of 
the functionality of the echo service or of asyncio itself.  If I'm 
implementing something that does something based on the cmd or cmd2 
module, interpreting commands, then having some kind of dialogue with 
the server matters.

Writing documentation so that everyone will understand it and NOT get 
the wrong end of the stick is difficult.  I don't know if this would 
make things more confusing for others, or even if it might have helped 
me. At the moment, I think it might be in the right direction, though.

Thank you,

Hugh


-- 
--
Dr. Hugh Sasse, BSc(Hons), PhD
Computer Systems Electronic Engineer
School of Engineering and Sustainable Development
DE MONTFORT UNIVERSITY