classification
Title: attrgetter and itemgetter signatures in docs need cleanup
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: chris.jerdonek, docs@python, ezio.melotti, mjpieters, python-dev, r.david.murray, zach.ware
Priority: normal Keywords: easy, patch

Created on 2012-11-21 15:16 by r.david.murray, last changed 2013-05-10 16:31 by mjpieters. This issue is now closed.

Files
File name Uploaded Description Edit
issue16523.diff ezio.melotti, 2012-11-23 17:41 Patch against 3.2.
issue16523-2.diff ezio.melotti, 2013-05-01 13:57 review
Messages (9)
msg176060 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-11-21 15:16
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
msg176201 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-23 17:58
+.. 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):
msg176203 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-23 18:05
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.
msg176206 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-23 18:27
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, ...)
msg188226 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-05-01 13:57
Attached an updated patch that uses the double signature.
msg188234 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2013-05-01 17:38
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.
msg188705 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-05-08 07:57
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
msg188706 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-05-08 07:57
Fixed, thanks for the review!
msg188848 - (view) Author: Martijn Pieters (mjpieters) * Date: 2013-05-10 16:31
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
History
Date User Action Args
2013-05-10 16:31:59mjpieterssetnosy: + mjpieters
messages: + msg188848
2013-05-08 07:57:36ezio.melottisetstatus: open -> closed
messages: + msg188706

assignee: docs@python -> ezio.melotti
resolution: fixed
stage: commit review -> resolved
2013-05-08 07:57:05python-devsetnosy: + python-dev
messages: + msg188705
2013-05-01 17:38:35zach.waresetnosy: + zach.ware
messages: + msg188234
2013-05-01 13:57:11ezio.melottisetfiles: + issue16523-2.diff

stage: patch review -> commit review
messages: + msg188226
versions: - Python 3.2
2012-11-23 18:27:47chris.jerdoneksetmessages: + msg176206
2012-11-23 18:05:01ezio.melottisetnosy: + ezio.melotti
messages: + msg176203
2012-11-23 17:58:20chris.jerdoneksetmessages: + msg176201
2012-11-23 17:41:39ezio.melottisetfiles: + issue16523.diff
versions: + Python 3.2
nosy: + chris.jerdonek

keywords: + patch
stage: needs patch -> patch review
2012-11-21 15:31:10eric.araujosetkeywords: + easy
2012-11-21 15:16:06r.david.murraycreate