[New-bugs-announce] [issue38788] Inconsistent documentation of tell/seek on textiobase/textiowrapper

[Ulrik Haugen]

New submission from Ulrik Haugen <qha at lysator.liu.se>:

The class hierarchy suggests the only tell/seek implementations one
needs to look up are in iobase and those have the semantics i was
expecting:
https://docs.python.org/3.8/library/io.html#class-hierarchy

Plowing on one might discover that there are separate implementations
of tell/seek for textiobase whose documentation probably explains the
unexpected values tell returns.


The documentation for tell available from the help() command still
reflects the semantics i was expecting.

The documentation for seek available from the help() command still
reflects the semantics i was expecting. It does however suggest that
the first argument has been renamed from offset to cookie which the
online documentation has not yet caught up to at:
https://docs.python.org/3.8/library/io.html#io.TextIOBase.seek

The documentation body 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.

----------
components: Library (Lib)
messages: 356534
nosy: qha
priority: normal
severity: normal
status: open
title: Inconsistent documentation of tell/seek on textiobase/textiowrapper
versions: Python 3.8

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue38788>
_______________________________________