PyWart: Itertools module needs attention

[rantingrick]

############################################################
#                          Quote                           #
############################################################
# The itertools module is great HOWEVER i believe most     #
# people are recreating the functionalities due to the     #
# insanely cryptic and/or missing examples from each       #
# method                                                   #
############################################################

py> print itertools.chain.__doc__
chain(*iterables) --> chain object
Return a chain object whose .next() method returns elements from the
first iterable until it is exhausted, then elements from the next
iterable, until all of the iterables are exhausted.

############################################################
#                          Quote                           #
############################################################
# Okay not TOO bad however this simple example would       #
# suffice:                                                 #
############################################################

py> list(itertools.chain([1,2], [3,[4,5],6]))
[1, 2, 3, [4, 5], 6]

############################################################
#                          Quote                           #
############################################################
# Same for these...                                        #
############################################################

py> ''.join(list(itertools.dropwhile(lambda x:x==" ", "    hello
word    ")))
'hello word    '
py> ''.join(list(itertools.takewhile(lambda x:x==" ", "    hello
word    ")))
'    '
py> print itertools.compress.__doc__
compress(data, selectors) --> iterator over selected data
Return data elements corresponding to true selector elements.
Forms a shorter iterator from selected data elements using the
selectors to choose the data elements.

############################################################
#                          Quote                           #
############################################################
# WTF! Would you like to define a Python "selector". Could #
# it be that we should be using "selector function" or     #
# "predicate function" instead?                            #
############################################################