From 7f87ebbc3f52680c939791f397b9a478edf0c8d4 Mon Sep 17 00:00:00 2001
From: "Erlend E. Aasland" <erlend@python.org>
Date: Tue, 22 Aug 2023 09:37:53 +0200
Subject: [PATCH] gh-107801: Improve the accuracy of io.TextIOWrapper.seek docs
 (#107933)

Clearly document the supported seek() operations:

- Rewind to the start of the stream
- Restore a previous stream position (given by tell())
- Fast-forward to the end of the stream
---
 Doc/library/io.rst            | 16 ++++++++++++++++
 Modules/_io/clinic/textio.c.h | 24 +++++++++++++++++++++---
 Modules/_io/textio.c          | 20 ++++++++++++++++++--
 3 files changed, 55 insertions(+), 5 deletions(-)

diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 66273d9ed1f..792bf43d981 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -1044,6 +1044,22 @@ Text I/O
       .. versionchanged:: 3.11
          The method supports ``encoding="locale"`` option.
 
+   .. method:: seek(cookie, whence=os.SEEK_SET, /)
+
+      Set the stream position.
+      Return the new stream position as an :class:`int`.
+
+      Four operations are supported,
+      given by the following argument combinations:
+
+      * ``seek(0, SEEK_SET)``: Rewind to the start of the stream.
+      * ``seek(cookie, SEEK_SET)``: Restore a previous position;
+        *cookie* **must be** 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 invalid,
+      and may raise exceptions.
 
 .. class:: StringIO(initial_value='', newline='\n')
 
diff --git a/Modules/_io/clinic/textio.c.h b/Modules/_io/clinic/textio.c.h
index 5c2162529ff..9bccd71e1d3 100644
--- a/Modules/_io/clinic/textio.c.h
+++ b/Modules/_io/clinic/textio.c.h
@@ -756,9 +756,27 @@ exit:
 }
 
 PyDoc_STRVAR(_io_TextIOWrapper_seek__doc__,
-"seek($self, cookie, whence=0, /)\n"
+"seek($self, cookie, whence=os.SEEK_SET, /)\n"
 "--\n"
-"\n");
+"\n"
+"Set the stream position, and return the new stream position.\n"
+"\n"
+"  cookie\n"
+"    Zero or an opaque number returned by tell().\n"
+"  whence\n"
+"    The relative position to seek from.\n"
+"\n"
+"Four operations are supported, given by the following argument\n"
+"combinations:\n"
+"\n"
+"- seek(0, SEEK_SET): Rewind to the start of the stream.\n"
+"- seek(cookie, SEEK_SET): Restore a previous position;\n"
+"  \'cookie\' must be a number returned by tell().\n"
+"- seek(0, SEEK_END): Fast-forward to the end of the stream.\n"
+"- seek(0, SEEK_CUR): Leave the current stream position unchanged.\n"
+"\n"
+"Any other argument combinations are invalid,\n"
+"and may raise exceptions.");
 
 #define _IO_TEXTIOWRAPPER_SEEK_METHODDEF    \
     {"seek", _PyCFunction_CAST(_io_TextIOWrapper_seek), METH_FASTCALL, _io_TextIOWrapper_seek__doc__},
@@ -957,4 +975,4 @@ _io_TextIOWrapper_close(textio *self, PyObject *Py_UNUSED(ignored))
 {
     return _io_TextIOWrapper_close_impl(self);
 }
-/*[clinic end generated code: output=e1060638b65e8a63 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=6bd981a58fcbc778 input=a9049054013a1b77]*/
diff --git a/Modules/_io/textio.c b/Modules/_io/textio.c
index 6ce90b2ed77..d87bd0054d4 100644
--- a/Modules/_io/textio.c
+++ b/Modules/_io/textio.c
@@ -2428,13 +2428,29 @@ _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 new stream position.
+
+Four operations are supported, given by the following argument
+combinations:
+
+- seek(0, SEEK_SET): Rewind to the start of the stream.
+- seek(cookie, SEEK_SET): Restore a previous position;
+  'cookie' must be 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 invalid,
+and may raise exceptions.
 [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=0f68adcb02cf2823]*/
 {
     PyObject *posobj;
     cookie_type cookie;