From 44c6575b026a0bb3ee9e59f1e25e13dc37e159ee Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 22 Aug 2023 10:35:15 +0200 Subject: [PATCH 1/4] gh-107801: Improve the accuracy of io.IOBase.seek docs - Add param docstrings - Link to os.SEEK_* constants - Mention the return value in the initial paragraph --- Doc/library/io.rst | 21 ++++++++++++--------- Modules/_io/clinic/iobase.c.h | 7 ++++++- Modules/_io/iobase.c | 4 +++- 3 files changed, 21 insertions(+), 11 deletions(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 792bf43d9811bb..592a46fb778bd4 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -403,21 +403,20 @@ I/O Base Classes Note that it's already possible to iterate on file objects using ``for line in file: ...`` without calling :meth:`!file.readlines`. - .. method:: seek(offset, whence=SEEK_SET, /) + .. method:: seek(offset, whence=os.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*, + interpreted relative to the position indicated by *whence*, + and return the new absolute position. + Values for *whence* are: - * :data:`!SEEK_SET` or ``0`` -- start of the stream (the default); + * :data:`os.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 + * :data:`os.SEEK_CUR` or ``1`` -- current stream position; *offset* may be negative - * :data:`!SEEK_END` or ``2`` -- end of the stream; *offset* is usually + * :data:`os.SEEK_END` or ``2`` -- end of the stream; *offset* is usually negative - Return the new absolute position. - .. versionadded:: 3.1 The :data:`!SEEK_*` constants. @@ -1061,6 +1060,10 @@ Text I/O Any other argument combinations are invalid, and may raise exceptions. + .. seealso:: + + :data:`os.SEEK_SET`, :data:`os.SEEK_CUR`, and :data:`os.SEEK_END`. + .. class:: StringIO(initial_value='', newline='\n') A text stream using an in-memory text buffer. It inherits diff --git a/Modules/_io/clinic/iobase.c.h b/Modules/_io/clinic/iobase.c.h index 773e0010477053..e29a4f182dc03e 100644 --- a/Modules/_io/clinic/iobase.c.h +++ b/Modules/_io/clinic/iobase.c.h @@ -14,6 +14,11 @@ PyDoc_STRVAR(_io__IOBase_seek__doc__, "\n" "Change the stream position to the given byte offset.\n" "\n" +" offset\n" +" The stream position, relative to \'whence\'.\n" +" whence\n" +" The relative position to seek from.\n" +"\n" "The offset is interpreted relative to the position indicated by whence.\n" "Values for whence are:\n" "\n" @@ -436,4 +441,4 @@ _io__RawIOBase_readall(PyObject *self, PyObject *Py_UNUSED(ignored)) { return _io__RawIOBase_readall_impl(self); } -/*[clinic end generated code: output=301b22f8f75ce3dc input=a9049054013a1b77]*/ +/*[clinic end generated code: output=7c2df7a330be8b5b input=a9049054013a1b77]*/ diff --git a/Modules/_io/iobase.c b/Modules/_io/iobase.c index 5fd19895311c0c..55508a2214f84d 100644 --- a/Modules/_io/iobase.c +++ b/Modules/_io/iobase.c @@ -83,7 +83,9 @@ iobase_unsupported(_PyIO_State *state, const char *message) _io._IOBase.seek cls: defining_class offset: int(unused=True) + The stream position, relative to 'whence'. whence: int(unused=True, c_default='0') = os.SEEK_SET + The relative position to seek from. / Change the stream position to the given byte offset. @@ -101,7 +103,7 @@ Return the new absolute position. static PyObject * _io__IOBase_seek_impl(PyObject *self, PyTypeObject *cls, int Py_UNUSED(offset), int Py_UNUSED(whence)) -/*[clinic end generated code: output=8bd74ea6538ded53 input=8d4e6adcd08292f2]*/ +/*[clinic end generated code: output=8bd74ea6538ded53 input=74211232b363363e]*/ { _PyIO_State *state = get_io_state_by_cls(cls); return iobase_unsupported(state, "seek"); From a2a6dc54d98455477a59b1b20be3df369bee5588 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 29 Aug 2023 18:57:22 +0200 Subject: [PATCH 2/4] Update io.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/library/io.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 6cc490ebb56307..08348d3933acff 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -412,8 +412,8 @@ I/O Base Classes * :data:`os.SEEK_SET` or ``0`` -- start of the stream (the default); *offset* should be zero or positive - * :data:`os.SEEK_CUR` or ``1`` -- current stream position; *offset* may - be negative + * :data:`os.SEEK_CUR` or ``1`` -- current stream position; + *offset* may be negative * :data:`os.SEEK_END` or ``2`` -- end of the stream; *offset* is usually negative From bdbcf776a1f44dca1a49b2be2bb7ed663c98520e Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 29 Aug 2023 18:57:29 +0200 Subject: [PATCH 3/4] Update io.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/library/io.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 08348d3933acff..71e4913d56fe85 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -414,8 +414,8 @@ I/O Base Classes *offset* should be zero or positive * :data:`os.SEEK_CUR` or ``1`` -- current stream position; *offset* may be negative - * :data:`os.SEEK_END` or ``2`` -- end of the stream; *offset* is usually - negative + * :data:`os.SEEK_END` or ``2`` -- end of the stream; + *offset* is usually negative .. versionadded:: 3.1 The :data:`!SEEK_*` constants. From 3fbef494119d66c795ed5b058df38950ef8230ea Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 29 Aug 2023 19:10:29 +0200 Subject: [PATCH 4/4] Update Doc/library/io.rst --- 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 71e4913d56fe85..01088879218cb4 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -415,7 +415,7 @@ I/O Base Classes * :data:`os.SEEK_CUR` or ``1`` -- current stream position; *offset* may be negative * :data:`os.SEEK_END` or ``2`` -- end of the stream; - *offset* is usually negative + *offset* is usually negative .. versionadded:: 3.1 The :data:`!SEEK_*` constants.