Unlike the other scripting languages I work with(like PHP, Ruby, JavaScript, etc.), I am not comfortable using Python. I have made some stuff in Python(for example, frees) – but I could get into the flow as easily as with other languages. For the longest time, I thought it was because of the whitespace issue. But recently, I created a small Python script – that’s when I understood that whitespace does not concern me. What make me angry at python is its documentation/manual.

By Python Manual, I mean the official Python Manual available at http://docs.python.org/. I have downloaded the entire manual to my system as HTML files and use that as a reference when working with Python. This is what I have done for all the other languages I work with…

• Perl
• PHP
• Ruby
• JavaScript
• CSS
• etc.

Finding a Function

There is one big problem with using HTML files as your reference – you cannot search through it. So I try to find a page in the documentation that lists all the functions in a single page. When I need to find a function, all I have to do is search through this page. These pages in the documentation serves this purpose…

• PHP
• Perl
• JavaScript
• Ruby

What about Python? Well, Python don’t have such a page in their manual. The nearest one I could find a combination of four pages – Module Index + Library Index + Tutorial Index + Language Index. Its no where near as useful.

Even if you are online(remember, many people are not connected all the time), its still not easy to find a function in Python documentation – even with searching capabilities. Don’t believe me? OK – go to Python Docs and try to find the documentation for the function that, say, reverses an array. Now go to the PHP site and do the same.

Reference Formats

Anyway, I cannot really complain about the the availability of the ‘function page’. Its just the way I prefer – other people may not want such a page. But I can complain about the fact that they don’t provide a CHM file in their downloads section. CHM solves the problem as you can search through them easily.

PHP, on other hand, provides the CHM file. This makes the PHP manual much more easier to use.

Even though Python don’t officially provide a CHM file, others have made it available on the net. Its just a google search away. But I prefer to get these stuff from an official source.

Level of Detail in the Documentation

The worst sin of the Python manual is that the documentation is not detailed enough. To better understand this, let’s take an example – say the array reversal function. First we take a look at the Python documentation for this function…

reverse()

Reverse the order of the items in the array.

One line. That’s it! If you are not well versed in Python, you will have no idea of how to use this function – because there is no example. Most people will expect that the array must be given as the argument. But the argument list is empty in the documentation. That’s because the array is not passed as an argument – rather, in Python, this function is a member function of the array object – so the proper usage will be something like this…

x = [1,2,4]
x.reverse()
#Now x has the value [4,2,1]

I know that because I know Python – but if a new user manages to find the documentation for this function, he will be confused. Another thing – I am not saying that there are no examples in the documentation – examples are given for a lot of functions. But its no where near the level that PHP has achieved.

OK – now lets see the PHP manual for the same function – array_reverse(). There is an entire page for that function. Not just for this function – there is one page of documentation for every function in PHP. And there are examples. And at the end, there is a collection of ‘user notes’ – making each function much clearer. Beautiful!

I feel a bit guilty about comparing Python with PHP documentation – PHP has the best documentation in its class of languages. But still, Python has a lot to learn from PHP(I wanted to say that for a long time ).

As promised in the last post(Hello Script for PHP), this is my Hello Script for Python. ‘Hello Script‘ is a file that contains the most commonly used elements of a programming language so that it can be used as a cheat sheet when working with that language.

A word of caution here – the blocks in Python is created using whitespace – so the indentation is important. So when you see an indentation in the below code, think of it as one tab(instead of four spaces or something).

I want to insert a disclaimer here – I am not that good with python. We never really clicked. I have done very limited work in Python. So if you notice any problems with the below script, let me know and I’ll correct it.

#!/usr/bin/python

print "Hello World\n"

name = "Binny"
year = 2008
print "Hello, " + name + " - welcome to " + str(year) + "\n"

# If,else conditions
if (year > 2008):
	print "Welcome to the future - yes, we have flying cars!\n"
elif(year < 2008):
	print "The past - please don't change anything. Don't step on any butterflies. And for the sake of all thats good and holy, stay away from your parents!\n"
else:
	print "Anything wrong with your time machine? You have not gone anywhere, kiddo.\n"

# For loop
for i in range(0,3):
	print str(i) + ") Hi there!"

print ""

#Numerical Array, While
rules = ['Do no harm','Obey','Continue Living']
i = 0
while(i<len(rules)):
	print "Rule " + str(i+1) + " : " + rules[i]
	i = i + 1
print ""

# Associated array, foreach
associated = {
	'hello'	:	'world',
	'foo'	:	'bar',
	'lorem'	:	'ipsum'
}
for key in associated:
	print key + " : " + associated[key]
print ""

import string
csv_values = string.split("hello,world,how,are,you\n", ",")
print string.join(csv_values, ":")

# Function, argument, return, call
def hello(name):
	return "Hello " + name + "\n"

hello_string = hello("Binny")
print hello_string

# One for the OOP fanboys - Class, members, object and stuff.
class Movie:
	name = ''
	rating = 0

	def __init__(self, name):
		self.name = name
		self.rateMovie()

	def rateMovie(self):
		self.rating = (len(self.name) % 10) + 1 #IMDBs rating algorithm. True story!

	def printMovieDetails(self):
		print "Movie : ",  self.name
		print "Rating : ", '*' * self.rating , "(", self.rating ,")\n"

#Create the object
ncfom = Movie("New Country for Old Men") #It's a sequel!
ncfom.printMovieDetails()

# File IO
# File reading, easy method...
file_in  = open('Hello.py', 'r')
contents = file_in.read()
print "Current file has " + str(len(contents)) + " chars\n"
file_in.close()
# Writing to a file
file_out = open('/tmp/hello.txt', 'w')
file_out.write("Hello World")
file_out.close()

# Command Executing
import commands
import os
print "Result of 'ls' command is " + commands.getoutput('ls') #Execute the command 'ls' and print its output
print

# Regular Expressions
import re
hell_check = re.compile("^Hell")
string = "Hello World"
if hell_check.match(string): print "Yup - its evil (Compiled)"
if re.match('^Hell', string): print "Yup - its evil (Not Compiled)"
print re.sub(r'l([^l])', r'\1', string)

As I said last time, save this to a file and keep it around for future reference.

Next hello script – Perl, Ruby or Tcl/Tk? Which one do you want – leave it in the comments.

But when I actually ran the programs in Linux, I got the shock of a lifetime. The applications I created looked bad – really bad…

I still use many Tk programs – but because of the looks issue, I decided to stop using Tk for my new programs. So I decided to try GTK. I even created a small application using PyGTK(my first) to view the harddisk space usage in Linux – Frees.

It was a very simple application – all I had to do is run the ‘df’ command, parse its output, and display a small table using that data. I was expecting around 100, 150 lines of code at the most. But after I created the app, I have 500+ lines of code.

At first, I thought that it was a mistake on my part – I thought that I was not using the best method. But then I came across an article in Reddit – gnocl or PyGtk?.

PyGtk is still the most recommended binding for Gtk. A lot of programs in Linux is written using PyGtk. So naturally there are a few advantages for using it…

• It will be the more ‘road-tested’ binding.
• Many system will have it installed by default.
• Bigger community – so…
  • more support
  • more examples
  • more tutorials
  • etc.

One the other hand, I have to write more code.

Conclusion

If it is a private script – only useful for myself, then I will use Tcl/Tk or Gnometcl. If the script could be distributed, like Frees, then I will use Python GTK.

What about the other options…

• wxWidgets
• PyQT
• Ruby/GTK
• Perl/GTK

Any recommendations for me on which library to use? Please leave it in the comments.