gh-107801: Improve io.*.seek docs and docstrings

Doc/library/io.rst

@@ -168,6 +168,19 @@ High-level Module Interface
    :func:`os.stat`) if possible.
 
 
+.. data:: SEEK_SET
+          SEEK_CUR
+          SEEK_END
+
+   Parameters to the :meth:`~IOBase.seek` method,
+   used to specify the relative position
+   Their values are 0, 1, and 2, respectively.
+
+   .. seealso::
+
+      :data:`os.SEEK_SET`, :data:`os.SEEK_CUR`, and :data:`os.SEEK_END`.
+
+
 .. function:: open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)
 
    This is an alias for the builtin :func:`open` function.
@@ -405,18 +418,17 @@ I/O Base Classes
 
    .. method:: seek(offset, whence=SEEK_SET, /)
 
-      Change the stream position to the given byte *offset*.  *offset* is
-      interpreted relative to the position indicated by *whence*.  The default
-      value for *whence* is :data:`SEEK_SET`.  Values for *whence* are:
+      Change the stream position to the given byte *offset*,
+      and return the new absolute position as an integer.
+      *offset* is interpreted relative to the position indicated by *whence*.
+      Valid values for *whence* are:
 
-      * :data:`SEEK_SET` or ``0`` -- start of the stream (the default);
+      * :data:`SEEK_SET` -- seek from the start of the stream (the default);
         *offset* should be zero or positive
-      * :data:`SEEK_CUR` or ``1`` -- current stream position; *offset* may
-        be negative
-      * :data:`SEEK_END` or ``2`` -- end of the stream; *offset* is usually
-        negative
-
-      Return the new absolute position.
+      * :data:`SEEK_CUR` -- seek from current stream position;
+        *offset* may be negative
+      * :data:`SEEK_END` -- seek from the end of the stream;
+        *offset* is usually negative
 
       .. versionadded:: 3.1
          The ``SEEK_*`` constants.
@@ -911,21 +923,22 @@ Text I/O
 
    .. method:: seek(offset, whence=SEEK_SET, /)
 
-      Change the stream position to the given *offset*.  Behaviour depends on
-      the *whence* parameter.  The default value for *whence* is
-      :data:`SEEK_SET`.
-
-      * :data:`SEEK_SET` or ``0``: seek from the start of the stream
-        (the default); *offset* must either be a number returned by
-        :meth:`TextIOBase.tell`, or zero.  Any other *offset* value
-        produces undefined behaviour.
-      * :data:`SEEK_CUR` or ``1``: "seek" to the current position;
-        *offset* must be zero, which is a no-operation (all other values
-        are unsupported).
-      * :data:`SEEK_END` or ``2``: seek to the end of the stream;
-        *offset* must be zero (all other values are unsupported).
-
-      Return the new absolute position as an opaque number.
+      Change the stream position to the given byte *offset*,
+      and return the new absolute position as an opaque number.
+      *offset* is interpreted relative to the position indicated by *whence*.
+      Valid values for *whence* are:
+
+      * :data:`SEEK_SET` -- seek from the start of the stream (the default);
+        *offset* must either be a number returned by
+        :meth:`TextIOBase.tell`, or zero.
+        Any other *offset* value produces undefined behaviour.
+      * :data:`SEEK_CUR` -- seek from current stream position;
+        *offset* must be zero, which is a no-operation.
+        All other values are unsupported.
+      * :data:`SEEK_END` -- seek from the end of the stream;
+        *offset* must be zero.
+        All other values are unsupported.
+
 
       .. versionadded:: 3.1
          The ``SEEK_*`` constants.

Doc/tutorial/inputoutput.rst

@@ -433,10 +433,12 @@ an opaque number when in text mode.
 
 To change the file object's position, use ``f.seek(offset, whence)``.  The position is computed
 from adding *offset* to a reference point; the reference point is selected by
-the *whence* argument.  A *whence* value of 0 measures from the beginning
-of the file, 1 uses the current file position, and 2 uses the end of the file as
-the reference point.  *whence* can be omitted and defaults to 0, using the
-beginning of the file as the reference point. ::
+the *whence* argument.
+A *whence* value of :data:`io.SEEK_SET` measures from the beginning of the file,
+:data:`io.SEEK_CUR` uses the current file position,
+and :data:`io.SEEK_END` uses the end of the file as the reference point.
+*whence* can be omitted and defaults to :data:`!io.SEEK_SET`,
+using the beginning of the file as the reference point. ::
 
    >>> f = open('workfile', 'rb+')
    >>> f.write(b'0123456789abcdef')
