[docs] [issue34434] Removal of kwargs for built-in types not covered with "changed in Python" note in documentation

Josh Rosenberg report at bugs.python.org
Wed Aug 22 11:17:40 EDT 2018


Josh Rosenberg <shadowranger+python at gmail.com> added the comment:

Bloating the documentation is almost certainly unjustifiable for list and tuple, and only barely justifiable for int, bool and float, given that:

1. The documentation (at least for Python 3) has *never* claimed the arguments could be passed by keyword (all of them used brackets to indicate the argument was optional without implying a meaningful default, which is typically how "does not take arguments by keyword" was described before the current "/" convention)

and

2. Aside from bool and float (and to a lesser extent, int), the documented name of said parameter didn't match the name it was accepted under, e.g.:

   a. The docs for tuple and list claimed the name was "iterable"; the only accepted name was "sequence"
   b. The online docs for int gave a wholly invalid "name", calling it "number | string", when in fact it was accepted only as "x". That said, int's docstring does describe the name "correctly" as "x"

So for tuple/list it would have been impossible to write code that depended on being able to pass the first parameter by keyword unless you'd gone mucking about in the CPython source code to figure out the secret keyword name. I could justify a note for int/bool/float given that the docstrings for all of them named the argument, and bool/float named it in the online docs, but we don't need to document a change that no one could have taken a dependency on without going to extreme trouble.

----------
nosy: +josh.r

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


More information about the docs mailing list