This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Documentation of itertools.accumulate is confused
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: akuchling Nosy List: MLModel, akuchling, chrish42, docs@python, ezio.melotti, python-dev, rhettinger, terry.reedy
Priority: low Keywords: easy, patch

Created on 2014-01-01 16:12 by MLModel, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
accumulate_doc.patch chrish42, 2014-04-14 19:00 review
accumulate2.diff chrish42, 2014-04-15 15:52 Second (final) revision of the doc patch for accumulate. review
Messages (6)
msg207135 - (view) Author: Mitchell Model (MLModel) Date: 2014-01-01 16:12
The documentation of itertools.accumulate (10.1) starts out with 2 misleading sentences: "Make an iterator that returns accumulated sums. Elements may be any addable type..." It then goes on to show examples of using the func parameter added in 3.3 that are not additions. It should be changed to something like: "Make an iterator that returns accumulated values. Elements may be any type that can be an argument to func. Func defaults to addition, so by default elements can be any addable types, ..." My wording is awkward, but you get the idea. I think this is a significant documentation issue, not just a nit.
msg207260 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-01-04 00:17
Somewhat orthogonal to Mitchell's suggestion, I would change 'returns' to 'yields' and expand 'elements' to 'elements of *iterable*'.
msg216172 - (view) Author: Christian Hudon (chrish42) * Date: 2014-04-14 19:00
The following patch improves (I hope) the documentation of itertools.accumulate. Comments and feedback welcome.

Terry, I did not implement your suggestion of changing "returns" to "yields", as it would have made things inconsistent with the documentation (and docstrings) of pretty much all the other generators in the itertools module, as they all use this idiom also. If one of the Python documentation experts thinks this change is also a good idea, please just open a new bug report for that and put me in the nosy list, and I'll do the change for all relevant generators in the itertools module.
msg216321 - (view) Author: Christian Hudon (chrish42) * Date: 2014-04-15 15:52
Second revision, incorporating comments. Also document the behavior when passed an empty input iterable.
msg216419 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-04-16 02:29
New changeset 9e1d2150fff2 by Andrew Kuchling in branch 'default':
#20103: Rewrite description of itertools.accumulate().
http://hg.python.org/cpython/rev/9e1d2150fff2
msg216420 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2014-04-16 02:30
Thanks for your patch!
History
Date User Action Args
2022-04-11 14:57:56adminsetgithub: 64302
2014-04-16 02:30:21akuchlingsetstatus: open -> closed

assignee: rhettinger -> akuchling

nosy: + akuchling
messages: + msg216420
resolution: fixed
stage: patch review -> resolved
2014-04-16 02:29:15python-devsetnosy: + python-dev
messages: + msg216419
2014-04-15 15:52:21chrish42setfiles: + accumulate2.diff

messages: + msg216321
2014-04-15 15:29:05akuchlingsetstage: needs patch -> patch review
2014-04-14 19:00:24chrish42setfiles: + accumulate_doc.patch

nosy: + chrish42
messages: + msg216172

keywords: + patch
2014-01-08 06:34:27rhettingersetpriority: normal -> low
assignee: docs@python -> rhettinger
2014-01-04 00:19:51ezio.melottisetkeywords: + easy
nosy: + ezio.melotti
type: enhancement
2014-01-04 00:17:24terry.reedysetstage: needs patch
2014-01-04 00:17:11terry.reedysetnosy: + terry.reedy
messages: + msg207260
2014-01-01 17:03:10benjamin.petersonsetnosy: + rhettinger
2014-01-01 16:12:00MLModelcreate