PyWart: Itertools module needs attention

R

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? #
############################################################
 
E

Ethan Furman

Nick said:
I'm honestly missing the point of this mail.


rantingrick is a well-known troll, and doesn't need to have a point.

Please do not feed the troll.

~Ethan~
 
I

Ian Kelly

############################################################
#                          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                                                   #
############################################################

Have you looked at the online itertools documentation at all?

http://docs.python.org/library/itertools.html
py> ''.join(list(itertools.dropwhile(lambda x:x==" ", "    hello
word    ")))
'hello word    '
py> ''.join(list(itertools.takewhile(lambda x:x==" ", "    hello
word    ")))
'    '

These are too complex to be good examples. Drop the lambda and
replace it with a built-in. Also, str.join is perfectly capable of
taking an iterator as its argument. There is no reason at all to
construct a list first.
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?                            #
############################################################

Notice that it says "selector elements", not "selector functions".
You have misconstrued what this function does. Hint: it does not use
predicates at all.

I can agree though that this could probably use a simple example in
the doc string.
 
R

rantingrick

Have you looked at the online itertools documentation at all?

http://docs.python.org/library/itertools.html

Yes the online docs are much better. I really like the source code
showing the inner workings of the methods. However i always get upset
when i see poorly thought out doc-strings. My philosophy is that we
should use the built in help function first and only visit the
documentation if more instruction is needed.


I may need to create another PyWart on the topic of doc-strings and
how the author of these strings needs to forget everything he knows
and imagine he is a complete python neophyte. I remember my initial
frustrations learning about functions (in another life it seems) and
my inability to grasp the concept was due to poor examples. I believe
the author use the Fibonacci sequence as an example (Python docs use
this example also). What an idiot!

What does conditionals, linear assignment, loops, the print function,
in-place addition, logic, blah, blah, have to do with understanding a
function... NOTHING! The most basic and by far the best first example
for functions (in any language) is this...

def add(x, y):
return x + y

Followed by this...

def sub(x,y):
return x - y

Simple and to the point. It simply reeks of "ah ha"! I dare anyone to
create a better introductory function example. Dear Tutorial Writer:
When writing tutorials please check your ego at the door. Thank you.
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

Forum statistics

Threads
473,744
Messages
2,569,483
Members
44,901
Latest member
Noble71S45

Latest Threads

Top