[issue16523] attrgetter and itemgetter signatures in docs need cleanup
New submission from R. David Murray: It looks like the use of the 'args' formal parameter was cut and pasted from the methodcaller docs, when it is not appropriate for itemgetter and attrgetter. http://docs.python.org/3/library/operator.html#operator.attrgetter ---------- assignee: docs@python components: Documentation messages: 176060 nosy: docs@python, r.david.murray priority: normal severity: normal stage: needs patch status: open title: attrgetter and itemgetter signatures in docs need cleanup type: behavior versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- keywords: +easy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- keywords: +patch nosy: +chris.jerdonek stage: needs patch -> patch review versions: +Python 3.2 Added file: http://bugs.python.org/file28089/issue16523.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Chris Jerdonek added the comment: +.. function:: attrgetter(attr[, attr2, attr3, ...]) Why not reword to use the *attr notation? It is even already being used below: + The function is equivalent to:: def attrgetter(*items): if any(not isinstance(item, str) for item in items): ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Ezio Melotti added the comment: I thought about that, but wanted to make a distinction between the form that accepts only 1 arg and returns an item and the form that receives 2+ args and returns a tuple. ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Chris Jerdonek added the comment: You can also make that distinction using *. For example: .. function:: attrgetter(attr, *attrs) or .. function:: attrgetter(attr) attrgetter(attr1, attr2, *attrs) (cf. http://docs.python.org/dev/library/functions.html#max ) Elsewhere we started to prefer using two signature lines where two or more "behaviors" are possible, which might be good to do in any case. With the "..." notation, this would look like: .. function:: attrgetter(attr) attrgetter(attr1, attr2, ...) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Ezio Melotti added the comment: Attached an updated patch that uses the double signature. ---------- stage: patch review -> commit review versions: -Python 3.2 Added file: http://bugs.python.org/file30093/issue16523-2.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Zachary Ware added the comment: I left a couple of Rietveld comments. Other than those nitpicks it looks good to me, and I could be convinced otherwise on the nitpicks :) Also, thanks for catching the extra commas after the "After"s in operator.rst; I had meant to include those in the same patch that took them out of _operator.c, but apparently I missed it. ---------- nosy: +zach.ware _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Roundup Robot added the comment: New changeset 6f2412f12bfd by Ezio Melotti in branch '3.3': #16523: improve attrgetter/itemgetter/methodcaller documentation. http://hg.python.org/cpython/rev/6f2412f12bfd New changeset c2000ce25fe8 by Ezio Melotti in branch 'default': #16523: merge with 3.3. http://hg.python.org/cpython/rev/c2000ce25fe8 New changeset 5885c02120f0 by Ezio Melotti in branch '2.7': #16523: improve attrgetter/itemgetter/methodcaller documentation. http://hg.python.org/cpython/rev/5885c02120f0 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Ezio Melotti added the comment: Fixed, thanks for the review! ---------- assignee: docs@python -> ezio.melotti resolution: -> fixed stage: commit review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Martijn Pieters added the comment: The 2.7 patch shifted the `itemgetter()` signature to above the `attrgetter()` change and new notes. New patch to fix that in issue #17949: http://bugs.python.org/issue17949 ---------- nosy: +mjpieters _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- keywords: +easy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- keywords: +patch nosy: +chris.jerdonek stage: needs patch -> patch review versions: +Python 3.2 Added file: http://bugs.python.org/file28089/issue16523.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Chris Jerdonek added the comment: +.. function:: attrgetter(attr[, attr2, attr3, ...]) Why not reword to use the *attr notation? It is even already being used below: + The function is equivalent to:: def attrgetter(*items): if any(not isinstance(item, str) for item in items): ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Ezio Melotti added the comment: I thought about that, but wanted to make a distinction between the form that accepts only 1 arg and returns an item and the form that receives 2+ args and returns a tuple. ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Chris Jerdonek added the comment: You can also make that distinction using *. For example: .. function:: attrgetter(attr, *attrs) or .. function:: attrgetter(attr) attrgetter(attr1, attr2, *attrs) (cf. http://docs.python.org/dev/library/functions.html#max ) Elsewhere we started to prefer using two signature lines where two or more "behaviors" are possible, which might be good to do in any case. With the "..." notation, this would look like: .. function:: attrgetter(attr) attrgetter(attr1, attr2, ...) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Ezio Melotti added the comment: Attached an updated patch that uses the double signature. ---------- stage: patch review -> commit review versions: -Python 3.2 Added file: http://bugs.python.org/file30093/issue16523-2.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Zachary Ware added the comment: I left a couple of Rietveld comments. Other than those nitpicks it looks good to me, and I could be convinced otherwise on the nitpicks :) Also, thanks for catching the extra commas after the "After"s in operator.rst; I had meant to include those in the same patch that took them out of _operator.c, but apparently I missed it. ---------- nosy: +zach.ware _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Roundup Robot added the comment: New changeset 6f2412f12bfd by Ezio Melotti in branch '3.3': #16523: improve attrgetter/itemgetter/methodcaller documentation. http://hg.python.org/cpython/rev/6f2412f12bfd New changeset c2000ce25fe8 by Ezio Melotti in branch 'default': #16523: merge with 3.3. http://hg.python.org/cpython/rev/c2000ce25fe8 New changeset 5885c02120f0 by Ezio Melotti in branch '2.7': #16523: improve attrgetter/itemgetter/methodcaller documentation. http://hg.python.org/cpython/rev/5885c02120f0 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Ezio Melotti added the comment: Fixed, thanks for the review! ---------- assignee: docs@python -> ezio.melotti resolution: -> fixed stage: commit review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
Martijn Pieters added the comment: The 2.7 patch shifted the `itemgetter()` signature to above the `attrgetter()` change and new notes. New patch to fix that in issue #17949: http://bugs.python.org/issue17949 ---------- nosy: +mjpieters _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16523> _______________________________________
participants (7)
-
Chris Jerdonek -
Ezio Melotti
-
Martijn Pieters
-
R. David Murray
-
Roundup Robot
-
Zachary Ware
-
Éric Araujo