Update docs, factor out peek_bytes, semantics

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

Author: marcelm

Doc/library/io.rst

@@ -739,12 +739,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.15
 
    .. method:: read1(size=-1, /)
 

Lib/_pyio.py

@@ -996,13 +996,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_io/test_memoryio.py

@@ -572,12 +572,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

@@ -420,8 +420,9 @@ _io_BytesIO_tell_impl(bytesio *self)
     return PyLong_FromSsize_t(self->pos);
 }
 
+// Read without advancing position
 static PyObject *
-read_bytes_lock_held(bytesio *self, Py_ssize_t size)
+peek_bytes_lock_held(bytesio *self, Py_ssize_t size)
 {
     _Py_CRITICAL_SECTION_ASSERT_OBJECT_LOCKED(self);
 
@@ -432,7 +433,6 @@ read_bytes_lock_held(bytesio *self, Py_ssize_t size)
     if (size > 1 &&
         self->pos == 0 && size == PyBytes_GET_SIZE(self->buf) &&
         FT_ATOMIC_LOAD_SSIZE_RELAXED(self->exports) == 0) {
-        self->pos += size;
         return Py_NewRef(self->buf);
     }
 
@@ -444,10 +444,16 @@ read_bytes_lock_held(bytesio *self, Py_ssize_t size)
     }
 
     output = PyBytes_AS_STRING(self->buf) + self->pos;
-    self->pos += size;
     return PyBytes_FromStringAndSize(output, size);
 }
 
+static PyObject *
+read_bytes_lock_held(bytesio *self, Py_ssize_t size) {
+    PyObject *bytes = peek_bytes_lock_held(self, size);
+    self->pos += size;
+    return bytes;
+}
+
 /*[clinic input]
 @critical_section
 _io.BytesIO.read
@@ -502,17 +508,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;
 
@@ -525,11 +532,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_lock_held(self, size);
-    self->pos = prev_pos;
-
-    return result;
+    return peek_bytes_lock_held(self, size);
 }