--- Carsten Haese <[EMAIL PROTECTED]> wrote:
> On Sun, 2007-05-27 at 18:12 -0700, Steve Howell
> wrote:
> > [...] there is no way
> > that "uniquekeys" is a sensible variable [...]
>
> That's because the OP didn't heed the advice from
> the docs that
> "Generally, the iterable needs to already be sorted
> on the same key
> function."
>
It was I who was complaining about the variable name
uniquekeys, because the example itself didn't
incorporate a call to sorted(). I would have proposed
two solutions to prevent people from falling into the
trap/pitfall:
1) Add a call to sorted() in the example.
2) Rename the variable to
not_necessarily_unique_keys or something like that.
Raymond did the former, so I'm happy.
Although I do think, of course, that people need to
read docs carefully, I think it was a big trap/pitfall
that people might assume the semantics of the SQL
"group by" syntax, so I'm glad that Raymond now calls
out the pitfall, and compares it to the Unix "uniq"
command, which has more similar semantics.
> Suppose hypothetically you wanted to show off a
> really neat example that
> involves chain, izip, and groupby.
It's hypothetical for itertools, but I can understand
your premise for other modules, where you do more
typically need multiple functions from the module to
provide meaningful examples.
> If the examples
> were forced into the
> page of function synopses, you'd have to duplicate
> it in all three
> functions, or randomly pick one function for which
> your example is an
> example.
There's no reason why all three functions couldn't
link to the same example on the Examples page, though.
> Having a separate examples page that is not
> arbitrarily
> sectioned by function name makes more sense.
>
I'd propose a separate examples page that is not
arbitrarily sectioned by function name, or not by
function name, but which is organized according to the
best way to help users use the module. In the case of
itertools, I'd see the benefit of a separate section
with many examples of groupby(), since it's a very
rich function in its capabilities, and it doesn't
really require anything else from itertools to write
useful programs.
____________________________________________________________________________________Boardwalk
for $500? In 2007? Ha! Play Monopoly Here and Now (it's updated for today's
economy) at Yahoo! Games.
http://get.games.yahoo.com/proddesc?gamekey=monopolyherenow
--
http://mail.python.org/mailman/listinfo/python-list
