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

[Josh Rosenberg]

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

For tuple and list, no, they couldn't have looked at the help (because the help calls the argument "iterable", while the only keyword accepted was "sequence"). Nor was "sequence" documented in the online docs, nor anywhere else that I can find; it was solely in the C source code.

If it was discoverable in any other way, I wouldn't say documenting the change (outside of What's New) was completely unjustifiable (I acknowledge that int, bool and float warrant a mention, since they did document a functioning name for the argument; I was a little too down on them in my original messages).

But the only way someone would accidentally use keyword arguments for list/tuple is if they were fuzzing the constructor by submitting random keyword arguments until something worked. That seems an odd thing to worry about breaking. The error message wouldn't help either; the exception raised tells you what argument was unrecognized, but not the names of recognized arguments.

Even if you want to document it, it's hard to do so without being confusing, inaccurate, or both. The original PR's versionchanged message was:

*iterable* is now a positional-only parameter.

But "iterable" was never a legal keyword, so saying it's "now a positional-only parameter" implies that at some point, it wasn't, and you could pass it with the name "iterable", which is wrong/confusing. If you mention "sequence", you're mentioning a now defunct detail (confusing, but not wrong). I suppose you could have the versionchanged say "This function does not accept keyword arguments", but again, for all discoverable purposes, it never did.

I'm not saying *no* documentation of the change is needed, but I am saying, for list/tuple, the What's New note is sufficient to cover it for those people who went mucking through the CPython source code to find an undocumented keyword they could use.

----------

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