[issue15472] Itertools doc summary table misdocuments some arguments
New submission from Éric Araujo <merwok@netwok.org>: 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. ---------- assignee: docs@python components: Documentation messages: 166594 nosy: docs@python, eric.araujo, rhettinger priority: normal severity: normal status: open title: Itertools doc summary table misdocuments some arguments versions: Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15472> _______________________________________
Petri Lehtinen added the comment: cycle() doesn't use seq, but p (p0, p1, ...). Others use seq (seq[0], seq[1], ...). How do you think these should be changed? ---------- nosy: +petri.lehtinen _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15472> _______________________________________
Éric Araujo added the comment: cycle was a bad example, but there are other: ifilter, islice, takewhile. "it" (like what tee uses) instead of "seq" would work. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15472> _______________________________________
Raymond Hettinger added the comment: I would like to stick with "seq" because another other variant is less readable or understandable IMO. ---------- assignee: docs@python -> rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15472> _______________________________________
Raymond Hettinger added the comment: 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. ---------- priority: normal -> low _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15472> _______________________________________
Ezio Melotti added the comment: 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. ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15472> _______________________________________
Éric Araujo added the comment: 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”. ---------- status: open -> pending _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue15472> _______________________________________
Raymond Hettinger added the comment: Thank you. ---------- resolution: -> wont fix stage: -> resolved status: pending -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue15472> _______________________________________
participants (4)
-
Ezio Melotti -
Petri Lehtinen
-
Raymond Hettinger
-
Éric Araujo