Docs and docstrings for io.*.seek are inconsistent

[MatthiasWiesmann]

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

[sunmy2019]

Note: If anything is changed here, the relevant doc should also be changed.
https://docs.python.org/3/library/io.html#io.IOBase.seek

[AA-Turner]

@MatthiasWiesmann would you have time to write a PR with suggestied revisions of the help text?

To note, Python 3.12 will include the constants in os (see #104418), though there is quite a bit of inconsistency between the various seek() methods' docstrings:

• cpython/Modules/_io/iobase.c

  Lines 82 to 99 in 2e27da1

  	/*[clinic input]
  	_io._IOBase.seek
  	cls: defining_class
  	offset: int(unused=True)
  	whence: int(unused=True, c_default='0') = os.SEEK_SET
  	/
  	Change the stream position to the given byte offset.
  	The offset is interpreted relative to the position indicated by whence.
  	Values for whence are:
  	* os.SEEK_SET or 0 -- start of stream (the default); offset should be zero or positive
  	* os.SEEK_CUR or 1 -- current stream position; offset may be negative
  	* os.SEEK_END or 2 -- end of stream; offset is usually negative
  	Return the new absolute position.
  	[clinic start generated code]*/

• cpython/Modules/_io/bufferedio.c

  Lines 1285 to 1290 in 2e27da1

  	/*[clinic input]
  	_io._Buffered.seek
  	target as targetobj: object
  	whence: int = 0
  	/
  	[clinic start generated code]*/

• cpython/Modules/_io/bytesio.c

  Lines 637 to 650 in 2e27da1

  	/*[clinic input]
  	_io.BytesIO.seek
  	pos: Py_ssize_t
  	whence: int = 0
  	/
  	Change stream position.
  	Seek to byte offset pos relative to position indicated by whence:
  	0 Start of stream (the default). pos should be >= 0;
  	1 Current position - pos may be negative;
  	2 End of stream - pos usually negative.
  	Returns the new absolute position.
  	[clinic start generated code]*/

• cpython/Modules/_io/fileio.c

  Lines 954 to 969 in 2e27da1

  	/*[clinic input]
  	_io.FileIO.seek
  	pos: object
  	whence: int = 0
  	/
  	Move to new file position and return the file position.
  	Argument offset is a byte count. Optional argument whence defaults to
  	SEEK_SET or 0 (offset from start of file, offset should be >= 0); other values
  	are SEEK_CUR or 1 (move relative to current position, positive or negative),
  	and SEEK_END or 2 (move relative to end of file, usually negative, although
  	many platforms allow seeking beyond the end of a file).
  	Note that not all file objects are seekable.
  	[clinic start generated code]*/

• cpython/Modules/_io/stringio.c

  Lines 464 to 477 in 2e27da1

  	/*[clinic input]
  	_io.StringIO.seek
  	pos: Py_ssize_t
  	whence: int = 0
  	/
  	Change stream position.
  	Seek to character offset pos relative to position indicated by whence:
  	0 Start of stream (the default). pos should be >= 0;
  	1 Current position - pos must be 0;
  	2 End of stream - pos must be 0.
  	Returns the new absolute position.
  	[clinic start generated code]*/

• cpython/Modules/_io/textio.c

  Lines 2428 to 2433 in 2e27da1

  	/*[clinic input]
  	_io.TextIOWrapper.seek
  	cookie as cookieObj: object
  	whence: int = 0
  	/
  	[clinic start generated code]*/

cc @erlend-aasland as the author of #104418 if you have any thoughts.

A

[erlend-aasland]

I agree that it is confusing that the parameter names for the low-level API seek() aren't used consistently throughout the docs/docstrings. Luckily, these are all positional-only, so we can easily normalise them without backwards compatibility concerns.

Suggested improvements:

• Consistently name the seek() params
• Consistently use io.SEEK_* constants instead of os.SEEK_*
• Document io.SEEK_ constants

[serhiy-storchaka]

1. The confusion is caused by the fact that TextIOWrapper.seek() has no docstring, so pydoc shows a docstring from a parent class, which is inadequate due to significant difference in semantic.
2. The first argument of TextIOWrapper.seek() is not a byte offset, and not an offset at all. It is a "cookie", i.e. zero or an opaque number returned by tell(). Passing anything other than zero and the value returned by tell() when whence=SEEK_SET has undefined behavior.
3. SEEK_CUR and SEEK_END only support zero as the first argument.

Neither forward seeking nor backward seeking are supported. The only supported are rewinding to the start and restoring the previous position saved by tell(). Confusion could be avoided if TextIOWrapper.tell() returned a special type instead of integer, but for now it would be a large breaking change (because the cookie can be saved in a file as an integer and used in other process).

[erlend-aasland]

As a data point: on macOS, Linux, and FreeBSD, the lseek and fseek manpages uses offset and whence as parameter names.

[serhiy-storchaka]

Because they only work with binary files. They do not work with TextIOWrapper which support multibyte stateful codecs.