classification
Title: What happened to StreamReaderProtocol?
Type: Stage: resolved
Components: asyncio Versions: Python 3.8
process
Status: closed Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: asvetlov, aymeric.augustin, yselivanov
Priority: normal Keywords:

Created on 2019-07-21 06:28 by aymeric.augustin, last changed 2019-07-23 16:53 by aymeric.augustin. This issue is now closed.

Messages (2)
msg348226 - (view) Author: Aymeric Augustin (aymeric.augustin) * Date: 2019-07-21 06:28
`StreamReaderProtocol` was a public API from Python 3.4 to 3.6:

- https://docs.python.org/3.4/library/asyncio-stream.html?highlight=streamreaderprotocol#streamreaderprotocol
- https://docs.python.org/3.5/library/asyncio-stream.html?highlight=streamreaderprotocol#streamreaderprotocol
- https://docs.python.org/3.6/library/asyncio-stream.html?highlight=streamreaderprotocol#streamreaderprotocol

In Python 3.7, it vanished from the documentation. I couldn't find which commit made that change and why.

- https://docs.python.org/3.7/search.html?q=streamreaderprotocol&check_keywords=yes&area=default

Apparently it's deprecated in Python 3.8 as a side effect of https://bugs.python.org/issue36889.

Unfortunately, that ticket says nothing about `StreamReaderProtocol` and how to replace it. The documentation added when fixing that ticket doesn't say anything about `StreamReaderProtocol` either.

It would be less difficult to swallow the rate of API churn in asyncio if there were at least a few words about why it's happening and what concrete benefits it brings to users.

I can understand the need to change APIs, even public APIs. However, when there's zero information in tickets, commit messages and documentations, I don't know why change is happening and how I'm supposed to adapt my code. That's stressful. If what I'm doing is deprecated, probably it's a bad idea, but I can't know why?

I'm sure you aren't trying to convince me to avoid stream utilities in asyncio and write my own buffering. However, that's the result you're getting :-/ Providing a quick explanation of deprecations / removals of public APIs would help.

(Somewhat related: https://bugs.python.org/issue24885)
msg348330 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2019-07-23 12:21
Hi. StreamReaderProtocol was leaked implementation detail, not a public reusable class. The protocol has too many "gray zones" where its implementation is not well defined or even wrong. 

This situation prevents us from stream API improvements which require changing these implementation details. Keeping full backward compatibility literally means doubling source code, it makes no sense for "private" API but adds a huge maintenance burden.

We are striving to remove it from public API step by step: documentation-deprecation-removal.

If you really need the class -- please copy-paste the source lines into your project and use the copy on your own.
History
Date User Action Args
2019-07-23 16:53:57aymeric.augustinsetstatus: open -> closed
stage: resolved
2019-07-23 12:21:15asvetlovsetmessages: + msg348330
2019-07-21 06:28:22aymeric.augustincreate