gh-100226: Clarify StreamReader.read behavior (#101807)

diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 3b3c68ab6ef6258d40c4aae4c4706d79d548e5f3..bbac1c32b5695f327079518059e9ef2803d36231 100644 (file)
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -206,12 +206,20 @@ StreamReader
 
    .. coroutinemethod:: read(n=-1)
 
-      Read up to *n* bytes.  If *n* is not provided, or set to ``-1``,
-      read until EOF and return all read bytes.
+      Read up to *n* bytes from the stream.
 
+      If *n* is not provided or set to ``-1``,
+      read until EOF, then return all read :class:`bytes`.
       If EOF was received and the internal buffer is empty,
       return an empty ``bytes`` object.
 
+      If *n* is ``0``, return an empty ``bytes`` object immediately.
+
+      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.
+
    .. coroutinemethod:: readline()
 
       Read one line, where "line" is a sequence of bytes

diff --git a/Lib/asyncio/streams.py b/Lib/asyncio/streams.py
index 7d13e961bd2de417874566e0e4792a60580f052a..bf15f517e50dcea50078e4b67d0abd5628b10396 100644 (file)
--- a/Lib/asyncio/streams.py
+++ b/Lib/asyncio/streams.py
@@ -649,16 +649,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.