[Python-checkins] [3.11] gh-100226: Clarify StreamReader.read behavior (GH-101807) (#102001)
kumaraditya303
webhook-mailer at python.org
Thu Feb 23 08:36:06 EST 2023
https://github.com/python/cpython/commit/42d0ca92ed141e7518b5b4d77e6e27e36ac451dc
commit: 42d0ca92ed141e7518b5b4d77e6e27e36ac451dc
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: kumaraditya303 <59607654+kumaraditya303 at users.noreply.github.com>
date: 2023-02-23T19:05:59+05:30
summary:
[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 at hyper-world.de>
Co-authored-by: Shantanu <12621235+hauntsaninja at users.noreply.github.com>
files:
M Doc/library/asyncio-stream.rst
M Lib/asyncio/streams.py
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 74891306a637..e9d466d95e54 100644
--- 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 d21a31d1860d..560ad8a8510e 100644
--- a/Lib/asyncio/streams.py
+++ b/Lib/asyncio/streams.py
@@ -648,16 +648,17 @@ async def readuntil(self, separator=b'\n'):
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.
More information about the Python-checkins
mailing list