classification
Title: io.[Text]IOBase.seek doesn't take keyword parameter
Type: Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: martin.panter Nosy List: berker.peksag, docs@python, ezio.melotti, introom, martin.panter, python-dev
Priority: normal Keywords: patch

Created on 2015-09-08 13:44 by introom, last changed 2015-09-11 04:46 by martin.panter. This issue is now closed.

Files
File name Uploaded Description Edit
seek.patch introom, 2015-09-08 13:44 review
Messages (6)
msg250200 - (view) Author: shiyao.ma (introom) * Date: 2015-09-08 13:44
The doc is here: https://docs.python.org/3.5/library/io.html#io.IOBase.seek
and here: https://docs.python.org/3.5/library/io.html#io.TextIOBase.seek

It is said the parameter list is in the form of:
seek(offset, whence=SEEK_SET)

But actually only:
seek(offset) or seek(offset, whence) is allowed.

Passing seek(offset, whence=SEEK_FOOBAR) will throw an error.

The patch fixes the function signature as seek(offset[, whence])
msg250261 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-09-08 22:41
This also bugs me, and the same problem exists in other parts of the documentation. Perhaps you might be interested in Issue 23738 and whether changing to the new notation used by PEP 457, pydoc, help(), Argument Clinic is any good:

seek(offset, whence=SEEK_SET, /)

But in the mean time, I think the proposed patch is okay, and would certainly benefit the Python 2 documetation where using the new PEP 457 slash indicator is less likely to be appropriate.
msg250281 - (view) Author: shiyao.ma (introom) * Date: 2015-09-09 04:22
Thanks for your comment.

I had a read of pep457. It's still in draft status, so incorporating
the / indicator is not much a concern AFAIK.

Any further modification for me to do to get that merged?
msg250284 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-09-09 04:50
I will try to commit your patch today when I up to it.

Maybe the “draft” status of that PEP is out of date. The slash (/) indicator is already being used in some places in pydoc, e.g.

$ pydoc object.__eq__
Help on wrapper_descriptor in object:

object.__eq__ = __eq__(self, value, /)
    Return self==value.
msg250445 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-09-11 04:40
New changeset 0ca216f5276e by Martin Panter <vadmium> in branch '3.4':
Issue #25030: Do not document seek() as if it accepts keyword arguments
https://hg.python.org/cpython/rev/0ca216f5276e

New changeset 77784422da4d by Martin Panter <vadmium> in branch '2.7':
Issue #25030: Do not document seek() as if it accepts keyword arguments
https://hg.python.org/cpython/rev/77784422da4d

New changeset a0c6f5358029 by Martin Panter <vadmium> in branch '3.5':
Issue #25030: Merge seek() doc fixes from 3.4 into 3.5
https://hg.python.org/cpython/rev/a0c6f5358029

New changeset c4bb0da8b45e by Martin Panter <vadmium> in branch 'default':
Issue #25030: Merge seek() doc fixes from 3.5
https://hg.python.org/cpython/rev/c4bb0da8b45e
msg250447 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-09-11 04:46
Thanks for the patch. I took the liberty of also fixing the doc string of BytesIO.seek().
History
Date User Action Args
2015-09-11 04:46:29martin.pantersetstatus: open -> closed
resolution: fixed
messages: + msg250447

stage: commit review -> resolved
2015-09-11 04:40:51python-devsetnosy: + python-dev
messages: + msg250445
2015-09-09 04:50:04martin.pantersetassignee: docs@python -> martin.panter
title: io. -> io.[Text]IOBase.seek doesn't take keyword parameter
messages: + msg250284
stage: commit review
2015-09-09 04:22:57introomsetmessages: + msg250281
title: io.[Text]IOBase.seek doesn't take keyword parameter -> io.
2015-09-08 22:41:12martin.pantersetnosy: + martin.panter

messages: + msg250261
versions: + Python 2.7, Python 3.4, Python 3.6
2015-09-08 22:21:43martin.panterlinkissue23738 dependencies
2015-09-08 13:44:41introomcreate