Pages

Sunday, April 4, 2010

DocStrings


Python has a nifty feature called documentation strings which is usually referred to by its shorter name
docstrings. DocStrings are an important tool that you should make use of since it helps to document the program better and makes it more easy to understand. Amazingly, we can even get back the docstring
from, say a function, when the program is actually running!
Using DocStrings
Example 7.8. Using DocStrings
#!/usr/bin/python
# Filename: func_doc.py
def printMax(x, y):
'''Prints the maximum of two numbers.
The two values must be integers.'''
x = int(x) # convert to integers, if possible
y = int(y)
if x > y:
print x, 'is maximum'
else:
print y, 'is maximum'
printMax(3, 5)
print printMax.__doc__
Output
$ python func_doc.py
5 is maximum
Prints the maximum of two numbers.
The two values must be integers.
How It Works
A string on the first logical line of a function is the docstring for that function. Note that DocStrings also
apply to modules and classes which we will learn about in the respective chapters.
The convention followed for a docstring is a multi-line string where the first line starts with a capital letter
and ends with a dot. Then the second line is blank followed by any detailed explanation starting from
the third line. You are strongly advised to follow this convention for all your docstrings for all your nontrivial
functions.
We can access the docstring of the printMax function using the __doc__ (notice the double underscores)
attribute (name belonging to) of the function. Just remember that Python treats everything as an
object and this includes functions. We'll learn more about objects in the chapter on classes.
If you have used the help() in Python, then you have already seen the usage of docstrings! What it

does is just fetch the __doc__ attribute of that function and displays it in a neat manner for you. You
can try it out on the function above - just include help(printMax) in your program. Remember to
press q to exit the help.
Automated tools can retrieve the documentation from your program in this manner. Therefore, I strongly
recommend that you use docstrings for any non-trivial function that you write. The pydoc command that
comes with your Python distribution works similarly to help() using docstrings.

The return statement


The return statement is used to return from a function i.e. break out of the function. We can optionally
return a value from the function as well.

Using the literal statement
Example 7.7. Using the literal statement
#!/usr/bin/python
# Filename: func_return.py
def maximum(x, y):
if x > y:
return x
else:
return y
print maximum(2, 3)
Output
$ python func_return.py
3
How It Works
The maximum function returns the maximum of the parameters, in this case the numbers supplied to the
function. It uses a simple if..else statement to find the greater value and then returns that value.
Note that a return statement without a value is equivalent to return None. None is a special type
in Python that represents nothingness. For example, it is used to indicate that a variable has no value if it
has a value of None.
Every function implicitly contains a return None statement at the end unless you have written your
own return statement. You can see this by running print someFunction() where the function
someFunction does not use the return statement such as:
def someFunction():
pass
The pass statement is used in Python to indicate an empty block of statements.

Keyword Arguments


If you have some functions with many parameters and you want to specify only some of them, then you
can give values for such parameters by naming them - this is called keyword arguments - we use the
name (keyword) instead of the position (which we have been using all along) to specify the arguments to
the function.
There are two advantages - one, using the function is easier since we do not need to worry about the order of the arguments. Two, we can give values to only those parameters which we want, provided that
the other parameters have default argument values.
Using Keyword Arguments
Example 7.6. Using Keyword Arguments
#!/usr/bin/python
# Filename: func_key.py
def func(a, b=5, c=10):
print 'a is', a, 'and b is', b, 'and c is', c
func(3, 7)
func(25, c=24)
func(c=50, a=100)
Output
$ python func_key.py
a is 3 and b is 7 and c is 10
a is 25 and b is 5 and c is 24
a is 100 and b is 5 and c is 50
How It Works
The function named func has one parameter without default argument values, followed by two parameters
with default argument values.
In the first usage, func(3, 7), the parameter a gets the value 3, the parameter b gets the value 5 and
c gets the default value of 10.
In the second usage func(25, c=24), the variable a gets the value of 25 due to the position of the
argument. Then, the parameter c gets the value of 24 due to naming i.e. keyword arguments. The variable
b gets the default value of 5.
In the third usage func(c=50, a=100), we use keyword arguments completely to specify the values.
Notice, that we are specifying value for parameter c before that for a even though a is defined before
c in the function definition.