itertools.groupby

[Raymond Hettinger]

On May 27, 2:59 pm, Steve Howell <showel... at yahoo.com> wrote:
> These docs need work.  Please do not defend them;
> please suggest improvements.

FWIW, I wrote those docs.  Suggested improvements are
welcome; however, I think they already meet a somewhat
high standard of quality:

- there is an accurate, succinct one-paragraph description
  of what the itertool does.

- there is advice to pre-sort the data using the same
  key function.

- it also advises when to list-out the group iterator
  and gives an example with working code.

- it includes a pure python equivalent which shows precisely
  how the function operates.

- there are two more examples on the next page.  those two
  examples also give sample inputs and outputs.

This is most complex itertool in the module.  I believe
the docs for it can be usable, complete, and precise,
but not idiot-proof.

The groupby itertool came-out in Py2.4 and has had remarkable
success (people seem to get what it does and like using it, and
there have been no bug reports or reports of usability problems).
All in all, that ain't bad (for what 7stud calls a poster child).


Raymond