Update docs, factor out peek_bytes, semantics

Semantic change: The default argument for peek is now size=1.

Author: marcelm

Doc/library/io.rst

@@ -728,12 +728,15 @@ than raw I/O does.
 
       Return :class:`bytes` containing the entire contents of the buffer.
 
-   .. method:: peek(size=0, /)
-
-      .. versionadded:: 3.13
+   .. method:: peek(size=1, /)
 
       Return bytes from the current position onwards but without advancing the
-      position. The number of bytes returned may be less or more than requested.
+      position. 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.
+      Return an empty bytes object at EOF.
+
+      .. versionadded:: 3.13
 
    .. method:: read1(size=-1, /)
 

Lib/_pyio.py

@@ -978,13 +978,12 @@ def tell(self):
             raise ValueError("tell on closed file")
         return self._pos
 
-    def peek(self, size=-1):
-        pos = self.tell()
-        if size == 0:
-            size = -1
-        b = self.read(size)
-        self.seek(pos)
-        return b
+    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:

Lib/test/test_memoryio.py

@@ -523,12 +523,13 @@ def test_peek(self):
         pos = memio.tell()
         self.assertEqual(memio.peek(1), buf[:1])
         self.assertEqual(memio.peek(1), buf[:1])
-        self.assertEqual(memio.peek(), buf)
+        self.assertEqual(memio.peek(), buf[:1])
         self.assertEqual(memio.peek(0), buf)
         self.assertEqual(memio.tell(), pos)
         memio.read(1)
         self.assertEqual(memio.peek(1), buf[1:2])
-        self.assertEqual(memio.peek(), buf[1:])
+        self.assertEqual(memio.peek(), buf[1:2])
+        self.assertEqual(memio.peek(0), buf[1:])
         self.assertEqual(memio.peek(42), buf[1:])
         memio.read()
         self.assertEqual(memio.peek(1), self.EOF)

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,20 @@ 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);
+    self->pos += size;
+    return bytes;
+}
+
 /*[clinic input]
 _io.BytesIO.read
     size: Py_ssize_t(accept={int, NoneType}) = -1
@@ -465,17 +471,18 @@ _io_BytesIO_read1_impl(bytesio *self, Py_ssize_t size)
 
 /*[clinic input]
 _io.BytesIO.peek
-    size: Py_ssize_t(accept={int, NoneType}) = -1
+    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=afc80e71b37e7c59]*/
+/*[clinic end generated code: output=fa4d8ce28b35db9b input=cb06614a3ed0496e]*/
 {
     Py_ssize_t n;
 
@@ -488,11 +495,7 @@ _io_BytesIO_peek_impl(bytesio *self, Py_ssize_t size)
         if (size < 0)
             size = 0;
     }
-    Py_ssize_t prev_pos = self->pos;
-    PyObject* result = read_bytes(self, size);
-    self->pos = prev_pos;
-
-    return result;
+    return peek_bytes(self, size);
 }