gh-90533: Implement BytesIO.peek()

Doc/library/io.rst

@@ -728,6 +728,15 @@ than raw I/O does.
 
       Return :class:`bytes` containing the entire contents of the buffer.
 
+   .. method:: peek(size=1, /)
+
+      Return bytes from the current position onwards without advancing the position.
+      At least one byte of data is returned if not at EOF.
+      Return an empty :class:`bytes` object at EOF.
+      If the size argument is less than one or larger than the number of available bytes,
+      a copy of the buffer from the current position until the end is returned.
+
+      .. versionadded:: 3.13
 
    .. method:: read1(size=-1, /)
 
@@ -761,9 +770,12 @@ than raw I/O does.
 
    .. method:: peek(size=0, /)
 
-      Return bytes from the stream without advancing the position.  At most one
-      single read on the raw stream is done to satisfy the call. The number of
-      bytes returned may be less or more than requested.
+      Return bytes from the current position onwards without advancing the position.
+      At least one byte of data is returned if not at EOF.
+      Return an empty :class:`bytes` object at EOF.
+      At most one single read on the underlying raw stream is done to satisfy the call.
+      The exact number of bytes returned is unspecified
+      (*size* is ignored).
 
    .. method:: read(size=-1, /)
 

Doc/whatsnew/3.13.rst

@@ -151,6 +151,8 @@ and only logged in :ref:`Python Development Mode <devmode>` or on :ref:`Python
 built on debug mode <debug-build>`.
 (Contributed by Victor Stinner in :gh:`62948`.)
 
+* Add :meth:`io.BytesIO.peek`. (Contributed by Marcel Martin in :gh:`90533`.)
+
 opcode
 ------
 

Lib/_pyio.py

@@ -978,6 +978,13 @@ def tell(self):
             raise ValueError("tell on closed file")
         return self._pos
 
+    def peek(self, size=1):
+        if self.closed:
+            raise ValueError("peek on closed file")
+        if size < 1:
+            size = len(self._buffer) - self._pos
+        return self._buffer[self._pos : self._pos + size]
+
     def truncate(self, pos=None):
         if self.closed:
             raise ValueError("truncate on closed file")

Lib/test/test_memoryio.py

@@ -517,6 +517,41 @@ def test_relative_seek(self):
         memio.seek(1, 1)
         self.assertEqual(memio.read(), buf[1:])
 
+    def test_peek(self):
+        buf = self.buftype("1234567890")
+        with self.ioclass(buf) as memio:
+            self.assertEqual(memio.tell(), 0)
+            self.assertEqual(memio.peek(1), buf[:1])
+            self.assertEqual(memio.peek(1), buf[:1])
+            self.assertEqual(memio.peek(), buf[:1])
+            self.assertEqual(memio.peek(0), buf)
+            self.assertEqual(memio.peek(len(buf) + 100), buf)
+            self.assertEqual(memio.peek(-1), buf)
+            self.assertEqual(memio.tell(), 0)
+            memio.read(1)
+            self.assertEqual(memio.tell(), 1)
+            self.assertEqual(memio.peek(1), buf[1:2])
+            self.assertEqual(memio.peek(1), buf[1:2])
+            self.assertEqual(memio.peek(), buf[1:2])
+            self.assertEqual(memio.peek(0), buf[1:])
+            self.assertEqual(memio.peek(len(buf) + 100), buf[1:])
+            self.assertEqual(memio.peek(-1), buf[1:])
+            self.assertEqual(memio.tell(), 1)
+            memio.read()
+            self.assertEqual(memio.tell(), len(buf))
+            self.assertEqual(memio.peek(1), self.EOF)
+            self.assertEqual(memio.tell(), len(buf))
+            # Peeking works after writing
+            abc = self.buftype("abc")
+            memio.write(abc)
+            self.assertEqual(memio.peek(), self.EOF)
+            memio.seek(len(buf))
+            self.assertEqual(memio.peek(), abc[:1])
+            self.assertEqual(memio.peek(-1), abc)
+            self.assertEqual(memio.peek(len(abc) + 100), abc)
+            self.assertEqual(memio.tell(), len(buf))
+        self.assertRaises(ValueError, memio.peek)
+
     def test_unicode(self):
         memio = self.ioclass()
 

Misc/NEWS.d/next/Library/2022-04-10-20-10-59.bpo-46375.8j1ogZ.rst

@@ -0,0 +1 @@
+Add :meth:`io.BytesIO.peek`.

Modules/_io/bytesio.c

@@ -394,8 +394,9 @@ _io_BytesIO_tell_impl(bytesio *self)
     return PyLong_FromSsize_t(self->pos);
 }
 
+// Read without advancing position
 static PyObject *
-read_bytes(bytesio *self, Py_ssize_t size)
+peek_bytes(bytesio *self, Py_ssize_t size)
 {
     const char *output;
 
@@ -404,15 +405,23 @@ read_bytes(bytesio *self, Py_ssize_t size)
     if (size > 1 &&
         self->pos == 0 && size == PyBytes_GET_SIZE(self->buf) &&
         self->exports == 0) {
-        self->pos += size;
         return Py_NewRef(self->buf);
     }
 
     output = PyBytes_AS_STRING(self->buf) + self->pos;
-    self->pos += size;
     return PyBytes_FromStringAndSize(output, size);
 }
 
+static PyObject *
+read_bytes(bytesio *self, Py_ssize_t size)
+{
+    PyObject *bytes = peek_bytes(self, size);
+    if (bytes != NULL) {
+        self->pos += size;
+    }
+    return bytes;
+}
+
 /*[clinic input]
 _io.BytesIO.read
     size: Py_ssize_t(accept={int, NoneType}) = -1
@@ -462,6 +471,38 @@ _io_BytesIO_read1_impl(bytesio *self, Py_ssize_t size)
     return _io_BytesIO_read_impl(self, size);
 }
 
+
+/*[clinic input]
+_io.BytesIO.peek
+    size: Py_ssize_t = 1
+    /
+
+Return bytes from the stream without advancing the position.
+
+If the size argument is zero or negative, read until EOF is reached.
+Return an empty bytes object at EOF.
+[clinic start generated code]*/
+
+static PyObject *
+_io_BytesIO_peek_impl(bytesio *self, Py_ssize_t size)
+/*[clinic end generated code: output=fa4d8ce28b35db9b input=cb06614a3ed0496e]*/
+{
+    CHECK_CLOSED(self);
+
+    /* adjust invalid sizes */
+    Py_ssize_t n = self->string_size - self->pos;
+    if (size < 1 || size > n) {
+        size = n;
+        /* size can be negative after truncate() or seek() */
+        if (size < 0) {
+            size = 0;
+        }
+    }
+    return peek_bytes(self, size);
+}
+
+
+
 /*[clinic input]
 _io.BytesIO.readline
     size: Py_ssize_t(accept={int, NoneType}) = -1
@@ -1019,6 +1060,7 @@ static struct PyMethodDef bytesio_methods[] = {
     _IO_BYTESIO_READLINE_METHODDEF
     _IO_BYTESIO_READLINES_METHODDEF
     _IO_BYTESIO_READ_METHODDEF
+    _IO_BYTESIO_PEEK_METHODDEF
     _IO_BYTESIO_GETBUFFER_METHODDEF
     _IO_BYTESIO_GETVALUE_METHODDEF
     _IO_BYTESIO_SEEK_METHODDEF