--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/SEESenv/web/html/backup/func.html Fri Feb 12 01:11:21 2010 +0530
@@ -0,0 +1,726 @@
+<html>
+<head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Chapter 9. Finding and fixing mistakes</title>
+<link rel="stylesheet" href="/support/styles.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.3"><link rel="home" href="index.html" title="Mercurial: The Definitive Guide">
+<link rel="up" href="index.html" title="Mercurial: The Definitive Guide">
+<link rel="prev" href="managing-releases-and-branchy-development.html" title="Chapter 8. Managing releases and branchy development">
+<link rel="next" href="handling-repository-events-with-hooks.html" title="Chapter 10. Handling repository events with hooks"><link rel="alternate" type="application/atom+xml" title="Comments" href="/feeds/comments/">
+<link rel="shortcut icon" type="image/png" href="/support/figs/favicon.png">
+<script type="text/javascript" src="/support/jquery-min.js"></script>
+<script type="text/javascript" src="/support/form.js"></script>
+<script type="text/javascript" src="/support/hsbook.js"></script></head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<!--<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">Chapter 14. Adding functionality with extensions</th></tr>
+<tr>
+<td width="20%" align="left">
+<a accesskey="p" href="advanced-uses-of-mercurial-queues.html">Prev</a> </td>
+<th width="60%" align="center"> </th>
+<td width="20%" align="right"> <a accesskey="n" href="migrating-to-mercurial.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div> -->
+<div class="chapter" title="Chapter 14. Adding functionality with extensions">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="chap:hgext"></a>Chapter 14. Adding functionality with extensions</h2></div></div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt><span class="sect1"><a href="adding-functionality-with-extensions.html#sec:hgext:inotify">14.1. Improve performance with the <code class="literal">inotify</code> extension</a></span></dt>
+<dt><span class="sect1"><a href="adding-functionality-with-extensions.html#sec:hgext:extdiff">14.2. Flexible diff support with the <code class="literal">extdiff</code> extension</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="adding-functionality-with-extensions.html#id3071699">14.2.1. Defining command aliases</a></span></dt></dl></dd>
+<dt><span class="sect1"><a href="adding-functionality-with-extensions.html#sec:hgext:transplant">14.3. Cherrypicking changes with the <code class="literal">transplant</code> extension</a></span></dt>
+<dt><span class="sect1"><a href="adding-functionality-with-extensions.html#sec:hgext:patchbomb">14.4. Send changes via email with the <code class="literal">patchbomb</code> extension</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="adding-functionality-with-extensions.html#id3072184">14.4.1. Changing the behavior of patchbombs</a></span></dt></dl></dd>
+</dl>
+</div>
+<p><b>Table of Contents</b></p>
+<dl>
+<dt><span class="section"><a href="#default-arguments">1. Default Arguments</a></span></dt>
+<dt><span class="section"><a href="#keyword-arguments">2. Keyword Arguments</a></span></dt>
+<dt><span class="section"><a href="#parameter-packing-and-unpacking">3. Parameter Packing and Unpacking</a></span></dt>
+<dt><span class="section"><a href="#nested-functions-and-scopes">4. Nested Functions and Scopes</a></span></dt>
+<dt><span class="section"><a href="#map-reduce-and-filter-functions">5. map, reduce and filter functions</a></span></dt>
+<dd><dl><dt><span class="section"><a href="#list-comprehensions">5.1. List Comprehensions</a></span></dt></dl></dd>
+</dl>
+
+<p id="x_74b">
+ <span class="emphasis"><em>Functions</em></span> allow us to enclose a set of statements and call the function again and again instead of repeating the group of statements everytime. Functions also allow us to isolate a piece of code from all the other code and provides the convenience of not polluting the global variables.
+ </p>
+<p id="x_74c"<a name="x_74c"></a>
+ <span class="emphasis"><em>Function</em></span> in python is defined with the keyword
+ <span class="strong"><strong>def</strong></span> followed by the name of the function, in turn followed by a pair of parenthesis which encloses the list of parameters to the function. The definition line ends with a ':'. The definition line is followed by the body of the function intended by one block. The
+ <span class="emphasis"><em>Function</em></span> must return a value:
+ </p>
+<pre class="programlisting">def factorial(n):
+ fact = 1
+ for i in range(2, n):
+ fact *= i
+
+ return fact
+
+</pre>
+<p><a name="x_74d"></a>The code snippet above defines a function with the name factorial, takes the number for which the factorial must be computed, computes the factorial and returns the value.</p>
+<p><a name="x_74e"></a>A
+ <span class="emphasis"><em>Function</em></span> once defined can be used or called anywhere else in the program. We call a fucntion with its name followed by a pair of parenthesis which encloses the arguments to the function.
+ </p>
+<p><a name="x_74f"></a>The value that function returns can be assigned to a variable. Let's call the above function and store the factorial in a variable:</p>
+<pre class="programlisting">fact5 = factorial(5)
+
+</pre>
+<p><a name="x_750"></a>The value of fact5 will now be 120, which is the factorial of 5. Note that we passed 5 as the argument to the function.</p>
+<p><a name="x_751"></a>It may be necessary to document what the function does, for each of the function to help the person who reads our code to understand it better. In order to do this Python allows the first line of the function body to be a string. This string is called as
+ <span class="emphasis"><em>Documentation String</em></span> or
+ <span class="emphasis"><em>docstring</em></span>.
+ <span class="emphasis"><em>docstrings</em></span> prove to be very handy since there are number of tools which can pull out all the docstrings from Python functions and generate the documentation automatically from it.
+ <span class="emphasis"><em>docstrings</em></span> for functions can be written as follows:
+ </p>
+<pre class="programlisting">def factorial(n):
+ 'Returns the factorial for the number n.'
+ fact = 1
+ for i in range(2, n):
+ fact *= i
+
+ return fact
+
+</pre>
+<p><a name="x_752"></a>An important point to note at this point is that, a function can return any Python value or a Python object, which also includes a
+ <span class="emphasis"><em>Tuple</em></span>. A
+ <span class="emphasis"><em>Tuple</em></span> is just a collection of values and those values themselves can be of any other valid Python datatypes, including
+ <span class="emphasis"><em>Lists</em></span>,
+ <span class="emphasis"><em>Tuples</em></span>,
+ <span class="emphasis"><em>Dictionaries</em></span> among other things. So effectively, if a function can return a tuple, it can return any number of values through a tuple
+ </p>
+<p><a name="x_753"></a>Let us write a small function to swap two values:</p>
+<pre class="programlisting">def swap(a, b):
+ return b, a
+
+c, d = swap(a, b)
+
+</pre>
+<p><a name="x_754"></a>Function scope --------------- The variables used inside the function are confined to the function's scope and doesn't pollute the variables of the same name outside the scope of the function. Also the arguments passed to the function are passed by-value if it is of basic Python data type:</p>
+<pre class="programlisting">def cant_change(n):
+ n = 10
+
+n = 5
+cant_change(n)
+
+</pre>
+<p><a name="x_755"></a>Upon running this code, what do you think would have happened to value of n which was assigned 5 before the function call? If you have already tried out that snippet on the interpreter you already know that the value of n is not changed. This is true of any immutable types of Python like
+ <span class="emphasis"><em>Numbers</em></span>,
+ <span class="emphasis"><em>Strings</em></span> and
+ <span class="emphasis"><em>Tuples</em></span>. But when you pass mutable objects like
+ <span class="emphasis"><em>Lists</em></span> and
+ <span class="emphasis"><em>Dictionaries</em></span> the values are manipulated even outside the function:
+ </p>
+<pre class="programlisting">>>> def can_change(n):
+... n[1] = James
+...
+
+>>> name = ['Mr.', 'Steve', 'Gosling']
+>>> can_change(name)
+>>> name
+['Mr.', 'James', 'Gosling']
+
+</pre>
+<p><a name="x_756"></a>If nothing is returned by the function explicitly, Python takes care to return None when the funnction is called.</p>
+<div class="section" title="1. Default Arguments">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="default-arguments"></a>1. Default Arguments</h2></div></div></div>
+<p><a name="x_757"></a>There may be situations where we need to allow the functions to take the arguments optionally. Python allows us to define function this way by providing a facility called
+ <span class="emphasis"><em>Default Arguments</em></span>. For example, we need to write a function that returns a list of fibonacci numbers. Since our function cannot generate an infinite list of fibonacci numbers, we need to specify the number of elements that the fibonacci sequence must contain. Suppose, additionally, we want to the function to return 10 numbers in the sequence if no option is specified we can define the function as follows:
+ </p>
+<pre class="programlisting">def fib(n=10):
+ fib_list = [0, 1]
+ for i in range(n - 2):
+ next = fib_list[-2] + fib_list[-1]
+ fib_list.append(next)
+ return fib_list
+
+</pre>
+<p><a name="x_758"></a>When we call this function, we can optionally specify the value for the parameter n, during the call as an argument. Calling with no argument and argument with n=5 returns the following fibonacci sequences:</p>
+<pre class="programlisting">fib()
+[0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
+fib(5)
+[0, 1, 1, 2, 3]
+
+</pre>
+</div>
+<div class="section" title="2. Keyword Arguments">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="keyword-arguments"></a>2. Keyword Arguments</h2></div></div></div>
+<p><a name="x_759"></a>When a function takes a large number of arguments, it may be difficult to remember the order of the parameters in the function definition or it may be necessary to pass values to only certain parameters since others take the default value. In either of these cases, Python provides the facility of passing arguments by specifying the name of the parameter as defined in the function definition. This is known as
+ <span class="emphasis"><em>Keyword Arguments</em></span>.
+ </p>
+<p><a name="x_75a"></a>In a function call,
+ <span class="emphasis"><em>Keyword arguments</em></span> can be used for each argument, in the following fashion:
+ </p>
+<pre class="programlisting">argument_name=argument_value
+Also denoted as: keyword=argument
+
+def wish(name='World', greetings='Hello'):
+ print "%s, %s!" % (greetings, name)
+
+</pre>
+<p><a name="x_75b"></a>This function can be called in one of the following ways. It is important to note that no restriction is imposed in the order in which
+ <span class="emphasis"><em>Keyword arguments</em></span> can be specified. Also note, that we have combined
+ <span class="emphasis"><em>Keyword arguments</em></span> with
+ <span class="emphasis"><em>Default arguments</em></span> in this example, however it is not necessary:
+ </p>
+<pre class="programlisting">wish(name='Guido', greetings='Hey')
+wish(greetings='Hey', name='Guido')
+
+</pre>
+<p><a name="x_75c"></a>Calling functions by specifying arguments in the order of parameters specified in the function definition is called as
+ <span class="emphasis"><em>Positional arguments</em></span>, as opposed to
+ <span class="emphasis"><em>Keyword arguments</em></span>. It is possible to use both
+ <span class="emphasis"><em>Positional arguments</em></span> and
+ <span class="emphasis"><em>Keyword arguments</em></span> in a single function call. But Python doesn't allow us to bungle up both of them. The arguments to the function, in the call, must always start with
+ <span class="emphasis"><em>Positional arguments</em></span> which is in turn followed by
+ <span class="emphasis"><em>Keyword arguments</em></span>:
+ </p>
+<pre class="programlisting">def my_func(x, y, z, u, v, w):
+ # initialize variables.
+ ...
+ # do some stuff
+ ...
+ # return the value
+
+</pre>
+<p><a name="x_75d"></a>It is valid to call the above functions in the following ways:</p>
+<pre class="programlisting">my_func(10, 20, 30, u=1.0, v=2.0, w=3.0)
+my_func(10, 20, 30, 1.0, 2.0, w=3.0)
+my_func(10, 20, z=30, u=1.0, v=2.0, w=3.0)
+my_func(x=10, y=20, z=30, u=1.0, v=2.0, w=3.0)
+
+</pre>
+<p><a name="x_75e"></a>Following lists some of the invalid calls:</p>
+<pre class="programlisting">my_func(10, 20, z=30, 1.0, 2.0, 3.0)
+my_func(x=10, 20, z=30, 1.0, 2.0, 3.0)
+my_func(x=10, y=20, z=30, u=1.0, v=2.0, 3.0)
+
+</pre>
+</div>
+<div class="section" title="3. Parameter Packing and Unpacking">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="parameter-packing-and-unpacking"></a>3. Parameter Packing and Unpacking</h2></div></div></div>
+<p><a name="x_75f"></a>The positional arguments passed to a function can be collected in a tuple parameter and keyword arguments can be collected in a dictionary. Since keyword arguments must always be the last set of arguments passed to a function, the keyword dictionary parameter must be the last parameter. The function definition must include a list explicit parameters, followed by tuple paramter collecting parameter, whose name is preceded by a *****, for collecting positional parameters, in turn followed by the dictionary collecting parameter, whose name is preceded by a ****** :</p>
+<pre class="programlisting">def print_report(title, *args, **name):
+ """Structure of *args*
+ (age, email-id)
+ Structure of *name*
+ {
+ 'first': First Name
+ 'middle': Middle Name
+ 'last': Last Name
+ }
+ """
+
+ print "Title: %s" % (title)
+ print "Full name: %(first)s %(middle)s %(last)s" % name
+ print "Age: %d\nEmail-ID: %s" % args
+
+</pre>
+<p><a name="x_760"></a>The above function can be called as. Note, the order of keyword parameters can be interchanged:</p>
+<pre class="programlisting">>>> print_report('Employee Report', 29, 'johny@example.com', first='Johny',
+ last='Charles', middle='Douglas')
+Title: Employee Report
+Full name: Johny Douglas Charles
+Age: 29
+Email-ID: johny@example.com
+
+</pre>
+<p><a name="x_761"></a>The reverse of this can also be achieved by using a very identical syntax while calling the function. A tuple or a dictionary can be passed as arguments in place of a list of *Positional arguments* or *Keyword arguments* respectively using ***** or ****** :</p>
+<pre class="programlisting">def print_report(title, age, email, first, middle, last):
+ print "Title: %s" % (title)
+ print "Full name: %s %s %s" % (first, middle, last)
+ print "Age: %d\nEmail-ID: %s" % (age, email)
+
+>>> args = (29, 'johny@example.com')
+>>> name = {
+ 'first': 'Johny',
+ 'middle': 'Charles',
+ 'last': 'Douglas'
+ }
+>>> print_report('Employee Report', *args, **name)
+Title: Employee Report
+Full name: Johny Charles Douglas
+Age: 29
+Email-ID: johny@example.com
+
+</pre>
+</div>
+<div class="section" title="4. Nested Functions and Scopes">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="nested-functions-and-scopes"></a>4. Nested Functions and Scopes</h2></div></div></div>
+<p><a name="x_762"></a>Python allows nesting one function inside another. This style of programming turns out to be extremely flexible and powerful features when we use
+ <span class="emphasis"><em>Python decorators</em></span>. We will not talk about decorators is beyond the scope of this course. If you are interested in knowing more about
+ <span class="emphasis"><em>decorator programming</em></span> in Python you are suggested to read:
+ </p>
+<div class="literallayout"><p><br>
+ <a class="ulink" href="http://avinashv.net/2008/04/python-decorators-syntactic-sugar" target="_top">http://avinashv.net/2008/04/python-decorators-syntactic-sugar</a>/<br>
+ <a class="ulink" href="http://personalpages.tds.net" target="_top">http://personalpages.tds.net</a>/~kent37/kk/00001.html<br>
+ </p></div>
+<p><a name="x_763"></a>However, the following is an example for nested functions in Python:</p>
+<pre class="programlisting">def outer():
+ print "Outer..."
+ def inner():
+ print "Inner..."
+ print "Outer..."
+ inner()
+
+>>> outer()
+
+</pre>
+</div>
+<div class="section" title="5. map, reduce and filter functions">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="map-reduce-and-filter-functions"></a>5. map, reduce and filter functions</h2></div></div></div>
+<p><a name="x_764"></a>Python provides several built-in functions for convenience. The
+ <span class="strong"><strong>map()</strong></span>,
+ <span class="strong"><strong>reduce()</strong></span> and
+ <span class="strong"><strong>filter()</strong></span> functions prove to be very useful with sequences like
+ <span class="emphasis"><em>Lists</em></span>.
+ </p>
+<p><a name="x_765"></a>The
+ <span class="strong"><strong>map</strong></span> (
+ <span class="emphasis"><em>function</em></span>,
+ <span class="emphasis"><em>sequence</em></span>) function takes two arguments:
+ <span class="emphasis"><em>function</em></span> and a
+ <span class="emphasis"><em>sequence</em></span> argument. The
+ <span class="emphasis"><em>function</em></span> argument must be the name of the function which in turn takes a single argument, the individual element of the
+ <span class="emphasis"><em>sequence</em></span>. The
+ <span class="strong"><strong>map</strong></span> function calls
+ <span class="emphasis"><em>function(item)</em></span>, for each item in the sequence and returns a list of values, where each value is the value returned by each call to
+ <span class="emphasis"><em>function(item)</em></span>.
+ <span class="strong"><strong>map()</strong></span> function allows to pass more than one sequence. In this case, the first argument,
+ <span class="emphasis"><em>function</em></span> must take as many arguments as the number of sequences passed. This function is called with each corresponding element in the each of the sequences, or
+ <span class="strong"><strong>None</strong></span> if one of the sequence is exhausted:
+ </p>
+<pre class="programlisting">def square(x):
+ return x*x
+
+>>> map(square, [1, 2, 3, 4])
+[1, 4, 9, 16]
+
+def mul(x, y):
+ return x*y
+
+>>> map(mul, [1, 2, 3, 4], [6, 7, 8, 9])
+
+</pre>
+<p><a name="x_766"></a>The
+ <span class="strong"><strong>filter</strong></span> (
+ <span class="emphasis"><em>function</em></span>,
+ <span class="emphasis"><em>sequence</em></span>) function takes two arguments, similar to the
+ <span class="strong"><strong>map()</strong></span> function. The
+ <span class="strong"><strong>filter</strong></span> function calls
+ <span class="emphasis"><em>function(item)</em></span>, for each item in the sequence and returns all the elements in the sequence for which
+ <span class="emphasis"><em>function(item)</em></span> returned True:
+ </p>
+<pre class="programlisting">def even(x):
+ if x % 2:
+ return True
+ else:
+ return False
+
+>>> filter(even, range(1, 10))
+[1, 3, 5, 7, 9]
+
+</pre>
+<p><a name="x_767"></a>The
+ <span class="strong"><strong>reduce</strong></span> (
+ <span class="emphasis"><em>function</em></span>,
+ <span class="emphasis"><em>sequence</em></span>) function takes two arguments, similar to
+ <span class="strong"><strong>map</strong></span> function, however multiple sequences are not allowed. The
+ <span class="strong"><strong>reduce</strong></span> function calls
+ <span class="emphasis"><em>function</em></span> with first two consecutive elements in the sequence, obtains the result, calls
+ <span class="emphasis"><em>function</em></span> with the result and the subsequent element in the sequence and so on until the end of the list and returns the final result:
+ </p>
+<pre class="programlisting">def mul(x, y):
+ return x*y
+
+>>> reduce(mul, [1, 2, 3, 4])
+24
+
+</pre>
+<div class="section" title="5.1. List Comprehensions">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="list-comprehensions"></a>5.1. List Comprehensions</h3></div></div></div>
+<p><a name="x_768"></a>List Comprehension is a convenvience utility provided by Python. It is a syntatic sugar to create
+ <span class="emphasis"><em>Lists</em></span>. Using
+ <span class="emphasis"><em>List Comprehensions</em></span> one can create
+ <span class="emphasis"><em>Lists</em></span> from other type of sequential data structures or other
+ <span class="emphasis"><em>Lists</em></span> itself. The syntax of
+ <span class="emphasis"><em>List Comprehensions</em></span> consists of a square brackets to indicate the result is a
+ <span class="emphasis"><em>List</em></span> within which we include at least one
+ <span class="strong"><strong>for</strong></span> clause and multiple
+ <span class="strong"><strong>if</strong></span> clauses. It will be more clear with an example:
+ </p>
+<pre class="programlisting">>>> num = [1, 2, 3]
+>>> sq = [x*x for x in num]
+>>> sq
+[1, 4, 9]
+>>> all_num = [1, 2, 3, 4, 5, 6, 7, 8, 9]
+>>> even = [x for x in all_num if x%2 == 0]
+
+</pre>
+<p><a name="x_769"></a>The syntax used here is very clear from the way it is written. It can be translated into english as, "for each element x in the list all_num, if remainder of x divided by 2 is 0, add x to the list."</p>
+</div>
+</div>
+</div></body>
+</html>
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<title>Functional Approach</title>
+<link rel="stylesheet" href="hgbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" title="Functional Approach">
+<div class="titlepage">
+<div><div><h2 class="title">
+<a name="id2760558"></a>Functional Approach</h2></div></div>
+<hr>
+</div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt><span class="section"><a href="#default-arguments">1. Default Arguments</a></span></dt>
+<dt><span class="section"><a href="#keyword-arguments">2. Keyword Arguments</a></span></dt>
+<dt><span class="section"><a href="#parameter-packing-and-unpacking">3. Parameter Packing and Unpacking</a></span></dt>
+<dt><span class="section"><a href="#nested-functions-and-scopes">4. Nested Functions and Scopes</a></span></dt>
+<dt><span class="section"><a href="#map-reduce-and-filter-functions">5. map, reduce and filter functions</a></span></dt>
+<dd><dl><dt><span class="section"><a href="#list-comprehensions">5.1. List Comprehensions</a></span></dt></dl></dd>
+</dl>
+</div>
+<p><a name="x_74b"></a>
+ <span class="emphasis"><em>Functions</em></span> allow us to enclose a set of statements and call the function again and again instead of repeating the group of statements everytime. Functions also allow us to isolate a piece of code from all the other code and provides the convenience of not polluting the global variables.
+ </p>
+<p><a name="x_74c"></a>
+ <span class="emphasis"><em>Function</em></span> in python is defined with the keyword
+ <span class="strong"><strong>def</strong></span> followed by the name of the function, in turn followed by a pair of parenthesis which encloses the list of parameters to the function. The definition line ends with a ':'. The definition line is followed by the body of the function intended by one block. The
+ <span class="emphasis"><em>Function</em></span> must return a value:
+ </p>
+<pre class="programlisting">def factorial(n):
+ fact = 1
+ for i in range(2, n):
+ fact *= i
+
+ return fact
+
+</pre>
+<p><a name="x_74d"></a>The code snippet above defines a function with the name factorial, takes the number for which the factorial must be computed, computes the factorial and returns the value.</p>
+<p><a name="x_74e"></a>A
+ <span class="emphasis"><em>Function</em></span> once defined can be used or called anywhere else in the program. We call a fucntion with its name followed by a pair of parenthesis which encloses the arguments to the function.
+ </p>
+<p><a name="x_74f"></a>The value that function returns can be assigned to a variable. Let's call the above function and store the factorial in a variable:</p>
+<pre class="programlisting">fact5 = factorial(5)
+
+</pre>
+<p><a name="x_750"></a>The value of fact5 will now be 120, which is the factorial of 5. Note that we passed 5 as the argument to the function.</p>
+<p><a name="x_751"></a>It may be necessary to document what the function does, for each of the function to help the person who reads our code to understand it better. In order to do this Python allows the first line of the function body to be a string. This string is called as
+ <span class="emphasis"><em>Documentation String</em></span> or
+ <span class="emphasis"><em>docstring</em></span>.
+ <span class="emphasis"><em>docstrings</em></span> prove to be very handy since there are number of tools which can pull out all the docstrings from Python functions and generate the documentation automatically from it.
+ <span class="emphasis"><em>docstrings</em></span> for functions can be written as follows:
+ </p>
+<pre class="programlisting">def factorial(n):
+ 'Returns the factorial for the number n.'
+ fact = 1
+ for i in range(2, n):
+ fact *= i
+
+ return fact
+
+</pre>
+<p><a name="x_752"></a>An important point to note at this point is that, a function can return any Python value or a Python object, which also includes a
+ <span class="emphasis"><em>Tuple</em></span>. A
+ <span class="emphasis"><em>Tuple</em></span> is just a collection of values and those values themselves can be of any other valid Python datatypes, including
+ <span class="emphasis"><em>Lists</em></span>,
+ <span class="emphasis"><em>Tuples</em></span>,
+ <span class="emphasis"><em>Dictionaries</em></span> among other things. So effectively, if a function can return a tuple, it can return any number of values through a tuple
+ </p>
+<p><a name="x_753"></a>Let us write a small function to swap two values:</p>
+<pre class="programlisting">def swap(a, b):
+ return b, a
+
+c, d = swap(a, b)
+
+</pre>
+<p><a name="x_754"></a>Function scope --------------- The variables used inside the function are confined to the function's scope and doesn't pollute the variables of the same name outside the scope of the function. Also the arguments passed to the function are passed by-value if it is of basic Python data type:</p>
+<pre class="programlisting">def cant_change(n):
+ n = 10
+
+n = 5
+cant_change(n)
+
+</pre>
+<p><a name="x_755"></a>Upon running this code, what do you think would have happened to value of n which was assigned 5 before the function call? If you have already tried out that snippet on the interpreter you already know that the value of n is not changed. This is true of any immutable types of Python like
+ <span class="emphasis"><em>Numbers</em></span>,
+ <span class="emphasis"><em>Strings</em></span> and
+ <span class="emphasis"><em>Tuples</em></span>. But when you pass mutable objects like
+ <span class="emphasis"><em>Lists</em></span> and
+ <span class="emphasis"><em>Dictionaries</em></span> the values are manipulated even outside the function:
+ </p>
+<pre class="programlisting">>>> def can_change(n):
+... n[1] = James
+...
+
+>>> name = ['Mr.', 'Steve', 'Gosling']
+>>> can_change(name)
+>>> name
+['Mr.', 'James', 'Gosling']
+
+</pre>
+<p><a name="x_756"></a>If nothing is returned by the function explicitly, Python takes care to return None when the funnction is called.</p>
+<div class="section" title="1. Default Arguments">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="default-arguments"></a>1. Default Arguments</h2></div></div></div>
+<p><a name="x_757"></a>There may be situations where we need to allow the functions to take the arguments optionally. Python allows us to define function this way by providing a facility called
+ <span class="emphasis"><em>Default Arguments</em></span>. For example, we need to write a function that returns a list of fibonacci numbers. Since our function cannot generate an infinite list of fibonacci numbers, we need to specify the number of elements that the fibonacci sequence must contain. Suppose, additionally, we want to the function to return 10 numbers in the sequence if no option is specified we can define the function as follows:
+ </p>
+<pre class="programlisting">def fib(n=10):
+ fib_list = [0, 1]
+ for i in range(n - 2):
+ next = fib_list[-2] + fib_list[-1]
+ fib_list.append(next)
+ return fib_list
+
+</pre>
+<p><a name="x_758"></a>When we call this function, we can optionally specify the value for the parameter n, during the call as an argument. Calling with no argument and argument with n=5 returns the following fibonacci sequences:</p>
+<pre class="programlisting">fib()
+[0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
+fib(5)
+[0, 1, 1, 2, 3]
+
+</pre>
+</div>
+<div class="section" title="2. Keyword Arguments">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="keyword-arguments"></a>2. Keyword Arguments</h2></div></div></div>
+<p><a name="x_759"></a>When a function takes a large number of arguments, it may be difficult to remember the order of the parameters in the function definition or it may be necessary to pass values to only certain parameters since others take the default value. In either of these cases, Python provides the facility of passing arguments by specifying the name of the parameter as defined in the function definition. This is known as
+ <span class="emphasis"><em>Keyword Arguments</em></span>.
+ </p>
+<p><a name="x_75a"></a>In a function call,
+ <span class="emphasis"><em>Keyword arguments</em></span> can be used for each argument, in the following fashion:
+ </p>
+<pre class="programlisting">argument_name=argument_value
+Also denoted as: keyword=argument
+
+def wish(name='World', greetings='Hello'):
+ print "%s, %s!" % (greetings, name)
+
+</pre>
+<p><a name="x_75b"></a>This function can be called in one of the following ways. It is important to note that no restriction is imposed in the order in which
+ <span class="emphasis"><em>Keyword arguments</em></span> can be specified. Also note, that we have combined
+ <span class="emphasis"><em>Keyword arguments</em></span> with
+ <span class="emphasis"><em>Default arguments</em></span> in this example, however it is not necessary:
+ </p>
+<pre class="programlisting">wish(name='Guido', greetings='Hey')
+wish(greetings='Hey', name='Guido')
+
+</pre>
+<p><a name="x_75c"></a>Calling functions by specifying arguments in the order of parameters specified in the function definition is called as
+ <span class="emphasis"><em>Positional arguments</em></span>, as opposed to
+ <span class="emphasis"><em>Keyword arguments</em></span>. It is possible to use both
+ <span class="emphasis"><em>Positional arguments</em></span> and
+ <span class="emphasis"><em>Keyword arguments</em></span> in a single function call. But Python doesn't allow us to bungle up both of them. The arguments to the function, in the call, must always start with
+ <span class="emphasis"><em>Positional arguments</em></span> which is in turn followed by
+ <span class="emphasis"><em>Keyword arguments</em></span>:
+ </p>
+<pre class="programlisting">def my_func(x, y, z, u, v, w):
+ # initialize variables.
+ ...
+ # do some stuff
+ ...
+ # return the value
+
+</pre>
+<p><a name="x_75d"></a>It is valid to call the above functions in the following ways:</p>
+<pre class="programlisting">my_func(10, 20, 30, u=1.0, v=2.0, w=3.0)
+my_func(10, 20, 30, 1.0, 2.0, w=3.0)
+my_func(10, 20, z=30, u=1.0, v=2.0, w=3.0)
+my_func(x=10, y=20, z=30, u=1.0, v=2.0, w=3.0)
+
+</pre>
+<p><a name="x_75e"></a>Following lists some of the invalid calls:</p>
+<pre class="programlisting">my_func(10, 20, z=30, 1.0, 2.0, 3.0)
+my_func(x=10, 20, z=30, 1.0, 2.0, 3.0)
+my_func(x=10, y=20, z=30, u=1.0, v=2.0, 3.0)
+
+</pre>
+</div>
+<div class="section" title="3. Parameter Packing and Unpacking">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="parameter-packing-and-unpacking"></a>3. Parameter Packing and Unpacking</h2></div></div></div>
+<p><a name="x_75f"></a>The positional arguments passed to a function can be collected in a tuple parameter and keyword arguments can be collected in a dictionary. Since keyword arguments must always be the last set of arguments passed to a function, the keyword dictionary parameter must be the last parameter. The function definition must include a list explicit parameters, followed by tuple paramter collecting parameter, whose name is preceded by a *****, for collecting positional parameters, in turn followed by the dictionary collecting parameter, whose name is preceded by a ****** :</p>
+<pre class="programlisting">def print_report(title, *args, **name):
+ """Structure of *args*
+ (age, email-id)
+ Structure of *name*
+ {
+ 'first': First Name
+ 'middle': Middle Name
+ 'last': Last Name
+ }
+ """
+
+ print "Title: %s" % (title)
+ print "Full name: %(first)s %(middle)s %(last)s" % name
+ print "Age: %d\nEmail-ID: %s" % args
+
+</pre>
+<p><a name="x_760"></a>The above function can be called as. Note, the order of keyword parameters can be interchanged:</p>
+<pre class="programlisting">>>> print_report('Employee Report', 29, 'johny@example.com', first='Johny',
+ last='Charles', middle='Douglas')
+Title: Employee Report
+Full name: Johny Douglas Charles
+Age: 29
+Email-ID: johny@example.com
+
+</pre>
+<p><a name="x_761"></a>The reverse of this can also be achieved by using a very identical syntax while calling the function. A tuple or a dictionary can be passed as arguments in place of a list of *Positional arguments* or *Keyword arguments* respectively using ***** or ****** :</p>
+<pre class="programlisting">def print_report(title, age, email, first, middle, last):
+ print "Title: %s" % (title)
+ print "Full name: %s %s %s" % (first, middle, last)
+ print "Age: %d\nEmail-ID: %s" % (age, email)
+
+>>> args = (29, 'johny@example.com')
+>>> name = {
+ 'first': 'Johny',
+ 'middle': 'Charles',
+ 'last': 'Douglas'
+ }
+>>> print_report('Employee Report', *args, **name)
+Title: Employee Report
+Full name: Johny Charles Douglas
+Age: 29
+Email-ID: johny@example.com
+
+</pre>
+</div>
+<div class="section" title="4. Nested Functions and Scopes">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="nested-functions-and-scopes"></a>4. Nested Functions and Scopes</h2></div></div></div>
+<p><a name="x_762"></a>Python allows nesting one function inside another. This style of programming turns out to be extremely flexible and powerful features when we use
+ <span class="emphasis"><em>Python decorators</em></span>. We will not talk about decorators is beyond the scope of this course. If you are interested in knowing more about
+ <span class="emphasis"><em>decorator programming</em></span> in Python you are suggested to read:
+ </p>
+<div class="literallayout"><p><br>
+ <a class="ulink" href="http://avinashv.net/2008/04/python-decorators-syntactic-sugar" target="_top">http://avinashv.net/2008/04/python-decorators-syntactic-sugar</a>/<br>
+ <a class="ulink" href="http://personalpages.tds.net" target="_top">http://personalpages.tds.net</a>/~kent37/kk/00001.html<br>
+ </p></div>
+<p><a name="x_763"></a>However, the following is an example for nested functions in Python:</p>
+<pre class="programlisting">def outer():
+ print "Outer..."
+ def inner():
+ print "Inner..."
+ print "Outer..."
+ inner()
+
+>>> outer()
+
+</pre>
+</div>
+<div class="section" title="5. map, reduce and filter functions">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="map-reduce-and-filter-functions"></a>5. map, reduce and filter functions</h2></div></div></div>
+<p><a name="x_764"></a>Python provides several built-in functions for convenience. The
+ <span class="strong"><strong>map()</strong></span>,
+ <span class="strong"><strong>reduce()</strong></span> and
+ <span class="strong"><strong>filter()</strong></span> functions prove to be very useful with sequences like
+ <span class="emphasis"><em>Lists</em></span>.
+ </p>
+<p><a name="x_765"></a>The
+ <span class="strong"><strong>map</strong></span> (
+ <span class="emphasis"><em>function</em></span>,
+ <span class="emphasis"><em>sequence</em></span>) function takes two arguments:
+ <span class="emphasis"><em>function</em></span> and a
+ <span class="emphasis"><em>sequence</em></span> argument. The
+ <span class="emphasis"><em>function</em></span> argument must be the name of the function which in turn takes a single argument, the individual element of the
+ <span class="emphasis"><em>sequence</em></span>. The
+ <span class="strong"><strong>map</strong></span> function calls
+ <span class="emphasis"><em>function(item)</em></span>, for each item in the sequence and returns a list of values, where each value is the value returned by each call to
+ <span class="emphasis"><em>function(item)</em></span>.
+ <span class="strong"><strong>map()</strong></span> function allows to pass more than one sequence. In this case, the first argument,
+ <span class="emphasis"><em>function</em></span> must take as many arguments as the number of sequences passed. This function is called with each corresponding element in the each of the sequences, or
+ <span class="strong"><strong>None</strong></span> if one of the sequence is exhausted:
+ </p>
+<pre class="programlisting">def square(x):
+ return x*x
+
+>>> map(square, [1, 2, 3, 4])
+[1, 4, 9, 16]
+
+def mul(x, y):
+ return x*y
+
+>>> map(mul, [1, 2, 3, 4], [6, 7, 8, 9])
+
+</pre>
+<p><a name="x_766"></a>The
+ <span class="strong"><strong>filter</strong></span> (
+ <span class="emphasis"><em>function</em></span>,
+ <span class="emphasis"><em>sequence</em></span>) function takes two arguments, similar to the
+ <span class="strong"><strong>map()</strong></span> function. The
+ <span class="strong"><strong>filter</strong></span> function calls
+ <span class="emphasis"><em>function(item)</em></span>, for each item in the sequence and returns all the elements in the sequence for which
+ <span class="emphasis"><em>function(item)</em></span> returned True:
+ </p>
+<pre class="programlisting">def even(x):
+ if x % 2:
+ return True
+ else:
+ return False
+
+>>> filter(even, range(1, 10))
+[1, 3, 5, 7, 9]
+
+</pre>
+<p><a name="x_767"></a>The
+ <span class="strong"><strong>reduce</strong></span> (
+ <span class="emphasis"><em>function</em></span>,
+ <span class="emphasis"><em>sequence</em></span>) function takes two arguments, similar to
+ <span class="strong"><strong>map</strong></span> function, however multiple sequences are not allowed. The
+ <span class="strong"><strong>reduce</strong></span> function calls
+ <span class="emphasis"><em>function</em></span> with first two consecutive elements in the sequence, obtains the result, calls
+ <span class="emphasis"><em>function</em></span> with the result and the subsequent element in the sequence and so on until the end of the list and returns the final result:
+ </p>
+<pre class="programlisting">def mul(x, y):
+ return x*y
+
+>>> reduce(mul, [1, 2, 3, 4])
+24
+
+</pre>
+<div class="section" title="5.1. List Comprehensions">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="list-comprehensions"></a>5.1. List Comprehensions</h3></div></div></div>
+<p><a name="x_768"></a>List Comprehension is a convenvience utility provided by Python. It is a syntatic sugar to create
+ <span class="emphasis"><em>Lists</em></span>. Using
+ <span class="emphasis"><em>List Comprehensions</em></span> one can create
+ <span class="emphasis"><em>Lists</em></span> from other type of sequential data structures or other
+ <span class="emphasis"><em>Lists</em></span> itself. The syntax of
+ <span class="emphasis"><em>List Comprehensions</em></span> consists of a square brackets to indicate the result is a
+ <span class="emphasis"><em>List</em></span> within which we include at least one
+ <span class="strong"><strong>for</strong></span> clause and multiple
+ <span class="strong"><strong>if</strong></span> clauses. It will be more clear with an example:
+ </p>
+<pre class="programlisting">>>> num = [1, 2, 3]
+>>> sq = [x*x for x in num]
+>>> sq
+[1, 4, 9]
+>>> all_num = [1, 2, 3, 4, 5, 6, 7, 8, 9]
+>>> even = [x for x in all_num if x%2 == 0]
+
+</pre>
+<p><a name="x_769"></a>The syntax used here is very clear from the way it is written. It can be translated into english as, "for each element x in the list all_num, if remainder of x divided by 2 is 0, add x to the list."</p>
+</div>
+</div>
+</div></body>
+</html>