This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author twisteroid ambassador
Recipients docs@python, twisteroid ambassador, yselivanov
Date 2017-08-10.13:28:01
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1502371681.86.0.869371272399.issue31176@psf.upfronthosting.co.za>
In-reply-to
Content
In docs / Library Reference / asyncio / Transports and Protocols, it is mentioned that "asyncio currently implements transports for TCP, UDP, SSL, and subprocess pipes. The methods available on a transport depend on the transport’s kind." It also lists methods available on a BaseTransport, ReadTransport, WriteTransport, DatagramTransport and BaseSubprocessTransport.

However, the docs does not explain which transports have methods from which base classes, or in other words which base classes each concrete transport class inherits from. And this may not be obvious: for example, a UDP transport certainly is a DatagramTransport, but is it also a ReadTransport, or a WriteTransport?

(I feel like the answer is "no it isn't", but there are plenty of conflicting evidence. The docs show that WriteTransport has write_eof() and can_write_eof() -- methods clearly geared towards stream-like transports, and it duplicates abort() from DatagramTransport, so it would seem like WriteTransport and DatagramTransport are mutually exclusive. On the other hand, the default concrete implementation of _SelectorDatagramTransport actually inherits from Transport which inherits from both ReadTransport and WriteTransport, yet it does not inherit from DatagramTransport; As a result _SelectorDatagramTransport has all the methods from ReadTransport and WriteTransport, but many of them raise NotImplemented. This is why I'm asking this question in the first place: I found that the transport object I got from create_datagram_endpoint() has both pause_reading() and resume_reading() methods that raise NotImplemented, and thought that perhaps some event loop implementations would have these methods working, and I should try to use them. And before you say "UDP doesn't do flow control", asyncio actually does provide flow control for UDP on the writing end: see https://www.mail-archive.com/python-tulip@googlegroups.com/msg00532.html So it's not preposterous that there might be flow control on the reading end as well.)

I think it would be nice if the documentation can state the methods implemented for each type of transport, as the designers of Python intended, so there's a clear expectation of what methods will / should be available across different implementations of event loops and transports. Something along the lines of "The methods available on a transport depend on the transport’s kind: TCP transports support methods declared in BaseTransport, ReadTransport and WriteTransport below, etc."
History
Date User Action Args
2017-08-10 13:28:01twisteroid ambassadorsetrecipients: + twisteroid ambassador, docs@python, yselivanov
2017-08-10 13:28:01twisteroid ambassadorsetmessageid: <1502371681.86.0.869371272399.issue31176@psf.upfronthosting.co.za>
2017-08-10 13:28:01twisteroid ambassadorlinkissue31176 messages
2017-08-10 13:28:01twisteroid ambassadorcreate