@@ -445,14 +447,14 @@ beginning of the file as the reference point. ::
    5
    >>> f.read(1)
    b'5'
-   >>> f.seek(-3, 2)  # Go to the 3rd byte before the end
+   >>> f.seek(-3, io.SEEK_END)  # Go to the 3rd byte before the end
    13
    >>> f.read(1)
    b'd'
 
 In text files (those opened without a ``b`` in the mode string), only seeks
 relative to the beginning of the file are allowed (the exception being seeking
-to the very file end with ``seek(0, 2)``) and the only valid *offset* values are
+to the very file end with ``seek(0, io.SEEK_END)``) and the only valid *offset* values are
 those returned from the ``f.tell()``, or zero. Any other *offset* value produces
 undefined behaviour.
 

Doc/whatsnew/3.1.rst

@@ -367,8 +367,8 @@ New, Improved, and Deprecated Modules
 
   (Contributed by Benjamin Peterson and Antoine Pitrou.)
 
-* The :mod:`io` module has three new constants for the :meth:`seek`
-  method :data:`SEEK_SET`, :data:`SEEK_CUR`, and :data:`SEEK_END`.
+* The :mod:`io` module has three new constants for the :meth:`~io.IOBase.seek`
+  method :data:`~io.SEEK_SET`, :data:`~io.SEEK_CUR`, and :data:`~io.SEEK_END`.
 
 * The :data:`sys.version_info` tuple is now a named tuple::
 

Modules/_io/bufferedio.c

@@ -1284,14 +1284,14 @@ _io__Buffered_tell_impl(buffered *self)
 
 /*[clinic input]
 _io._Buffered.seek
-    target as targetobj: object
-    whence: int = 0
+    offset as targetobj: object
+    whence: int(c_default='0') = io.SEEK_SET
     /
 [clinic start generated code]*/
 
 static PyObject *
 _io__Buffered_seek_impl(buffered *self, PyObject *targetobj, int whence)
-/*[clinic end generated code: output=7ae0e8dc46efdefb input=a9c4920bfcba6163]*/
+/*[clinic end generated code: output=7ae0e8dc46efdefb input=d9ac57b8f178bc05]*/
 {
     Py_off_t target, n;
     PyObject *res = NULL;

Modules/_io/bytesio.c

@@ -636,22 +636,18 @@ bytesio_iternext(bytesio *self)
 
 /*[clinic input]
 _io.BytesIO.seek
-    pos: Py_ssize_t
-    whence: int = 0
+    offset as pos: Py_ssize_t
+    whence: int(c_default='0') = io.SEEK_SET
     /
 
-Change stream position.
+Change stream position and return the new absolute position.
 
-Seek to byte offset pos relative to position indicated by whence:
-     0  Start of stream (the default).  pos should be >= 0;
-     1  Current position - pos may be negative;
-     2  End of stream - pos usually negative.
-Returns the new absolute position.
+Set the byte offset 'offset', relative to position indicated by 'whence':
 [clinic start generated code]*/
 
 static PyObject *
 _io_BytesIO_seek_impl(bytesio *self, Py_ssize_t pos, int whence)
-/*[clinic end generated code: output=c26204a68e9190e4 input=1e875e6ebc652948]*/
+/*[clinic end generated code: output=c26204a68e9190e4 input=dbeeba9f5f031b6e]*/
 {
     CHECK_CLOSED(self);
 

Modules/_io/fileio.c

@@ -953,24 +953,14 @@ portable_lseek(fileio *self, PyObject *posobj, int whence, bool suppress_pipe_er
 
 /*[clinic input]
 _io.FileIO.seek
-    pos: object
-    whence: int = 0
+    offset as pos: object
+    whence: int(c_default='SEEK_SET') = io.SEEK_SET
     /
-
-Move to new file position and return the file position.
-
-Argument offset is a byte count.  Optional argument whence defaults to
-SEEK_SET or 0 (offset from start of file, offset should be >= 0); other values
-are SEEK_CUR or 1 (move relative to current position, positive or negative),
-and SEEK_END or 2 (move relative to end of file, usually negative, although
-many platforms allow seeking beyond the end of a file).
-
-Note that not all file objects are seekable.
 [clinic start generated code]*/
 
 static PyObject *
 _io_FileIO_seek_impl(fileio *self, PyObject *pos, int whence)
-/*[clinic end generated code: output=c976acdf054e6655 input=0439194b0774d454]*/
+/*[clinic end generated code: output=c976acdf054e6655 input=ec74977caf7c656b]*/
 {
     if (self->fd < 0)
         return err_closed();