From cce42af040ad5de5b0f15e6ab555c7b10ec1e8e2 Mon Sep 17 00:00:00 2001 From: Jan Gosmann Date: Fri, 10 Feb 2023 21:10:46 +0100 Subject: [PATCH 1/5] Clarify StreamReader.read behavior This clarifies the `StreamReader.read` behavior in the public documentation; mostly copying from the more precise docstring of the function. While we're at it, also fix some minor grammar in the docstring itself. Addresses #100226. --- Doc/library/asyncio-stream.rst | 12 ++++++++++-- Lib/asyncio/streams.py | 4 ++-- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index 3b3c68ab6ef625..2ba7631a97433b 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. + If *n* is not provided, or set to ``-1``, + read until EOF. After EOF is received, 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 positive, this function tries 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 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 7d13e961bd2de4..4892649d5e2694 100644 --- a/Lib/asyncio/streams.py +++ b/Lib/asyncio/streams.py @@ -655,9 +655,9 @@ async def read(self, n=-1): If n is zero, return empty bytes object immediately. - If n is positive, this function try to read `n` bytes, and may return + If n is positive, this function tries 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 + received before any byte is read, this function returns an empty bytes object. Returned value is not limited with limit, configured at stream From 970b725a47c07639c7f9be47bb113cfd461244af Mon Sep 17 00:00:00 2001 From: Jan Gosmann Date: Thu, 16 Feb 2023 21:27:09 +0100 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- Doc/library/asyncio-stream.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index 2ba7631a97433b..a97fb82b2d460c 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -206,14 +206,14 @@ StreamReader .. coroutinemethod:: read(n=-1) - Read up to *n* bytes. + Read up to *n* bytes from the stream. If *n* is not provided, or set to ``-1``, read until EOF. After EOF is received, 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 tries to read *n* bytes, and may return less or equal bytes than requested, but at least one byte. If EOF was From d5f28eb62a8c52ddab9f32b43a55704717c45566 Mon Sep 17 00:00:00 2001 From: Jan Gosmann Date: Thu, 16 Feb 2023 21:34:46 +0100 Subject: [PATCH 3/5] Improve clarity of StreamReader.read docs (based on review comments) --- Doc/library/asyncio-stream.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index a97fb82b2d460c..1ad8e2bcfddf40 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -209,15 +209,16 @@ StreamReader Read up to *n* bytes from the stream. If *n* is not provided, or set to ``-1``, - read until EOF. After EOF is received, return all read bytes. + 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, this function tries 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 an empty + If *n* is positive, wait for at least 1 byte to become available + (or EOF), then return the available ``bytes`` which might be less + than *n*. + If EOF is received before any byte is read, return an empty ``bytes`` object. .. coroutinemethod:: readline() From 976c25e47068071a091ec3d54cd67eb35fc5b907 Mon Sep 17 00:00:00 2001 From: Jan Gosmann Date: Fri, 17 Feb 2023 18:43:21 +0100 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- Doc/library/asyncio-stream.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index 1ad8e2bcfddf40..bbac1c32b5695f 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -208,16 +208,15 @@ StreamReader Read up to *n* bytes from the stream. - If *n* is not provided, or set to ``-1``, + 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, wait for at least 1 byte to become available - (or EOF), then return the available ``bytes`` which might be less - than *n*. + 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. From a920fbed365b97152e638d906eb237d7414464c1 Mon Sep 17 00:00:00 2001 From: Jan Gosmann Date: Fri, 17 Feb 2023 18:56:04 +0100 Subject: [PATCH 5/5] Copy StreamReader.read documentation to docstring It discusses how many bytes are returned in slightly more detail. --- Lib/asyncio/streams.py | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/Lib/asyncio/streams.py b/Lib/asyncio/streams.py index 4892649d5e2694..bf15f517e50dce 100644 --- a/Lib/asyncio/streams.py +++ b/Lib/asyncio/streams.py @@ -649,16 +649,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 tries 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 an empty bytes - 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.