classification
Title: bytes.translate() doesn't take keyword arguments; docs suggests it does
Type: Stage:
Components: Documentation, Library (Lib) Versions: Python 3.5
process
Status: closed Resolution: duplicate
Dependencies: Superseder: accept keyword arguments on most base type methods and builtins
View: 8706
Assigned To: docs@python Nosy List: SilentGhost, docs@python, martin.panter, nchammas, terry.reedy
Priority: normal Keywords:

Created on 2016-02-10 19:52 by nchammas, last changed 2016-02-14 10:51 by martin.panter. This issue is now closed.

Messages (6)
msg260034 - (view) Author: Nicholas Chammas (nchammas) * Date: 2016-02-10 19:52
The docs for `bytes.translate()` [0] show the following signature:

```
bytes.translate(table[, delete])
```

However, calling this method with keyword arguments yields:

```
>>> b''.translate(table='la table', delete=b'delete')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: translate() takes no keyword arguments
```

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
msg260035 - (view) Author: SilentGhost (SilentGhost) * (Python triager) Date: 2016-02-10 20:21
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.
msg260039 - (view) Author: Nicholas Chammas (nchammas) * Date: 2016-02-10 21:31
So you're saying if `bytes.translate()` accepted keyword arguments, its signature would look something like this?

```
bytes.translate(table, delete=None)
```

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.
msg260211 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-02-12 23:22
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.
msg260214 - (view) Author: Nicholas Chammas (nchammas) * Date: 2016-02-12 23:41
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()`?
msg260272 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-02-14 10:51
Nicholas, there is Issue 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 Issue 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

bytes.translate(table, delete=b"", /)

And there is Issue 21314 about where to document the slash notation that is already used in pydoc.
History
Date User Action Args
2016-02-14 10:51:23martin.pantersetsuperseder: accept keyword arguments on most base type methods and builtins

messages: + msg260272
nosy: + martin.panter
2016-02-12 23:41:53nchammassetstatus: open -> closed
resolution: duplicate
messages: + msg260214
2016-02-12 23:22:20terry.reedysetnosy: + terry.reedy
messages: + msg260211
2016-02-10 21:31:38nchammassetmessages: + msg260039
2016-02-10 20:21:17SilentGhostsetnosy: + SilentGhost
messages: + msg260035
2016-02-10 19:52:44nchammascreate