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

Brett Cannon report at bugs.python.org
Wed Aug 22 12:50:23 EDT 2018

Brett Cannon <brett at python.org> added the comment:

Please don't use over-the-top language like "completely unjustifiable" because it is unnecessary and in this case wrong. We treat our documentation as a recording of the semantics of the stdlib as well as a recording of what semantic changes occurred between versions. Something did change semantically and so it should be documented. Whether the way the docs have previously been written would have suggested that someone accidentally used keyword arguments is not the critical point. Anyone could have looked at e.g. help() or simply stumbled upon the fact keyword arguments used to work and then suddenly discovered they didn't. At that point it's more helpful to the user to know when that changed occurred then to try and minimize the amount of text in the  docs simply because they happened to have not been written to suggest keyword arguments worked when they, in fact, did.

IOW adding a "version changed" note is not bloat, it's about letting people know who happened to have used keyword arguments what version of Python is going to break their code.


Python tracker <report at bugs.python.org>

More information about the docs mailing list