# HG changeset patch
# Parent 4e84e45e191b3b063387fdd68075f47f4576e215
Issue #22671: Clarify and test default read method implementations

diff -r 4e84e45e191b Doc/library/io.rst
--- a/Doc/library/io.rst	Fri Dec 19 11:21:56 2014 -0500
+++ b/Doc/library/io.rst	Mon Dec 22 23:30:07 2014 +0000
@@ -199,8 +199,8 @@
                                                                          ``writable``, and ``writelines``
 :class:`RawIOBase`         :class:`IOBase`     ``readinto`` and          Inherited :class:`IOBase` methods, ``read``,
                                                ``write``                 and ``readall``
-:class:`BufferedIOBase`    :class:`IOBase`     ``detach``, ``read``,     Inherited :class:`IOBase` methods, ``readinto``
-                                               ``read1``, and ``write``
+:class:`BufferedIOBase`    :class:`IOBase`     ``detach``, ``read``,     Inherited :class:`IOBase` methods, ``readinto``,
+                                               ``read1``, and ``write``  and ``readinto1``
 :class:`TextIOBase`        :class:`IOBase`     ``detach``, ``read``,     Inherited :class:`IOBase` methods, ``encoding``,
                                                ``readline``, and         ``errors``, and ``newlines``
                                                ``write``
@@ -375,14 +375,18 @@
    .. method:: read(size=-1)
 
       Read up to *size* bytes from the object and return them.  As a convenience,
-      if *size* is unspecified or -1, :meth:`readall` is called.  Otherwise,
-      only one system call is ever made.  Fewer than *size* bytes may be
+      if *size* is unspecified or -1, all bytes until EOF are returned.
+      Otherwise, only one system call is ever made.
+      Fewer than *size* bytes may be
       returned if the operating system call returns fewer than *size* bytes.
 
       If 0 bytes are returned, and *size* was not 0, this indicates end of file.
       If the object is in non-blocking mode and no bytes are available,
       ``None`` is returned.
 
+      The default implementation defers to :meth:`readall` and
+      :meth:`readinto`.
+
    .. method:: readall()
 
       Read and return all the bytes from the stream until EOF, using multiple
diff -r 4e84e45e191b Lib/test/test_io.py
--- a/Lib/test/test_io.py	Fri Dec 19 11:21:56 2014 -0500
+++ b/Lib/test/test_io.py	Mon Dec 22 23:30:07 2014 +0000
@@ -605,8 +605,8 @@
         self.assertRaises(ValueError, f.flush)
 
     def test_RawIOBase_read(self):
-        # Exercise the default RawIOBase.read() implementation (which calls
-        # readinto() internally).
+        # Exercise the default RawIOBase.read() and readall() implementations
+        # (which call readinto() internally).
         rawio = self.MockRawIOWithoutRead((b"abc", b"d", None, b"efg", None))
         self.assertEqual(rawio.read(2), b"ab")
         self.assertEqual(rawio.read(2), b"c")
@@ -617,6 +617,43 @@
         self.assertEqual(rawio.read(2), None)
         self.assertEqual(rawio.read(2), b"")
 
+        rawio = self.MockRawIOWithoutRead((b"abc", b"d", b"efg"))
+        self.assertEqual(rawio.read(), b"abcdefg")
+        rawio = self.MockRawIOWithoutRead((b"abc", b"d", b"efg"))
+        self.assertEqual(rawio.readall(), b"abcdefg")
+
+    def test_BufferedIOBase_readinto(self):
+        # Exercise the default BufferedIOBase.readinto() and readinto1()
+        # implementations (which call read() or read1() internally).
+        class Reader(self.BufferedIOBase):
+            def read(self, size):
+                result = self.avail[:size]
+                self.avail = self.avail[size:]
+                return result
+            def read1(self, size):
+                return self.read(min(size, 5))
+        tests = (
+            dict(method="readinto", avail=10, request=5, result=5),
+            dict(method="readinto", avail=10, request=6, result=6),
+            dict(method="readinto", avail=5, request=6, result=5),
+            dict(method="readinto", avail=6, request=7, result=6),
+            dict(method="readinto1", avail=10, request=5, result=5),
+            dict(method="readinto1", avail=10, request=6, result=5),
+            dict(method="readinto1", avail=5, request=6, result=5),
+            dict(method="readinto1", avail=6, request=7, result=5),
+        )
+        for test in tests:
+            with self.subTest(**test):
+                reader = Reader()
+                reader.avail = bytes(range(test["avail"]))
+                buffer = bytearray(test["request"])
+                call = getattr(reader, test["method"])
+                size = test["result"]
+                self.assertEqual(call(buffer), size)
+                self.assertEqual(len(buffer), test["request"])
+                self.assertSequenceEqual(buffer[:size], range(size))
+                self.assertEqual(len(reader.avail), test["avail"] - size)
+
     def test_types_have_dict(self):
         test = (
             self.IOBase(),