Documentation

The documentation on text handles is misleading, in particular for the seek method.

Steps to reproduce

handle = open('/tmp/lines.txt') help(handle.seek) 

This produces the following documentation:

Help on built-in function seek: seek(cookie, whence=0, /) method of _io.TextIOWrapper instance Change stream position. Change the stream position to the given byte offset. The offset is interpreted relative to the position indicated by whence. Values for whence are: * 0 -- start of stream (the default); offset should be zero or positive * 1 -- current stream position; offset may be negative * 2 -- end of stream; offset is usually negative Return the new absolute position. 

Issues

• The documentation talks about a byte offset, but the interface mentions a cookie.
• The constants defined in os module, like os.SEEK_END are not mentioned.
• whence=2 with negative offset fails.

Generally, the behaviour is very inconsistent, seek relative to the end fail, seek relative to the start works, but might yield a situation when read fails.

Full investigation of the issue

Linked PRs

• gh-107801: Improve io.*.seek docs and docstrings #107899
• gh-107801: Improve the accuracy of io.TextIOWrapper.seek docs #107933
• gh-107801: Improve the accuracy of os.lseek docs #107935
• gh-107801: Document SEEK_HOLE and SEEK_DATA #107936
• [3.12] gh-107801: Document SEEK_HOLE and SEEK_DATA (GH-107936) #108086
• [3.11] gh-107801: Document SEEK_HOLE and SEEK_DATA (GH-107936) #108087
• gh-107801: Improve the docs of the SEEK_* constants #108099
• [3.11] gh-107801: Improve the docs of the SEEK_* constants (GH-108099) #108100
• [3.12] gh-107801: Improve the docs of the SEEK_* constants (#108099) #108108
• [3.12] gh-107801: Improve the accuracy of os.lseek docs (#107935) #108136
• [3.11] gh-107801: Improve the accuracy of os.lseek docs (#107935) #108137
• [3.12] gh-107801: Improve the accuracy of io.TextIOWrapper.seek docs (#107933) #108262
• [3.11] gh-107801: Improve the accuracy of io.TextIOWrapper.seek docs (#107933) #108264
• gh-107801: Document io.TextIOWrapper.tell #108265
• gh-107801: Improve the accuracy of io.IOBase.seek docs #108268
• [3.12] gh-107801: Document io.TextIOWrapper.tell (#108265) #108547
• [3.11] gh-107801: Document io.TextIOWrapper.tell (#108265) #108548
• [3.12] gh-107801: Improve the accuracy of io.IOBase.seek docs (#108268) #108655
• [3.11] gh-107801: Improve the accuracy of io.IOBase.seek docs (#108268) #108656