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
Metadata
Metadata
Assignees
Labels
only security fixesonly security fixesonly security fixesonly security fixesbugs and security fixesbugs and security fixesDocumentation in the Doc dirDocumentation in the Doc dirAn unexpected behavior, bug, or errorAn unexpected behavior, bug, or error