Is a UDP transport also a ReadTransport/WriteTransport?

[twisteroidambassador]

BPO	31176
Nosy	@1st1, @twisteroidambassador

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2017-08-10.13:28:01.796>
labels = ['type-feature', '3.7', 'docs', 'expert-asyncio']
title = 'Is a UDP transport also a ReadTransport/WriteTransport?'
updated_at = <Date 2017-08-10.13:28:01.796>
user = 'https://github.com/twisteroidambassador'

bugs.python.org fields:

activity = <Date 2017-08-10.13:28:01.796>
actor = 'twisteroid ambassador'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'asyncio']
creation = <Date 2017-08-10.13:28:01.796>
creator = 'twisteroid ambassador'
dependencies = []
files = []
hgrepos = []
issue_num = 31176
keywords = []
message_count = 1.0
messages = ['300083']
nosy_count = 3.0
nosy_names = ['docs@python', 'yselivanov', 'twisteroid ambassador']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue31176'
versions = ['Python 3.5', 'Python 3.6', 'Python 3.7']

[twisteroidambassador]

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."

[kumaraditya303]

@CAM-Gerlach Do you know if this inheritance pattern can be expressed better with a sphinx extension or something or does this needs to be done manually?

[gvanrossum]

We should start by collecting the actual graph of inheritance between the various transports, here in this issue.

[CAM-Gerlach]

In terms of support for presenting this information, there's the built in e.g. sphinx.ext.inheritance_diagram. But it seems to me, as it does @gvanrossum, that the main task at present is determining the intended and/or actual inheritance pattern between these classes. Once that is in hand, we can decide how to best present it, and implement that in the docs (which I could help with if desired).

[kumaraditya303]

In terms of support for presenting this information, there's the built in e.g. sphinx.ext.inheritance_diagram.

Thanks, I didn't know that sphinx has graphviz support.

There is one bad news, the current inheritance of datagram transports is broken (I remembered that this was fixed long ago but apparently not). See #90352 by @asvetlov