classification
Title: Itertools doc summary table misdocuments some arguments
Type: Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: wont fix
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: docs@python, eric.araujo, ezio.melotti, petri.lehtinen, rhettinger
Priority: low Keywords:

Created on 2012-07-27 18:23 by eric.araujo, last changed 2017-09-16 05:01 by rhettinger. This issue is now closed.

Messages (8)
msg166594 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-07-27 18:23
In the tables near the top of http://docs.python.org/library/itertools , some functions like cycle have an example that uses “seq”, which is interpreted as “sequence” but the functions do work with any iterable.
msg172767 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2012-10-12 18:12
cycle() doesn't use seq, but p (p0, p1, ...). Others use seq (seq[0], seq[1], ...). How do you think these should be changed?
msg176401 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-11-26 05:14
cycle was a bad example, but there are other: ifilter, islice, takewhile.  "it" (like what tee uses) instead of "seq" would work.
msg176442 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-11-26 19:11
I would like to stick with "seq" because another other variant is less readable or understandable IMO.
msg176443 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-11-26 19:14
Also note that the "seq[0], seq[1], ..." notation only makes sense for objects that are indexable.   It is very slightly misleading but does a good job of communicating what the itertools do.
msg176454 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-26 20:41
The line before the second table says "sequence". That could be changed to "iterable".  Specifying "it" in parentheses just after "iterable" and use it consistently in the examples could make it clearer.
I agree that using [0] and [1] is OK even if not 100% correct though.
msg302309 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2017-09-16 02:07
Per Raymond’s feedback, I will close this.  The table is useful as a quick reference, seq is a shortcut, “it” or “iter” are worse names, the first doc line says this is all about iterators, and the individual function docs do use “iterable”.
msg302319 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-09-16 05:01
Thank you.
History
Date User Action Args
2017-09-16 05:01:36rhettingersetstatus: pending -> closed
resolution: wont fix
messages: + msg302319

stage: resolved
2017-09-16 02:07:44eric.araujosetstatus: open -> pending

messages: + msg302309
2012-11-26 20:41:33ezio.melottisetnosy: + ezio.melotti
messages: + msg176454
2012-11-26 19:14:59rhettingersetpriority: normal -> low

messages: + msg176443
2012-11-26 19:11:53rhettingersetassignee: docs@python -> rhettinger
messages: + msg176442
2012-11-26 05:14:31eric.araujosetmessages: + msg176401
2012-10-12 18:12:30petri.lehtinensetnosy: + petri.lehtinen
messages: + msg172767
2012-07-27 18:23:54eric.araujocreate