itertools.groupby

[Steve Howell]

--- Raymond Hettinger <python at rcn.com> wrote:

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

I respectfully disagree, and I have suggested
improvements in this thread.

Without even reading the doc, I completely understand
the motivation for this function, and I understand its
implementation from reading email threads where it was
discussed, but when I go back a couple days later to
read the docs, I find it hard to grok how to actually
use the module.

You provided a bunch of points that clarify what you
did specify correctly in the documentation, and I'm
not going to attempt to refute them individually.  I'm
simply going to agree with the original poster that
the docs as written are hard to understand, and I'll
leave it to you to make your own judgment upon
re-reading the docs.

It could come down to simply needing a better
motivating example.

My suggestions mostly come down to providing better
example code (I provided some in a separate reply),
but I think you could also clarify the main use case
(aggregating a stream of data) and the main limitation
(requirement to sort by key since the iteration could
be infinite)--which I know you mention, but you maybe
could emphasize it more.

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

Agreed, of course, that nothing can be idiot-proof,
and I understand the limitations myself, and I
understand groupby's power.

> 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).
> 

I agree that "poster child" is way too strong, but
please don't disregard 7stud completely just because
he exaggerates a tad.

I've had minor usability problems with groupby, and I
just  haven't reported them.  I'm still on 2.3 for
most of my day-to-work work, but I've been
sufficiently intrigued by the power of groupby() to
try it out in a later version.

I really mean all of these suggestions constructively.
 It's a great function to have in Python, and I think
the documentation's mostly good, just could be even
better.






 
____________________________________________________________________________________
Don't get soaked.  Take a quick peak at the forecast
with the Yahoo! Search weather shortcut.
http://tools.search.yahoo.com/shortcuts/#loc_weather