--- Raymond Hettinger <[EMAIL PROTECTED]> 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 -- http://mail.python.org/mailman/listinfo/python-list