classification
Title: itertools.groupby has misleading doc string
Type: Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: docs@python, gmathews, josh.r, r.david.murray, rhettinger
Priority: low Keywords: patch

Created on 2016-06-24 20:58 by gmathews, last changed 2017-09-25 08:43 by rhettinger. This issue is now closed.

Files
File name Uploaded Description Edit
groupby_doc.patch gmathews, 2016-06-24 20:58 review
groupbydoc.diff rhettinger, 2016-06-28 15:22 Update doc string and main docs. review
Pull Requests
URL Status Linked Edit
PR 3738 merged rhettinger, 2017-09-24 22:18
PR 3744 merged python-dev, 2017-09-25 08:21
Messages (7)
msg269211 - (view) Author: Grant Mathews (gmathews) * Date: 2016-06-24 20:58
The itertools.groupby function is generally well-documented, but the fact that it only groups consecutive occurrences of keys is not mentioned in the doc string, which is where that information is most needed.
msg269218 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-06-25 02:24
The patch is fine.
msg269434 - (view) Author: Josh Rosenberg (josh.r) * (Python triager) Date: 2016-06-28 14:42
While you're fixing, the docstring should say "groupby(iterable, key=None)", not "groupby(iterable[, keyfunc])"; the functions accepts the key function by name, and the name is key, not keyfunc. And it can be passed explicitly as None (equivalent to not passing it at all), so the [, keyfunc] approach that indicates it's positional only and can't be explicitly passed as a default is wrong. Gets a little confusing because it also returns a "key", but the argument is definitely named "key", so we can't go calling it "keyfunc".

Mind you, seems like this could also be fixed by just Clinic-ifying it.
msg269435 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-06-28 14:50
Please open a separate issue for that problem.
msg269438 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-06-28 15:16
That's okay.  I'm taking care of both in this issue.
msg302922 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-09-25 08:21
New changeset 49392c63a243052c8013bef80d35202bb6d7c404 by Raymond Hettinger in branch 'master':
bpo-27385: Clarify docstring for groupby() (#3738)
https://github.com/python/cpython/commit/49392c63a243052c8013bef80d35202bb6d7c404
msg302926 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-09-25 08:41
New changeset e2a30cd35b95dad55aea10347655f246348d1951 by Raymond Hettinger (Miss Islington (bot)) in branch '3.6':
[3.6] bpo-27385: Clarify docstring for groupby() (GH-3738) (#3744)
https://github.com/python/cpython/commit/e2a30cd35b95dad55aea10347655f246348d1951
History
Date User Action Args
2017-09-25 08:43:03rhettingersetstatus: open -> closed
stage: patch review -> resolved
resolution: fixed
versions: + Python 3.7, - Python 2.7, Python 3.5
2017-09-25 08:41:52rhettingersetmessages: + msg302926
2017-09-25 08:21:17python-devsetpull_requests: + pull_request3731
2017-09-25 08:21:08rhettingersetmessages: + msg302922
2017-09-24 22:18:35rhettingersetpull_requests: + pull_request3724
2016-06-28 15:22:26rhettingersetfiles: + groupbydoc.diff
2016-06-28 15:16:34rhettingersetmessages: + msg269438
2016-06-28 14:50:23r.david.murraysetnosy: + r.david.murray
messages: + msg269435
2016-06-28 14:42:50josh.rsetnosy: + josh.r
messages: + msg269434
2016-06-25 02:24:31rhettingersetpriority: normal -> low
assignee: docs@python -> rhettinger
messages: + msg269218
2016-06-24 23:03:07ned.deilysetnosy: + rhettinger
stage: patch review

versions: - Python 3.2, Python 3.3, Python 3.4
2016-06-24 20:58:00gmathewscreate