gh-107801: Improve the accuracy of io.TextIOWrapper.seek docs

Doc/library/io.rst

@@ -255,7 +255,7 @@
 
    .. note::
 
       The abstract base classes also provide default implementations of some
       methods in order to help implementation of concrete stream classes.  For
       example, :class:`BufferedIOBase` provides unoptimized implementations of
       :meth:`~IOBase.readinto` and :meth:`~IOBase.readline`.
@@ -320,7 +320,7 @@
    implementations represent a file that cannot be read, written or
    seeked.
 
    Even though :class:`IOBase` does not declare :meth:`read`
    or :meth:`write` because their signatures will vary, implementations and
    clients should consider those methods part of the interface.  Also,
    implementations may raise a :exc:`ValueError` (or :exc:`UnsupportedOperation`)
@@ -379,7 +379,7 @@
 
    .. method:: readable()
 
       Return ``True`` if the stream can be read from.  If ``False``, :meth:`read`
       will raise :exc:`OSError`.
 
    .. method:: readline(size=-1, /)
@@ -405,15 +405,15 @@
 
    .. 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:
 
       * :data:`SEEK_SET` or ``0`` -- 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.
@@ -422,7 +422,7 @@
          The ``SEEK_*`` constants.
 
       .. versionadded:: 3.3
          Some operating systems could support additional values, like
          :const:`os.SEEK_HOLE` or :const:`os.SEEK_DATA`. The valid values
          for a file could depend on it being open in text or binary mode.
 
@@ -1043,6 +1043,20 @@
       .. versionchanged:: 3.11
          The method supports ``encoding="locale"`` option.
 
+   .. method:: seek(cookie, whence, /)
+
+      Set the stream position and return the current position.
+
+      Four operations are supported,
+      given by the following argument combinations:
+
+      * ``seek(0, SEEK_SET)``: Rewind to the start of the stream.
+      * ``seek(n, SEEK_SET)``: Restore a previous position;
+        'n' is a number returned by :meth:`!tell`.
+      * ``seek(0, SEEK_END)``: Fast-forward to the end of the stream.
+      * ``seek(0, SEEK_CUR)``: Leave the current stream position unchanged.
+
+      Any other argument combinations are undefined behaviour.
 
 .. class:: StringIO(initial_value='', newline='\n')
 

Modules/_io/textio.c

@@ -2428,13 +2428,28 @@ _textiowrapper_encoder_setstate(textio *self, cookie_type *cookie)
 /*[clinic input]
 _io.TextIOWrapper.seek
     cookie as cookieObj: object
-    whence: int = 0
+      Zero or an opaque number returned by tell().
+    whence: int(c_default='0') = os.SEEK_SET
+      The relative position to seek from.
     /
+
+Set the stream position and return the current position.
+
+Four operations are supported, given by the following argument
+combinations:
+
+- seek(0, SEEK_SET): Rewind to the start of the stream.
+- seek(n, SEEK_SET): Restore a previous position;
+  'n' is a number returned by tell().
+- seek(0, SEEK_END): Fast-forward to the end of the stream.
+- seek(0, SEEK_CUR): Leave the current stream position unchanged.
+
+Any other argument combinations are undefined behaviour.
 [clinic start generated code]*/
 
 static PyObject *
 _io_TextIOWrapper_seek_impl(textio *self, PyObject *cookieObj, int whence)
-/*[clinic end generated code: output=0a15679764e2d04d input=0458abeb3d7842be]*/
+/*[clinic end generated code: output=0a15679764e2d04d input=10ce5c609984638a]*/
 {
     PyObject *posobj;
     cookie_type cookie;