Repository navigation
bytes.translate() doesn't take keyword arguments; docs suggests it does #70522
Description
| BPO | 26334 |
|---|---|
| Nosy | @terryjreedy, @vadmium, @nchammas |
| Superseder |
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 = <Date 2016-02-12.23:41:53.523>
created_at = <Date 2016-02-10.19:52:44.438>
labels = ['library', 'docs']
title = "bytes.translate() doesn't take keyword arguments; docs suggests it does"
updated_at = <Date 2016-02-14.10:51:23.417>
user = 'https://github.com/nchammas'bugs.python.org fields:
activity = <Date 2016-02-14.10:51:23.417>
actor = 'martin.panter'
assignee = 'docs@python'
closed = True
closed_date = <Date 2016-02-12.23:41:53.523>
closer = 'nchammas'
components = ['Documentation', 'Library (Lib)']
creation = <Date 2016-02-10.19:52:44.438>
creator = 'nchammas'
dependencies = []
files = []
hgrepos = []
issue_num = 26334
keywords = []
message_count = 6.0
messages = ['260034', '260035', '260039', '260211', '260214', '260272']
nosy_count = 5.0
nosy_names = ['terry.reedy', 'SilentGhost', 'docs@python', 'martin.panter', 'nchammas']
pr_nums = []
priority = 'normal'
resolution = 'duplicate'
stage = None
status = 'closed'
superseder = '8706'
type = None
url = 'https://bugs.python.org/issue26334'
versions = ['Python 3.5']
Activity
nchammas commentedon Feb 10, 2016
The docs for
bytes.translate()[0] show the following signature:However, calling this method with keyword arguments yields:
I'm guessing other methods have this same issue. (e.g.
str.translate())Do the docs need to be updated, or should these methods be updated to accept keyword arguments, or something else?
[0] https://docs.python.org/3/library/stdtypes.html#bytes.translate
SilentGhost commentedon Feb 10, 2016
I don't think docs suggest that in any way. The keyword arguments are typically described like this: https://docs.python.org/3/library/stdtypes.html#str.split
bytes.translate has a typical signature of a function with optional positional arguments.
nchammas commentedon Feb 10, 2016
So you're saying if
bytes.translate()accepted keyword arguments, its signature would look something like this?I guess I was under the mistaken assumption that argument names in the docs always matched keyword arguments in the signature.
But you're right, a strictly positional argument (I guess specified via something like
args*?) doesn't have a name.terryjreedy commentedon Feb 12, 2016
This is a known, generic issue with c-coded functions. Some C functions have been converted, especially those with boolean parameters, and especially those with multiple boolean parameters.
I think, but an not sure, that / is sometimes used to signal that the preceding are position only, and that this may have something to do with ArgumentClinic. I also would like a consistent indication. But this may be a duplicate issue.
nchammas commentedon Feb 12, 2016
Yep, you're right. I'm just understanding now that we have lots of methods defined in C which have signatures like this.
Is there an umbrella issue, perhaps, that covers adding support for keyword-based arguments to functions defined in C, like
translate()?vadmium commentedon Feb 14, 2016
Nicholas, there is bpo-8706 about converting functions and methods to accept keywords in general.
There is also the slash “/” indicator proposed by PEP-457, which is used for some functions in pydoc; bytes.replace() for instance. In bpo-23738 I was trying to get some consensus on using this slash notation in the main documentation, in which case bytes.translate() could look like
And there is bpo-21314 about where to document the slash notation that is already used in pydoc.