Skip to content

[3.11] gh-107801: Improve the accuracy of io.IOBase.seek docs (#108268) #108656

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 29, 2023
Merged

[3.11] gh-107801: Improve the accuracy of io.IOBase.seek docs (#108268) #108656

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 14 additions & 12 deletions Doc/library/io.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -403,20 +403,19 @@ 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
be negative
* :data:`!SEEK_END` or ``2`` -- end of the stream; *offset* is usually
negative

Return the new absolute position.
* :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

.. versionadded:: 3.1
The :data:`!SEEK_*` constants.
Expand Down Expand Up @@ -1061,14 +1060,17 @@ 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`.

.. method:: tell()

Return the stream position as an opaque number.
The return value of :meth:`!tell` can be given as input to :meth:`seek`,
to restore a previous stream position.



.. class:: StringIO(initial_value='', newline='\n')

A text stream using an in-memory text buffer. It inherits
Expand Down
21 changes: 14 additions & 7 deletions Modules/_io/iobase.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,15 +82,22 @@ iobase_unsupported(const char *message)
/* Positioning */

PyDoc_STRVAR(iobase_seek_doc,
"Change stream position.\n"
"seek($self, offset, whence=os.SEEK_SET, /)\n"
"--\n"
"\n"
"Change the stream position to the given byte offset. The offset is\n"
"interpreted relative to the position indicated by whence. Values\n"
"for whence are:\n"
"Change the stream position to the given byte offset.\n"
"\n"
"* 0 -- start of stream (the default); offset should be zero or positive\n"
"* 1 -- current stream position; offset may be negative\n"
"* 2 -- end of stream; offset is usually negative\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"
"* os.SEEK_SET or 0 -- start of stream (the default); offset should be zero or positive\n"
"* os.SEEK_CUR or 1 -- current stream position; offset may be negative\n"
"* os.SEEK_END or 2 -- end of stream; offset is usually negative\n"
"\n"
"Return the new absolute position.");

Expand Down