[3.11] gh-100226: Clarify StreamReader.read behavior (GH-101807) (#102001)

gh-100226: Clarify StreamReader.read behavior (GH-101807)
(cherry picked from commit 77d95c83733722ada35eb1ef89ae5b84a51ddd32)

Co-authored-by: Jan Gosmann <jan@hyper-world.de>
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>

1 files changed, 9 insertions, 8 deletions

diff --git a/Lib/asyncio/streams.py b/Lib/asyncio/streams.py
index d21a31d..560ad8a 100644
--- a/Lib/asyncio/streams.py
+++ b/Lib/asyncio/streams.py
@@ -648,16 +648,17 @@ class StreamReader:
     async def read(self, n=-1):
         """Read up to `n` bytes from the stream.
 
-        If n is not provided, or set to -1, read until EOF and return all read
-        bytes. If the EOF was received and the internal buffer is empty, return
-        an empty bytes object.
+        If `n` is not provided or set to -1,
+        read until EOF, then return all read bytes.
+        If EOF was received and the internal buffer is empty,
+        return an empty bytes object.
 
-        If n is zero, return empty bytes object immediately.
+        If `n` is 0, return an empty bytes object immediately.
 
-        If n is positive, this function try to read `n` bytes, and may return
-        less or equal bytes than requested, but at least one byte. If EOF was
-        received before any byte is read, this function returns empty byte
-        object.
+        If `n` is positive, return at most `n` available bytes
+        as soon as at least 1 byte is available in the internal buffer.
+        If EOF is received before any byte is read, return an empty
+        bytes object.
 
         Returned value is not limited with limit, configured at stream
         creation.