Hello!
I finally found the complete tell/seek documentation:
https://docs.python.org/3.7/library/io.html#io.TextIOBase.tell
https://docs.python.org/3.7/library/io.html#io.TextIOBase.seek
"""
tell()
Return the current stream position as an opaque number. The number
does not usually represent a number of bytes in the underlying
binary storage.
seek(offset, whence=SEEK_SET)
Change the stream position to the given offset. Behaviour depends on
the whence parameter. The default value for whence is SEEK_SET.
SEEK_SET or 0: seek from the start of the stream (the default);
offset must either be a number returned by TextIOBase.tell(), or
zero. Any other offset value produces undefined behaviour.
SEEK_CUR or 1: “seek” to the current position; offset must be
zero, which is a no-operation (all other values are
unsupported).
SEEK_END or 2: seek to the end of the stream; offset must be
zero (all other values are unsupported).
Return the new absolute position as an opaque number.
New in version 3.1: The SEEK_* constants.
"""
So presumably this is not really a bug. There are plenty of
inconsistencies in the documentation though.
The class hierarchy suggests the only seek/tell implementations one
needs to look up are in IOBase and those have the semantics i was
expecting:
https://docs.python.org/3.7/library/io.html#class-hierarchy
The documentation available from the help() command still reflects the
semantics i was expecting. It does however suggest that the first
argument of seek has been renamed from offset to cookie which the online
documentation has not yet caught up to at:
https://docs.python.org/3.7/library/io.html#class-hierarchy
The documentation for seek from the help() command still refers to
offset though there is now no argument of that name.
>>> help(fh.tell)
Help on built-in function tell:
tell() method of _io.TextIOWrapper instance
Return current stream position.
>>> help(fh.seek)
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.
Best regards
/Ulrik Haugen
