From 89607fb8740e3046389129ab085b66b0c30aadc2 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 14 Aug 2023 12:54:17 +0200 Subject: [PATCH 1/5] gh-107801: Improve the accuracy of io.TextIOWrapper.seek docs Clearly document the supported seek() operations: - Rewind to the start of the stream - Restore a previous strema position (given by tell()) - Fast-forward to the end of the stream --- Doc/library/io.rst | 14 ++++++++++++++ Modules/_io/clinic/textio.c.h | 23 ++++++++++++++++++++--- Modules/_io/textio.c | 19 +++++++++++++++++-- 3 files changed, 51 insertions(+), 5 deletions(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 7eec1f87583b87..65db14bc378f02 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -1043,6 +1043,20 @@ Text I/O .. 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') diff --git a/Modules/_io/clinic/textio.c.h b/Modules/_io/clinic/textio.c.h index 5c2162529ff2dd..39bc3a943d9965 100644 --- a/Modules/_io/clinic/textio.c.h +++ b/Modules/_io/clinic/textio.c.h @@ -756,9 +756,26 @@ _io_TextIOWrapper_readline(textio *self, PyObject *const *args, Py_ssize_t nargs } 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 current 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(n, SEEK_SET): Restore a previous position;\n" +" \'n\' is 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 undefined behaviour."); #define _IO_TEXTIOWRAPPER_SEEK_METHODDEF \ {"seek", _PyCFunction_CAST(_io_TextIOWrapper_seek), METH_FASTCALL, _io_TextIOWrapper_seek__doc__}, @@ -957,4 +974,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=02dbfa9a9c038153 input=a9049054013a1b77]*/ diff --git a/Modules/_io/textio.c b/Modules/_io/textio.c index 6ce90b2ed774c0..a363a11ca0561d 100644 --- a/Modules/_io/textio.c +++ b/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; From fe7e7e54041ae5b237f54b888126415d1071e379 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 14 Aug 2023 12:58:24 +0200 Subject: [PATCH 2/5] tell is not documented yet --- Doc/library/io.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 65db14bc378f02..8c6839a24c03da 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -1052,7 +1052,7 @@ Text I/O * ``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`. + '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. From b718c67cec627ee343761eefad27f702dd74e4e3 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 14 Aug 2023 13:00:31 +0200 Subject: [PATCH 3/5] Sphinx syntax --- Doc/library/io.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 8c6839a24c03da..70aae78522bb2c 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -1052,7 +1052,7 @@ Text I/O * ``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`. + '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. From fb86f3b46a446d30a5e774f64d665ee35f88a880 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 14 Aug 2023 22:40:05 +0200 Subject: [PATCH 4/5] Address first batch of reviews --- Doc/library/io.rst | 9 +++++---- Modules/_io/clinic/textio.c.h | 11 ++++++----- Modules/_io/textio.c | 11 ++++++----- 3 files changed, 17 insertions(+), 14 deletions(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 70aae78522bb2c..e4060cf2db3f56 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -1045,18 +1045,19 @@ Text I/O .. method:: seek(cookie, whence, /) - Set the stream position and return the current position. + 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(n, SEEK_SET)``: Restore a previous position; - 'n' is a number returned by :meth:`!tell`. + * ``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 undefined behaviour. + 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 39bc3a943d9965..9bccd71e1d3ea6 100644 --- a/Modules/_io/clinic/textio.c.h +++ b/Modules/_io/clinic/textio.c.h @@ -759,7 +759,7 @@ PyDoc_STRVAR(_io_TextIOWrapper_seek__doc__, "seek($self, cookie, whence=os.SEEK_SET, /)\n" "--\n" "\n" -"Set the stream position and return the current position.\n" +"Set the stream position, and return the new stream position.\n" "\n" " cookie\n" " Zero or an opaque number returned by tell().\n" @@ -770,12 +770,13 @@ PyDoc_STRVAR(_io_TextIOWrapper_seek__doc__, "combinations:\n" "\n" "- seek(0, SEEK_SET): Rewind to the start of the stream.\n" -"- seek(n, SEEK_SET): Restore a previous position;\n" -" \'n\' is a number returned by tell().\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 undefined behaviour."); +"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__}, @@ -974,4 +975,4 @@ _io_TextIOWrapper_close(textio *self, PyObject *Py_UNUSED(ignored)) { return _io_TextIOWrapper_close_impl(self); } -/*[clinic end generated code: output=02dbfa9a9c038153 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=6bd981a58fcbc778 input=a9049054013a1b77]*/ diff --git a/Modules/_io/textio.c b/Modules/_io/textio.c index a363a11ca0561d..d87bd0054d4438 100644 --- a/Modules/_io/textio.c +++ b/Modules/_io/textio.c @@ -2433,23 +2433,24 @@ _io.TextIOWrapper.seek The relative position to seek from. / -Set the stream position and return the current position. +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(n, SEEK_SET): Restore a previous position; - 'n' is a number returned by tell(). +- 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 undefined behaviour. +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=10ce5c609984638a]*/ +/*[clinic end generated code: output=0a15679764e2d04d input=0f68adcb02cf2823]*/ { PyObject *posobj; cookie_type cookie; From 56d196b26d2b84a2c1266e73a03c071803d3db34 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 14 Aug 2023 23:22:21 +0200 Subject: [PATCH 5/5] Break the first sentence up, and remember to include the default value --- Doc/library/io.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index e4060cf2db3f56..cbf4b6bd70add3 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -1043,9 +1043,10 @@ Text I/O .. versionchanged:: 3.11 The method supports ``encoding="locale"`` option. - .. method:: seek(cookie, whence, /) + .. method:: seek(cookie, whence=os.SEEK_SET, /) - Set the stream position, and return the new stream position. + Set the stream position. + Return the new stream position as an :class:`int`. Four operations are supported, given by the following argument combinations: