Issue 24885: StreamReaderProtocol docs recommend using private API (original) (raw)
(If you want to customize the StreamReader and/or StreamReaderProtocol classes, just copy the code – there’s really nothing special here except some convenience.)
StreamReaderProtocol inherits from streams.FlowControlMixin which isn't documented. Applying this advice means, instead of inheriting from StreamReaderProtocol, inheriting from streams.FlowControlMixin -- in order to obtain the _drain_helper method, which StreamWriter.drain must wait for.
At this point inheriting StreamReaderProtocol appears to be the lesser evil.
I suggest to remove this paragraph from the documentation.
I just re-read the docs here (which came straight from the open_connection() docstring). The parenthetical remark is confusing -- I meant something more like
""" If you want to use different classes than StreamReader, StreamReaderProtocol and StreamWriter, just copy the code of open_connection() and substitute your own classes. """
That is, the customization it is trying to refer to is open_connection(), not the classes.
FWIW I think subclassing implementation classes is a dangerous practice and shouldn't be encouraged.
Because the same reasoning applies to all the top-level functions here (but not to the classes), I think I'll delete the offending paragraph and replace it with something like the following at the top of the docs for this module:
""" The top-level functions in this module are meant convenience wrappers only; there's really nothing special there, and if they don't do what you want feel free to copy their code. """