[issue24885] StreamReaderProtocol docs recommend using private API

[Guido van Rossum]

Changes by Guido van Rossum :


--
assignee:  -> gvanrossum
resolution:  -> fixed
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24885] StreamReaderProtocol docs recommend using private API

[Roundup Robot]

Roundup Robot added the comment:

New changeset d91208957e4e by Guido van Rossum in branch '3.4':
Issue #24885: Update note in docs about stream convenience functions.
https://hg.python.org/cpython/rev/d91208957e4e

New changeset 43c63dd2f383 by Guido van Rossum in branch '3.5':
Issue #24885: Update note in docs about stream convenience functions. (Merge 
3.4->3.5)
https://hg.python.org/cpython/rev/43c63dd2f383

New changeset 7947f43a1a87 by Guido van Rossum in branch 'default':
Issue #24885: Update note in docs about stream convenience functions. (Merge 
3.5->3.6)
https://hg.python.org/cpython/rev/7947f43a1a87

--
nosy: +python-dev

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24885] StreamReaderProtocol docs recommend using private API

[Guido van Rossum]

Guido van Rossum added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue24885] StreamReaderProtocol docs recommend using private API

[Aymeric Augustin]

New submission from Aymeric Augustin:

https://docs.python.org/3/library/asyncio-stream.html?highlight=streamreaderprotocol#stream-functions
 says:

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

--
components: asyncio
messages: 248767
nosy: aymeric.augustin, gvanrossum, haypo, yselivanov
priority: normal
severity: normal
status: open
title: StreamReaderProtocol docs recommend using private API
versions: Python 3.4

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com