bpo-41305: Add StreamReader.readinto() (GH-21491)

This function is useful when you want to fill an already allocated
buffer with data read from the stream.

Author: tontinton

Doc/library/asyncio-stream.rst

@@ -211,6 +211,13 @@ StreamReader
 
       .. versionadded:: 3.5.2
 
+   .. coroutinemethod:: readinto(buf)
+
+      Read up to *n* bytes with *n* being equal to the length of *buf* and
+      copy the buffer read from the stream into *buf*.
+
+      Return the number of bytes read from the stream.
+
    .. method:: at_eof()
 
       Return ``True`` if the buffer is empty and :meth:`feed_eof`

Lib/asyncio/streams.py

@@ -690,6 +690,44 @@ async def read(self, n=-1):
         self._maybe_resume_transport()
         return data
 
+    async def readinto(self, buf):
+        """Read up to the length of `buf` number of bytes from the stream and
+        fill the `buf` bytes object with what was read from the stream.
+
+        Returns the number of bytes read from the stream.
+
+        If `buf` is empty, return 0 immediately.
+
+        If `buf` is not empty, this function tries to read the length of `buf`
+        number of bytes, and may fill the buffer with less or equal bytes than
+        requested, but at least one byte. If EOF was received before any byte
+        is read, this function returns 0.
+
+        Returned value is not limited with limit, configured at stream
+        creation.
+
+        If stream was paused, this function will automatically resume it if
+        needed.
+        """
+        n = len(buf)
+
+        if self._exception is not None:
+            raise self._exception
+
+        if n == 0:
+            return 0
+
+        if not self._buffer and not self._eof:
+            await self._wait_for_data('readinto')
+
+        length = min(n, len(self._buffer))
+        if length > 0:
+            buf[:length] = self._buffer[:length]
+
+        del self._buffer[:n]
+        self._maybe_resume_transport()
+        return length
+
     async def readexactly(self, n):
         """Read exactly `n` bytes.
 

Misc/NEWS.d/next/Library/2020-07-15-19-34-39.bpo-41305.3In2Tp.rst

@@ -0,0 +1 @@
+Add the ``StreamReader.readinto(buf)`` function.