A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

I have pushed the changes to make sure await stream.write(data) as recommended with stream.write(data); await stream.drain() also documented with a method. I think the only detail pending now is over how multiple stream.write can be buffered to use stream.drain later as below that should be noted in the stream.drain docs.

#14488 (comment)

This is a bit more subtle. drain() is only needed when you do a few stream.write() calls. When you have only one stream.write() you can just say await stream.write() and not bother with drain(). @asvetlov am I right?

I think the only detail pending now is over how multiple stream.write can be buffered to use stream.drain later as below that should be noted in the stream.drain docs.

The interesting part is that multiple sync writes and single drain after doesn't help with buffering. Instead, it may consume more memory then expected.

asyncio streams already have low and high watermarks for write buffer size control. If kernel write buffer is full the data is collected in asyncio internal write buffer. If the internal buffer size is greater than high watermark the writing is paused until the size of the buffer doesn't fall to less than the low watermark. After that write is resumed and keeps resumed until the high watermark is reached again.

So, data is effectively buffered even if await stream.write() notation is always used, drain() after multiple sync write() calls doesn't make any value.

I doubt if we need to document it here, in a method reference. Maybe a separate asyncio section about buffering makes sense?
The section is not related to streams itself, low-level protocol.pause_writing() / protocol.resume_writing() supports the same logic.

Andrew, reading all of this makes me think about soft-deprecating non-await write() and drain() in the documentation (it will probably take us many releases before we can actually deprecate them, if ever). This will actually encourage people to just write await stream.write() and not touch drain() etc.

Andrew, reading all of this makes me think about soft-deprecating non-await write() and drain() in the documentation (it will probably take us many releases before we can actually deprecate them, if ever). This will actually encourage people to just write await stream.write() and not touch drain() etc.

@1st1 I told you at US PyCon that non-awaitable methods are useless and should be deprecated eventually. You had doubts, so we decided to support both.

I totally agree with the deprecation strategy.

Does soft-deprecation means ..deprecated: section or completely removal these API from docs?
The second is more aggressive, sure. But it simplifies documentation writing and (much more important) reading a lot.

@1st1 what do you prefer?

Does soft-deprecation means ..deprecated: section or completely removal these API from docs?
The second is more aggressive, sure. But it simplifies documentation writing and (much more important) reading a lot.

I'd do it in a very soft way in 3.8/3.9; basically we just warn users that they are deprecated in the docs and that's it.

Ok, I agree with any decision.
@tirkarthi please add .. deprecated:: sections.

Sorry for the endless list of notes. Writing a new stream API took me weeks, documenting it takes a long as well.

Added deprecated notes to Stream.drain and method Stream.write to recommending usage of await Stream.write as a coroutine to be awaited. There is also StreamWriter.write and StreamWriter.writelines but they are already recommended to use stream.write and contain examples on using it in 3.7 where await is not supported so I have not added deprecations there.

No problem, I got to know better about the API while documentation and also closed some old and outdated issues related to Streams on the tracker with the PR. Appreciate your help on word formation and care to perfect user facing documentation.

Good, done. The current order is alphabetic sort as below with attribute mode at first

mode

abort
at_eof
can_write_eof
close
drain
get_extra_info
is_closing
read
readexactly
readline
readuntil
sendfile
start_tls
wait_closed
write coroutine
write method
writelines
write_eof

``

@1st1 please review again. The PR is ready for merging from my perspective

@tirkarthi: Status check is done, and it's a success ✅ .

Thanks @tirkarthi for the PR 🌮🎉.. I'm working now to backport this PR to: 3.8.
🐍🍒⛏🤖

I'm having trouble backporting to 3.8. Reason: 'Error 110 while writing to socket. Connection timed out.'. Please retry by removing and re-adding the needs backport to 3.8 label.

Thank you very much Andrew and Yury. I can create a separate PR if there are additional improvements.

Oops. Sorry, @1st1
I've added automerge label with the hope that the merge will be blocked until your approval.
@miss-islington has own logic for this situation.

Anyway, please feel free to express your objection if any, @tirkarthi and I can fix them in the following PR quickly.

Thanks @tirkarthi for the PR 🌮🎉.. I'm working now to backport this PR to: 3.8.
🐍🍒⛏🤖

GH-16087 is a backport of this pull request to the 3.8 branch.