2.tour/08-Defining-Functions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "<!--BOOK_INFORMATION-->\n",
    "<img align=\"left\" style=\"padding-right:10px;\" src=\"fig/cover-small.jpg\">\n",
    "*This notebook contains an excerpt from the [Whirlwind Tour of Python](http://www.oreilly.com/programming/free/a-whirlwind-tour-of-python.csp) by Jake VanderPlas; the content is available [on GitHub](https://github.com/jakevdp/WhirlwindTourOfPython).*\n",
    "\n",
    "*The text and code are released under the [CC0](https://github.com/jakevdp/WhirlwindTourOfPython/blob/master/LICENSE) license; see also the companion project, the [Python Data Science Handbook](https://github.com/jakevdp/PythonDataScienceHandbook).*\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "<!--NAVIGATION-->\n",
    "< [Control Flow](07-Control-Flow-Statements.ipynb) | [Contents](Index.ipynb) | [Errors and Exceptions](09-Errors-and-Exceptions.ipynb) >"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Defining and Using Functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "So far, our scripts have been simple, single-use code blocks.\n",
    "\n",
    "- to make it more readable and reusable \n",
    "    - to factor-out useful pieces into reusable *functions*.\n",
    "\n",
    "Here we'll cover two ways of creating functions: \n",
    "- the ``def`` statement, useful for any type of function, and \n",
    "- the ``lambda`` statement, useful for creating short anonymous functions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Using Functions\n",
    "\n",
    "Functions are `groups of code that have a name, and can be called using parentheses`.\n",
    "\n",
    "We've seen functions before. For example, ``print`` in Python 3 is a function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "abc--->apple!"
     ]
    }
   ],
   "source": [
    "print('abc','apple', end = '!', sep = '--->')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "\n",
    "- function name ``print``  \n",
    "- function's *argument* ``'abc'``\n",
    "- *keyword arguments* \n",
    "    - One available keyword argument for the ``print()`` function (in Python 3) is ``sep``, \n",
    "        - which tells what character or characters should be used to separate multiple items:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1 2 3\n"
     ]
    }
   ],
   "source": [
    "print(1, 2, 3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1--2--3\n"
     ]
    }
   ],
   "source": [
    "print(1, 2, 3, sep='--')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "When non-keyword arguments are used together with keyword arguments, the keyword arguments must come at the end."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Defining Functions\n",
    "\n",
    "Functions become even more useful when we begin to define our own, organizing functionality to be used in multiple places.\n",
    "\n",
    "- functions are defined with the ``def`` statement.\n",
    "\n",
    "e.g., Let us define a function to make a Fibonacci sequence "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-10-17T06:39:01.026881Z",
     "start_time": "2018-10-17T06:39:01.018979Z"
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610, 987, 1597, 2584, 4181, 6765, 10946, 17711, 28657, 46368, 75025, 121393, 196418, 317811, 514229, 832040]\n"
     ]
    }
   ],
   "source": [
    "def fibonacci(N):\n",
    "    L = []\n",
    "    a, b = 0, 1\n",
    "    while len(L) < N:\n",
    "        a, b = b, a + b\n",
    "        L.append(a)\n",
    "    return L\n",
    "\n",
    "print(fibonacci(30))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Now we have a function named ``fibonacci`` which \n",
    "- takes a single argument ``N``, \n",
    "- does something with this argument, and \n",
    "- ``return``s a value; in this case, a list of the first ``N`` Fibonacci numbers:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, 1, 2, 3, 5, 8, 13, 21, 34, 55]"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fibonacci(10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "If you're familiar with strongly-typed languages like ``C``, you'll immediately notice that \n",
    "- **no type information** associated with the function inputs or outputs.\n",
    "    - return any Python object\n",
    "    - simple or compound\n",
    "        - which means `constructs` are straightforward in Python (that may be difficult in other languages).\n",
    "\n",
    "For example, multiple return values are simply put in a tuple, which is indicated by commas:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3.0 4.0 (3-4j)\n"
     ]
    }
   ],
   "source": [
    "def real_imag_conj(val):\n",
    "    return val.real, val.imag, val.conjugate()\n",
    "\n",
    "r, i, c = real_imag_conj(3 + 4j)\n",
    "print(r, i, c)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Default Argument Values\n",
    "\n",
    "Often when defining a function, \n",
    "- there are certain values that we want the function to use *most* of the time, but \n",
    "- we'd also like to give the user some flexibility.\n",
    "\n",
    "In this case, we can use *default values* for arguments.\n",
    "\n",
    "Consider the ``fibonacci`` function from before.\n",
    "- What if we would like the user to be able to play with the starting values?\n",
    "- We could do that as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-10-17T06:43:05.449234Z",
     "start_time": "2018-10-17T06:43:05.443584Z"
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "def fibonacci(N, a=0, b=1):\n",
    "    L = []\n",
    "    while len(L) < N:\n",
    "        a, b = b, a + b\n",
    "        L.append(a)\n",
    "    return L"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "With a single argument, the result of the function call is identical to before:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-10-17T06:43:07.391274Z",
     "start_time": "2018-10-17T06:43:07.386721Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, 1, 2, 3, 5, 8, 13, 21, 34, 55]"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fibonacci(10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "But now we can use the function to explore new things, such as the effect of new starting values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-10-17T06:43:09.917993Z",
     "start_time": "2018-10-17T06:43:09.913366Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[5, 7, 12, 19, 31, 50, 81, 131, 212, 343]"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fibonacci(10, 2, 5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "The values can also be specified by name if desired, in which case the order of the named values does not matter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-10-17T06:43:52.486577Z",
     "start_time": "2018-10-17T06:43:52.481873Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[3, 4, 7, 11, 18, 29, 47, 76, 123, 199]"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fibonacci(10, b=3, a=1)\n",
    "#fibonacci(10, 3, 1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## ``*args`` and ``**kwargs``: Flexible Arguments\n",
    "Sometimes you might wish to write a function in which you don't initially know how many arguments the user will pass.\n",
    "\n",
    "In this case, you can use the special form ``*args`` and ``**kwargs`` to catch all arguments that are passed.\n",
    "\n",
    "Here is an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-10-17T06:45:25.811146Z",
     "start_time": "2018-10-17T06:45:25.806619Z"
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "def catch_all(*args, **kwargs):\n",
    "    print(\"args =\", args)\n",
    "    print(\"kwargs = \", kwargs)\n",
    "    \n",
    "#catch_all(*apple, **pears)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "The names ``args`` and ``kwargs`` are NOT important, but \n",
    "- the ``*`` characters preceding them ARE IMPORTANT.\n",
    "\n",
    "``args`` and ``kwargs`` are just the variable names often used by convention, \n",
    "- short for \"arguments\" and \"keyword arguments\".\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "The operative difference is the asterisk characters: \n",
    "- a single ``*`` before a variable means **\"expand this as a sequence\"**, while \n",
    "- a double ``**`` before a variable means **\"expand this as a dictionary\"**.\n",
    "\n",
    "In fact, this syntax can be used not only with the function definition, but with the function call as well!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-10-17T06:48:43.044108Z",
     "start_time": "2018-10-17T06:48:43.040244Z"
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "args = (1, 2, 3)\n",
      "kwargs =  {'a': 4, 'b': 5}\n"
     ]
    }
   ],
   "source": [
    "catch_all(1, 2, 3, a=4, b=5)\n",
    "#catch_all('apple', 'pear', sep= ';', end = '!')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "args = ('a',)\n",
      "kwargs =  {'keyword': 2}\n"
     ]
    }
   ],
   "source": [
    "catch_all('a', keyword=2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "args = (1, 2, 3)\n",
      "kwargs =  {'pi': 3.14}\n"
     ]
    }
   ],
   "source": [
    "inputs = (1, 2, 3)\n",
    "keywords = {'pi': 3.14}\n",
    "\n",
    "catch_all(*inputs, **keywords)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Anonymous (``lambda``) Functions\n",
    "\n",
    "Another way of defining short, one-off functions with the ``lambda`` statement.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "add = lambda x, y: x + y\n",
    "add(1, 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "This lambda function is roughly equivalent to"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "def add(x, y):\n",
    "    return x + y"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "So why would you ever want to use such a thing?\n",
    "- *everything is an object* in Python, even functions themselves!\n",
    "    - functions can be passed as arguments to functions.\n",
    "\n",
    "As an example of this, suppose we have some data stored in a list of dictionaries:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "data = [{'first':'Guido', 'last':'Van Rossum', 'YOB':1956},\n",
    "        {'first':'Grace', 'last':'Hopper',     'YOB':1906},\n",
    "        {'first':'Alan',  'last':'Turing',     'YOB':1912}]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Now suppose we want to sort this data.\n",
    "Python has a ``sorted`` function that does this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, 2, 3, 4, 5, 6]"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sorted([2,4,3,5,1,6])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "But dictionaries are not orderable: \n",
    "- we need a way to tell the function *how* to sort our data.\n",
    "- We can do this by specifying the ``key`` function, \n",
    "    - a function which given an item returns the sorting key for that item:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'YOB': 1912, 'first': 'Alan', 'last': 'Turing'},\n",
       " {'YOB': 1906, 'first': 'Grace', 'last': 'Hopper'},\n",
       " {'YOB': 1956, 'first': 'Guido', 'last': 'Van Rossum'}]"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# sort alphabetically by first name\n",
    "sorted(data, key=lambda item: item['first'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'YOB': 1906, 'first': 'Grace', 'last': 'Hopper'},\n",
       " {'YOB': 1912, 'first': 'Alan', 'last': 'Turing'},\n",
       " {'YOB': 1956, 'first': 'Guido', 'last': 'Van Rossum'}]"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# sort by year of birth\n",
    "sorted(data, key=lambda item: item['YOB'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "While these key functions could certainly be created by the normal, ``def`` syntax, the ``lambda`` syntax is convenient for such short one-off functions like these."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "<!--NAVIGATION-->\n",
    "< [Control Flow](07-Control-Flow-Statements.ipynb) | [Contents](Index.ipynb) | [Errors and Exceptions](09-Errors-and-Exceptions.ipynb) >"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "celltoolbar": "Slideshow",
  "kernelspec": {
   "display_name": "Python [default]",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.5.4"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": false,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}