# HG changeset patch # Parent 154ae3af03173ce0f735b6dd47a37da97910f0b9 Document that “io” methods should accept bytes-like objects as arguments This matches the usage of ZipFile and BufferedWriter. This still requires return values to be bytes() objects. diff -r 154ae3af0317 Doc/library/io.rst --- a/Doc/library/io.rst Fri Jan 09 16:40:38 2015 -0600 +++ b/Doc/library/io.rst Mon Feb 23 04:37:16 2015 +0000 @@ -66,7 +66,8 @@ Binary I/O ^^^^^^^^^^ -Binary I/O (also called *buffered I/O*) expects and produces :class:`bytes` +Binary I/O (also called *buffered I/O*) expects +:term:`bytes-like objects ` and produces :class:`bytes` objects. No encoding, decoding, or newline translation is performed. This category of streams can be used for all kinds of non-text data, and also when manual control over the handling of text data is desired. @@ -227,9 +228,10 @@ when operations they do not support are called. The basic type used for binary data read from or written to a file is - :class:`bytes`. :class:`bytearray`\s are accepted too, and in some cases - (such as :meth:`readinto`) required. Text I/O classes work with - :class:`str` data. + :class:`bytes`. Other :term:`bytes-like objects ` are + accepted as method arguments too. In some cases, such as + :meth:`~RawIOBase.readinto`, a writable object such as :class:`bytearray` + is required. Text I/O classes work with :class:`str` data. Note that calling any method (even inquiries) on a closed stream is undefined. Implementations may raise :exc:`ValueError` in this case. @@ -390,15 +392,17 @@ .. method:: readinto(b) - Read up to ``len(b)`` bytes into :class:`bytearray` *b* and return the + Read bytes into a pre-allocated, writable + :term:`bytes-like object` *b*, and return the number of bytes read. If the object is in non-blocking mode and no bytes are available, ``None`` is returned. .. method:: write(b) - Write the given :class:`bytes` or :class:`bytearray` object, *b*, to the + Write the given :term:`bytes-like object`, *b*, to the underlying raw stream and return the number of bytes written. This can - be less than ``len(b)``, depending on specifics of the underlying raw + be less than the length of *b* in bytes, + depending on specifics of the underlying raw stream, and especially if it is in non-blocking mode. ``None`` is returned if the raw stream is set not to block and no single byte could be readily written to it. @@ -473,8 +477,8 @@ .. method:: readinto(b) - Read up to ``len(b)`` bytes into bytearray *b* and return the number of - bytes read. + Read bytes into a pre-allocated, writable + :term:`bytes-like object` *b* and return the number of bytes read. Like :meth:`read`, multiple reads may be issued to the underlying raw stream, unless the latter is interactive. @@ -484,7 +488,8 @@ .. method:: readinto1(b) - Read up to ``len(b)`` bytes into bytearray *b*, ,using at most one call to + Read bytes into a pre-allocated, writable + :term:`bytes-like object` *b*, using at most one call to the underlying raw stream's :meth:`~RawIOBase.read` (or :meth:`~RawIOBase.readinto`) method. Return the number of bytes read. @@ -495,8 +500,8 @@ .. method:: write(b) - Write the given :class:`bytes` or :class:`bytearray` object, *b* and - return the number of bytes written (never less than ``len(b)``, since if + Write the given :term:`bytes-like object`, *b*, and return the number + of bytes written (always equal to the length of *b* in bytes, since if the write fails an :exc:`OSError` will be raised). Depending on the actual implementation, these bytes may be readily written to the underlying stream, or held in a buffer for performance and latency @@ -580,7 +585,8 @@ A stream implementation using an in-memory bytes buffer. It inherits :class:`BufferedIOBase`. - The argument *initial_bytes* contains optional initial :class:`bytes` data. + The argument *initial_bytes* is a :term:`bytes-like object` that + contains initial data. :class:`BytesIO` provides or overrides these methods in addition to those from :class:`BufferedIOBase` and :class:`IOBase`: @@ -677,7 +683,7 @@ .. method:: write(b) - Write the :class:`bytes` or :class:`bytearray` object, *b* and return the + Write the :term:`bytes-like object`, *b*, and return the number of bytes written. When in non-blocking mode, a :exc:`BlockingIOError` is raised if the buffer needs to be written out but the raw stream blocks. diff -r 154ae3af0317 Lib/_pyio.py --- a/Lib/_pyio.py Fri Jan 09 16:40:38 2015 -0600 +++ b/Lib/_pyio.py Mon Feb 23 04:37:16 2015 +0000 @@ -290,8 +290,9 @@ called. The basic type used for binary data read from or written to a file is - bytes. bytearrays are accepted too, and in some cases (such as - readinto) needed. Text I/O classes work with str data. + bytes. Other bytes-like objects are accepted as method arguments too. In + some cases (such as readinto), a writable object is required. Text I/O + classes work with str data. Note that calling any method (even inquiries) on a closed stream is undefined. Implementations may raise OSError in this case. @@ -590,7 +591,7 @@ return data def readinto(self, b): - """Read up to len(b) bytes into bytearray b. + """Read bytes into a pre-allocated bytes-like object b. Returns an int representing the number of bytes read (0 for EOF), or None if the object is set not to block and has no data to read. @@ -600,7 +601,8 @@ def write(self, b): """Write the given buffer to the IO stream. - Returns the number of bytes written, which may be less than len(b). + Returns the number of bytes written, which may be less than the + length of b in bytes. """ self._unsupported("write") @@ -653,7 +655,7 @@ self._unsupported("read1") def readinto(self, b): - """Read up to len(b) bytes into bytearray b. + """Read bytes into a pre-allocated bytes-like object b. Like read(), this may issue multiple reads to the underlying raw stream, unless the latter is 'interactive'. @@ -667,7 +669,7 @@ return self._readinto(b, read1=False) def readinto1(self, b): - """Read up to len(b) bytes into *b*, using at most one system call + """Read bytes into buffer *b*, using at most one system call Returns an int representing the number of bytes read (0 for EOF). @@ -695,8 +697,8 @@ def write(self, b): """Write the given bytes buffer to the IO stream. - Return the number of bytes written, which is never less than - len(b). + Return the number of bytes written, which is always the length of b + in bytes. Raises BlockingIOError if the buffer is full and the underlying raw stream cannot accept more data at the moment. @@ -878,7 +880,8 @@ raise ValueError("write to closed file") if isinstance(b, str): raise TypeError("can't write str to binary stream") - n = len(b) + with memoryview(b) as view: + n = view.nbytes # Size of any bytes-like object if n == 0: return 0 pos = self._pos @@ -1092,14 +1095,13 @@ def _readinto(self, buf, read1): """Read data into *buf* with at most one system call.""" - if len(buf) == 0: - return 0 - # Need to create a memoryview object of type 'b', otherwise # we may not be able to assign bytes to it, and slicing it # would create a new object. if not isinstance(buf, memoryview): buf = memoryview(buf) + if buf.nbytes == 0: + return 0 buf = buf.cast('B') written = 0 diff -r 154ae3af0317 Lib/test/test_io.py --- a/Lib/test/test_io.py Fri Jan 09 16:40:38 2015 -0600 +++ b/Lib/test/test_io.py Mon Feb 23 04:37:16 2015 +0000 @@ -45,6 +45,22 @@ except ImportError: threading = None +try: + import ctypes +except ImportError: + def byteslike(*pos, **kw): + return array.array("b", bytes(*pos, **kw)) +else: + def byteslike(*pos, **kw): + """Create a bytes-like object having no string or sequence methods""" + data = bytes(*pos, **kw) + obj = EmptyStruct() + ctypes.resize(obj, len(data)) + memoryview(obj).cast("B")[:] = data + return obj + class EmptyStruct(ctypes.Structure): + pass + def _default_chunk_size(): """Get the default TextIOWrapper chunk size""" with open(__file__, "r", encoding="latin-1") as f: @@ -294,20 +310,21 @@ def read_ops(self, f, buffered=False): data = f.read(5) self.assertEqual(data, b"hello") - data = bytearray(data) + data = byteslike(data) self.assertEqual(f.readinto(data), 5) - self.assertEqual(data, b" worl") + self.assertEqual(bytes(data), b" worl") + data = bytearray(5) self.assertEqual(f.readinto(data), 2) self.assertEqual(len(data), 5) self.assertEqual(data[:2], b"d\n") self.assertEqual(f.seek(0), 0) self.assertEqual(f.read(20), b"hello world\n") self.assertEqual(f.read(1), b"") - self.assertEqual(f.readinto(bytearray(b"x")), 0) + self.assertEqual(f.readinto(byteslike(b"x")), 0) self.assertEqual(f.seek(-6, 2), 6) self.assertEqual(f.read(5), b"world") self.assertEqual(f.read(0), b"") - self.assertEqual(f.readinto(bytearray()), 0) + self.assertEqual(f.readinto(byteslike()), 0) self.assertEqual(f.seek(-6, 1), 5) self.assertEqual(f.read(5), b" worl") self.assertEqual(f.tell(), 10) @@ -318,6 +335,10 @@ f.seek(6) self.assertEqual(f.read(), b"world\n") self.assertEqual(f.read(), b"") + f.seek(0) + data = byteslike(5) + self.assertEqual(f.readinto1(data), 5) + self.assertEqual(bytes(data), b"hello") LARGE = 2**31 @@ -528,10 +549,22 @@ def test_array_writes(self): a = array.array('i', range(10)) n = len(a.tobytes()) - with self.open(support.TESTFN, "wb", 0) as f: - self.assertEqual(f.write(a), n) - with self.open(support.TESTFN, "wb") as f: - self.assertEqual(f.write(a), n) + def make_file_writer(): + return self.FileIO(support.TESTFN, "w") + def make_buffered_writer(): + return self.BufferedWriter(self.MockRawIO()) + def make_buffered_random(): + return self.BufferedRandom(self.MockRawIO()) + def make_buffered_rw_pair(): + return self.BufferedRWPair(self.MockRawIO(), self.MockRawIO()) + writer_factories = ( + self.BytesIO, make_file_writer, make_buffered_writer, + make_buffered_random, make_buffered_rw_pair, + ) + for factory in writer_factories: + with self.subTest(factory), factory() as f: + self.assertEqual(f.write(a), n) + f.writelines((a,)) def test_closefd(self): self.assertRaises(ValueError, self.open, support.TESTFN, 'w', @@ -663,6 +696,19 @@ support.gc_collect() self.assertEqual(recorded, []) + def test_buffered_readinto_mixin(self): + # Test the implementation provided by BufferedIOBase + class Stream(self.BufferedIOBase): + def read(self, size): + return b"12345" + read1 = read + stream = Stream() + for method in ("readinto", "readinto1"): + with self.subTest(method): + buffer = byteslike(5) + self.assertEqual(getattr(stream, method)(buffer), 5) + self.assertEqual(bytes(buffer), b"12345") + class CIOTest(IOTest): @@ -1564,11 +1610,13 @@ self.assertEqual(pair.read1(3), b"abc") def test_readinto(self): - pair = self.tp(self.BytesIO(b"abcdef"), self.MockRawIO()) - - data = bytearray(5) - self.assertEqual(pair.readinto(data), 5) - self.assertEqual(data, b"abcde") + for method in ("readinto", "readinto1"): + with self.subTest(method): + pair = self.tp(self.BytesIO(b"abcdef"), self.MockRawIO()) + + data = byteslike(5) + self.assertEqual(getattr(pair, method)(data), 5) + self.assertEqual(bytes(data), b"abcde") def test_write(self): w = self.MockRawIO() diff -r 154ae3af0317 Lib/test/test_memoryio.py --- a/Lib/test/test_memoryio.py Fri Jan 09 16:40:38 2015 -0600 +++ b/Lib/test/test_memoryio.py Mon Feb 23 04:37:16 2015 +0000 @@ -386,7 +386,16 @@ del __main__.PickleTestMemIO -class BytesIOMixin: +class PyBytesIOTest(MemoryTestMixin, MemorySeekTestMixin, unittest.TestCase): + # Test _pyio.BytesIO; class also inherited for testing C implementation + + UnsupportedOperation = pyio.UnsupportedOperation + + @staticmethod + def buftype(s): + return s.encode("ascii") + ioclass = pyio.BytesIO + EOF = b"" def test_getbuffer(self): memio = self.ioclass(b"1234567890") @@ -408,18 +417,6 @@ support.gc_collect() memio.truncate() - -class PyBytesIOTest(MemoryTestMixin, MemorySeekTestMixin, - BytesIOMixin, unittest.TestCase): - - UnsupportedOperation = pyio.UnsupportedOperation - - @staticmethod - def buftype(s): - return s.encode("ascii") - ioclass = pyio.BytesIO - EOF = b"" - def test_read1(self): buf = self.buftype("1234567890") memio = self.ioclass(buf) diff -r 154ae3af0317 Modules/_io/bufferedio.c --- a/Modules/_io/bufferedio.c Fri Jan 09 16:40:38 2015 -0600 +++ b/Modules/_io/bufferedio.c Mon Feb 23 04:37:16 2015 +0000 @@ -166,8 +166,8 @@ PyDoc_STRVAR(bufferediobase_write_doc, "Write the given buffer to the IO stream.\n" "\n" - "Returns the number of bytes written, which is never less than\n" - "len(b).\n" + "Returns the number of bytes written, which is always the length of b\n" + "in bytes.\n" "\n" "Raises BlockingIOError if the buffer is full and the\n" "underlying raw stream cannot accept more data at the moment.\n"); diff -r 154ae3af0317 Modules/_io/bytesio.c --- a/Modules/_io/bytesio.c Fri Jan 09 16:40:38 2015 -0600 +++ b/Modules/_io/bytesio.c Mon Feb 23 04:37:16 2015 +0000 @@ -547,7 +547,7 @@ } PyDoc_STRVAR(readinto_doc, -"readinto(bytearray) -> int. Read up to len(b) bytes into b.\n" +"readinto(bytearray) -> int. Read bytes into b.\n" "\n" "Returns number of bytes read (0 for EOF), or None if the object\n" "is set not to block as has no data to read."); diff -r 154ae3af0317 Modules/_io/fileio.c --- a/Modules/_io/fileio.c Fri Jan 09 16:40:38 2015 -0600 +++ b/Modules/_io/fileio.c Mon Feb 23 04:37:16 2015 +0000 @@ -1118,7 +1118,7 @@ "or None if no data is available. On end-of-file, returns ''."); PyDoc_STRVAR(write_doc, -"write(b: bytes) -> int. Write bytes b to file, return number written.\n" +"write(b) -> int. Write buffer b to file; return number of bytes written\n" "\n" "Only makes one system call, so not all of the data may be written.\n" "The number of bytes actually written is returned."); diff -r 154ae3af0317 Modules/_io/iobase.c --- a/Modules/_io/iobase.c Fri Jan 09 16:40:38 2015 -0600 +++ b/Modules/_io/iobase.c Mon Feb 23 04:37:16 2015 +0000 @@ -39,8 +39,9 @@ "called.\n" "\n" "The basic type used for binary data read from or written to a file is\n" - "bytes. bytearrays are accepted too, and in some cases (such as\n" - "readinto) needed. Text I/O classes work with str data.\n" + "bytes. Other bytes-like objects are accepted as method arguments too.\n" + "In some cases (such as readinto), a writable object is required. Text\n" + "I/O classes work with str data.\n" "\n" "Note that calling any method (except additional calls to close(),\n" "which are ignored) on a closed stream should raise a ValueError.\n"