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
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 66273d9..792bf43 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -1044,6 +1044,22 @@
.. 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 5c21625..9bccd71 100644
--- a/Modules/_io/clinic/textio.c.h
+++ b/Modules/_io/clinic/textio.c.h
@@ -756,9 +756,27 @@
}
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 @@
{
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 6ce90b2..d87bd00 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;
