Closed
Description
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
osmodule, likeos.SEEK_ENDare 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