io.[Text]IOBase.seek doesn't take keyword parameter - revisited

[andy-maier]

BPO	41698
Nosy	@methane, @andy-maier, @tomerv

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-09-03.01:32:40.652>
labels = ['3.8', 'docs']
title = "io.[Text]IOBase.seek doesn't take keyword parameter - revisited"
updated_at = <Date 2021-10-21.05:52:51.694>
user = 'https://github.com/andy-maier'

bugs.python.org fields:

activity = <Date 2021-10-21.05:52:51.694>
actor = 'tomerv'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-09-03.01:32:40.652>
creator = 'andymaier'
dependencies = []
files = []
hgrepos = []
issue_num = 41698
keywords = []
message_count = 5.0
messages = ['376272', '376273', '376274', '376277', '404569']
nosy_count = 4.0
nosy_names = ['methane', 'docs@python', 'andymaier', 'tomerv']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue41698'
versions = ['Python 3.8']

[andy-maier]

I stumbled across the problem reported in https://bugs.python.org/issue25030 on Python 3.8:

>>> with open('x.txt', 'a') as fp:
...   fp.seek(0, whence=os.SEEK_END)
... 
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
TypeError: seek() takes no keyword arguments

Which I coded with a keyword argument because the documentation says so:

   seek(offset, whence=SEEK_SET)

See https://docs.python.org/3.8/library/io.html#io.IOBase.seek

The fix for issue bpo-25030 changed the documentation to:

   seek(offset[, whence])

and supposedly was integrated into 2.7, 3.4, and the default branch back then.

It seems the fix got lost?

[methane]

For the record, https://github.com/python/cpython/pull/14691/files reintroduced whence=SEEK_SET.

[methane]

Since we have positional-only argument, can we document it as seek(offset, whence=SEEK_SET, /)?

[andy-maier]

Thanks for referencing the PR that reintroduced the old way of documenting it.

From my perspective, the proposal is fine. There are already some cases where it is documented like that, e.g. str.removeprefix(prefix, /).

[tomerv]

Just wanted to add that I encountered this today, went to file a ticket, and found this one. I'm fine with either style of documentation.

[JelleZijlstra]

Thanks for the patches @slateny!