[issue16556] Update string.Formatter.vformat documentation to say "**kwargs"
New submission from Taavi Burns: The documentation says "**kwds" instead of "**kwargs", which is what the function signature uses. I noticed some other (internally-consistent) occurrences in string.rst. Is there any interest in replacing "**kwds" generally with "**kwargs"? It looks like 327 vs 932 ratio in the docs, and closer to 1185 vs 2361 in the source tree as a whole. Thanks! ---------- assignee: docs@python components: Documentation files: kwds_kwargs.diff keywords: patch messages: 176393 nosy: docs@python, taavi-burns priority: normal severity: normal status: open title: Update string.Formatter.vformat documentation to say "**kwargs" type: enhancement versions: Python 2.7, Python 3.3 Added file: http://bugs.python.org/file28127/kwds_kwargs.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16556> _______________________________________
Éric Araujo added the comment: Hello Taavi! It seems to me there is little value in changing all docs to use “**kwargs” instead of “**kwds”, given that this cannot cause actual problems. The interesting thing is that the function takes keyword args. For string.Formatter.vformat, I see no harm in changing it, but also no value. Core developers tend to resist to aesthetic/cleanup/perfectionism-only changes for the sake of minimizing diff churn, avoiding divergences between versions and not taking unneeded risks (less so for doc changes, but a real concern for code cleanups). Ezio, what do you think? ---------- nosy: +eric.araujo, ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16556> _______________________________________
Taavi Burns added the comment: The issue of churn is totally fair. I'd still advocate for the attached patch, as it's tiny and fixes an inconsistency between the function signature and the docs that are referring to that signature. Thanks! ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16556> _______________________________________
Roundup Robot added the comment: New changeset d805982336a0 by Ezio Melotti in branch '2.7': #16556: Fix inconsistency between kwds and kwargs. Patch by Taavi Burns. http://hg.python.org/cpython/rev/d805982336a0 New changeset 565c3bbed7d3 by Ezio Melotti in branch '3.2': #16556: Fix inconsistency between kwds and kwargs. Patch by Taavi Burns. http://hg.python.org/cpython/rev/565c3bbed7d3 New changeset ae19d86b71c8 by Ezio Melotti in branch '3.3': #16556: merge with 3.2. http://hg.python.org/cpython/rev/ae19d86b71c8 New changeset c28f593ea0cb by Ezio Melotti in branch 'default': #16556: merge with 3.3. http://hg.python.org/cpython/rev/c28f593ea0cb ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16556> _______________________________________
Ezio Melotti added the comment: The patch looked OK, so I committed it. Regarding similar cleanups I think it's OK to do them only if the inconsistency is in the same function. If different functions use kwds or kwargs in different places but they do it consistently, then it doesn't matter. ---------- assignee: docs@python -> ezio.melotti resolution: -> fixed stage: -> committed/rejected status: open -> closed versions: +Python 3.2, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16556> _______________________________________
Éric Araujo added the comment: Oh, I had totally missed that the mismatch was between the function signature in the docs and another part of the doc (I thought it was between the real function signature and the doc). Good catch! ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16556> _______________________________________
Taavi Burns added the comment: Ah, yes, I could have been more clear that I wasn't even looking at the source code itself. :) Thanks! ---------- resolution: fixed -> status: closed -> open versions: -Python 3.2, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16556> _______________________________________
Taavi Burns added the comment: Gak, sorry, didn't mean to change the status and resolution! ---------- resolution: -> fixed status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16556> _______________________________________
Éric Araujo added the comment: Hello Taavi! It seems to me there is little value in changing all docs to use “**kwargs” instead of “**kwds”, given that this cannot cause actual problems. The interesting thing is that the function takes keyword args. For string.Formatter.vformat, I see no harm in changing it, but also no value. Core developers tend to resist to aesthetic/cleanup/perfectionism-only changes for the sake of minimizing diff churn, avoiding divergences between versions and not taking unneeded risks (less so for doc changes, but a real concern for code cleanups). Ezio, what do you think? ---------- nosy: +eric.araujo, ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16556> _______________________________________
Taavi Burns added the comment: The issue of churn is totally fair. I'd still advocate for the attached patch, as it's tiny and fixes an inconsistency between the function signature and the docs that are referring to that signature. Thanks! ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16556> _______________________________________
Roundup Robot added the comment: New changeset d805982336a0 by Ezio Melotti in branch '2.7': #16556: Fix inconsistency between kwds and kwargs. Patch by Taavi Burns. http://hg.python.org/cpython/rev/d805982336a0 New changeset 565c3bbed7d3 by Ezio Melotti in branch '3.2': #16556: Fix inconsistency between kwds and kwargs. Patch by Taavi Burns. http://hg.python.org/cpython/rev/565c3bbed7d3 New changeset ae19d86b71c8 by Ezio Melotti in branch '3.3': #16556: merge with 3.2. http://hg.python.org/cpython/rev/ae19d86b71c8 New changeset c28f593ea0cb by Ezio Melotti in branch 'default': #16556: merge with 3.3. http://hg.python.org/cpython/rev/c28f593ea0cb ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16556> _______________________________________
Ezio Melotti added the comment: The patch looked OK, so I committed it. Regarding similar cleanups I think it's OK to do them only if the inconsistency is in the same function. If different functions use kwds or kwargs in different places but they do it consistently, then it doesn't matter. ---------- assignee: docs@python -> ezio.melotti resolution: -> fixed stage: -> committed/rejected status: open -> closed versions: +Python 3.2, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16556> _______________________________________
Éric Araujo added the comment: Oh, I had totally missed that the mismatch was between the function signature in the docs and another part of the doc (I thought it was between the real function signature and the doc). Good catch! ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16556> _______________________________________
Taavi Burns added the comment: Ah, yes, I could have been more clear that I wasn't even looking at the source code itself. :) Thanks! ---------- resolution: fixed -> status: closed -> open versions: -Python 3.2, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16556> _______________________________________
Taavi Burns added the comment: Gak, sorry, didn't mean to change the status and resolution! ---------- resolution: -> fixed status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16556> _______________________________________
participants (4)
-
Ezio Melotti -
Roundup Robot
-
Taavi Burns
-
Éric Araujo