bpo-36889: Document Stream class and add docstrings by tirkarthi · Pull Request #14488 · python/cpython (original) (raw)

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.