05 - Functions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook is based on [Python Cheat Sheet](http://ehmatthes.github.io/pcc/cheatsheets/README.html) by [Eric Matthes](https://github.com/ehmatthes)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### What are functions?\n",
    "Functions are named blocks of code designed to do one specific job. Functions allow you to write code once that can then be run whenever you need to accomplish the same task. Functions can take in the information they need, and return the information they generate. Using functions effectively makes your programs easier to write, read, test, and fix."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Defining a function\n",
    "The first line of a function is its definition, marked by the keyword def. The name of the function is followed by a set of parentheses and a colon. A docstring, in triple quotes, describes what the function does. The body of a function is indented one level.\n",
    "\n",
    "To call a function, give the name of the function followed by a set of parentheses."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Making a function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello!\n"
     ]
    }
   ],
   "source": [
    "def greet_user():\n",
    "    \"\"\"Display a simple greeting.\"\"\"\n",
    "    print(\"Hello!\")\n",
    "\n",
    "greet_user()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Passing information to function\n",
    "Information that's passed to a function is called an argument; information that's received by a function is called\n",
    "a parameter. Arguments are included in parentheses after the function's name, and parameters are listed in parentheses in the function's definition."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Passing a single argument"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello, jesse!\n",
      "Hello, diana!\n",
      "Hello, brandon!\n"
     ]
    }
   ],
   "source": [
    "def greet_user(username):\n",
    "    \"\"\"Display a simple greeting.\"\"\"\n",
    "    print(\"Hello, \" + username + \"!\")\n",
    "    \n",
    "greet_user('jesse')\n",
    "greet_user('diana')\n",
    "greet_user('brandon')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Positional and keyword arguments\n",
    "The two main kinds of arguments are positional and keyword arguments. When you use positional arguments Python matches the first argument in the function call with the first parameter in the function definition, and so forth.\n",
    "\n",
    "With keyword arguments, you specify which parameter each argument should be assigned to in the function call. When you use keyword arguments, the order of the arguments doesn't matter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Using positional arguments"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "I have a hamster.\n",
      "Its name is harry.\n",
      "\n",
      "I have a dog.\n",
      "Its name is willie.\n"
     ]
    }
   ],
   "source": [
    "def describe_pet(animal, name):\n",
    "    \"\"\"Display information about a pet.\"\"\"\n",
    "    print(\"\\nI have a \" + animal + \".\")\n",
    "    print(\"Its name is \" + name + \".\")\n",
    "    \n",
    "describe_pet('hamster', 'harry')\n",
    "describe_pet('dog', 'willie')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Using keyword arguments"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "I have a hamster.\n",
      "Its name is harry.\n",
      "\n",
      "I have a dog.\n",
      "Its name is willie.\n"
     ]
    }
   ],
   "source": [
    "describe_pet(animal='hamster', name='harry')\n",
    "describe_pet(name='willie', animal='dog')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Default values\n",
    "You can provide a default value for a parameter. When function calls omit this argument the default value will be used. Parameters with default values must be listed after parameters without default values in the function's definition so positional arguments can still work correctly."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Using a default value"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "I have a hamster.\n",
      "Its name is harry.\n",
      "\n",
      "I have a dog.\n",
      "Its name is willie.\n"
     ]
    }
   ],
   "source": [
    "def describe_pet(name, animal='dog'):\n",
    "    \"\"\"Display information about a pet.\"\"\"\n",
    "    print(\"\\nI have a \" + animal + \".\")\n",
    "    print(\"Its name is \" + name + \".\")\n",
    "    \n",
    "describe_pet('harry', 'hamster')\n",
    "describe_pet('willie')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Using None to make an argument optional"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "I have a hamster.\n",
      "Its name is harry.\n",
      "\n",
      "I have a snake.\n"
     ]
    }
   ],
   "source": [
    "def describe_pet(animal, name=None):\n",
    "    \"\"\"Display information about a pet.\"\"\"\n",
    "    print(\"\\nI have a \" + animal + \".\")\n",
    "    if name:\n",
    "        print(\"Its name is \" + name + \".\")\n",
    "        \n",
    "describe_pet('hamster', 'harry')\n",
    "describe_pet('snake')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Return values\n",
    "A function can return a value or a set of values. When a function returns a value, the calling line must provide a variable in which to store the return value. A function stops running when it reaches a return statement."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Returning a single value"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Jimi Hendrix\n"
     ]
    }
   ],
   "source": [
    "def get_full_name(first, last):\n",
    "    \"\"\"Return a neatly formatted full name.\"\"\"\n",
    "    full_name = first + ' ' + last\n",
    "    return full_name.title()\n",
    "\n",
    "musician = get_full_name('jimi', 'hendrix')\n",
    "print(musician)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Returning a dictionary"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'first': 'jimi', 'last': 'hendrix'}\n"
     ]
    }
   ],
   "source": [
    "def build_person(first, last):\n",
    "    \"\"\"Return a dictionary of information about a person.\"\"\"\n",
    "    person = {'first': first, 'last': last}\n",
    "    return person\n",
    "\n",
    "musician = build_person('jimi', 'hendrix')\n",
    "print(musician)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Returning a dictionary with optional values"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'first': 'jimi', 'last': 'hendrix', 'age': 27}\n",
      "{'first': 'janis', 'last': 'joplin'}\n"
     ]
    }
   ],
   "source": [
    "def build_person(first, last, age=None):\n",
    "    \"\"\"Return a dictionary of information about a person.\"\"\"\n",
    "    person = {'first': first, 'last': last}\n",
    "    if age:\n",
    "        person['age'] = age\n",
    "    return person\n",
    "\n",
    "musician = build_person('jimi', 'hendrix', 27)\n",
    "print(musician)\n",
    "\n",
    "musician = build_person('janis', 'joplin')\n",
    "print(musician)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Passing a list to a function\n",
    "You can pass a list as an argument to a function, and the function can work with the values in the list. Any changes the function makes to the list will affect the original list. You can prevent a function from modifying a list by passing a copy of the list as an argument."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Passing a list as an argument"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello, hannah!\n",
      "Hello, ty!\n",
      "Hello, margot!\n"
     ]
    }
   ],
   "source": [
    "def greet_users(names):\n",
    "    \"\"\"Print a simple greeting to everyone.\"\"\"\n",
    "    for name in names:\n",
    "        msg = \"Hello, \" + name + \"!\"\n",
    "        print(msg)\n",
    "        \n",
    "usernames = ['hannah', 'ty', 'margot']\n",
    "greet_users(usernames)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Allowing a function to modify a list\n",
    "The following example sends a list of models to a function for printing. The original list is emptied, and the second list is filled."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Printing ring\n",
      "Printing pendant\n",
      "Printing phone case\n",
      "\n",
      "Unprinted: []\n",
      "Printed: ['ring', 'pendant', 'phone case']\n"
     ]
    }
   ],
   "source": [
    "def print_models(unprinted, printed):\n",
    "    \"\"\"3d print a set of models.\"\"\"\n",
    "    while unprinted:\n",
    "        current_model = unprinted.pop()\n",
    "        print(\"Printing \" + current_model)\n",
    "        printed.append(current_model)\n",
    "        \n",
    "        \n",
    "# Store some unprinted designs, and print each of them.\n",
    "unprinted = ['phone case', 'pendant', 'ring']\n",
    "printed = []\n",
    "print_models(unprinted, printed)\n",
    "\n",
    "print(\"\\nUnprinted:\", unprinted)\n",
    "print(\"Printed:\", printed)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Preventing a function from modifying a list\n",
    "The following example is the same as the previous one, except the original list is unchanged after calling print_models()."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Printing ring\n",
      "Printing pendant\n",
      "Printing phone case\n",
      "\n",
      "Original: ['phone case', 'pendant', 'ring']\n",
      "Printed: ['ring', 'pendant', 'phone case']\n"
     ]
    }
   ],
   "source": [
    "# Store some unprinted designs, and print each of them.\n",
    "original = ['phone case', 'pendant', 'ring']\n",
    "printed = []\n",
    "print_models(original[:], printed)\n",
    "\n",
    "print(\"\\nOriginal:\", original)\n",
    "print(\"Printed:\", printed)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Passing an arbitrary number of arguments\n",
    "Sometimes you won't know how many arguments a function will need to accept. Python allows you to collect an arbitrary number of arguments into one parameter using the * operator. A parameter that accepts an arbitrary number of arguments must come last in the function definition.\n",
    "\n",
    "The ** operator allows a parameter to collect an arbitrary number of keyword arguments."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Collecting an arbitrary number of arguments"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Making a small pizza.\n",
      "Toppings:\n",
      "- pepperoni\n",
      "\n",
      "Making a large pizza.\n",
      "Toppings:\n",
      "- bacon bits\n",
      "- pineapple\n",
      "\n",
      "Making a medium pizza.\n",
      "Toppings:\n",
      "- mushrooms\n",
      "- peppers\n",
      "- onions\n",
      "- extra cheese\n"
     ]
    }
   ],
   "source": [
    "def make_pizza(size, *toppings):\n",
    "    \"\"\"Make a pizza.\"\"\"\n",
    "    print(\"\\nMaking a \" + size + \" pizza.\")\n",
    "    print(\"Toppings:\")\n",
    "    for topping in toppings:\n",
    "        print(\"- \" + topping)\n",
    "        \n",
    "# Make three pizzas with different toppings.\n",
    "make_pizza('small', 'pepperoni')\n",
    "make_pizza('large', 'bacon bits', 'pineapple')\n",
    "make_pizza('medium', 'mushrooms', 'peppers', 'onions', 'extra cheese')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Collecting an arbitrary number of keyword arguments"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'first': 'albert', 'last': 'einstein', 'location': 'princeton'}\n",
      "{'first': 'marie', 'last': 'curie', 'location': 'paris', 'field': 'chemistry'}\n"
     ]
    }
   ],
   "source": [
    "def build_profile(first, last, **user_info):\n",
    "    \"\"\"Build a user's profile dictionary.\"\"\"\n",
    "    \n",
    "    # Build a dict with the required keys.\n",
    "    profile = {'first': first, 'last': last}\n",
    "    \n",
    "    # Add any other keys and values.\n",
    "    for key, value in user_info.items():\n",
    "        profile[key] = value\n",
    "        \n",
    "    return profile\n",
    "\n",
    "# Create two users with different kinds of information.\n",
    "user_0 = build_profile('albert', 'einstein', location='princeton')\n",
    "user_1 = build_profile('marie', 'curie', location='paris', field='chemistry')\n",
    "\n",
    "print(user_0)\n",
    "print(user_1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Modules\n",
    "You can store your functions in a separate file called a module, and then import the functions you need into the file containing your main program. This allows for cleaner program files. (Make sure your module is stored in the same directory as your main program.)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Storing a function in a module\n",
    "Check file: pizza.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Importing an entire module\n",
    "Every function in the module is available in the program file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Making a medium pizza.\n",
      "Toppings:\n",
      "- pepperoni\n",
      "\n",
      "Making a small pizza.\n",
      "Toppings:\n",
      "- bacon\n",
      "- pineapple\n"
     ]
    }
   ],
   "source": [
    "import pizza\n",
    "\n",
    "pizza.make_new_pizza('medium', 'pepperoni')\n",
    "pizza.make_new_pizza('small', 'bacon', 'pineapple')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Importing a specific function\n",
    "Only the imported functions are available in the program file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Making a medium pizza.\n",
      "Toppings:\n",
      "- pepperoni\n",
      "\n",
      "Making a small pizza.\n",
      "Toppings:\n",
      "- bacon\n",
      "- pineapple\n"
     ]
    }
   ],
   "source": [
    "from pizza import make_new_pizza\n",
    "\n",
    "make_new_pizza('medium', 'pepperoni')\n",
    "make_new_pizza('small', 'bacon', 'pineapple')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Giving a module an alias"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Making a medium pizza.\n",
      "Toppings:\n",
      "- pepperoni\n",
      "\n",
      "Making a small pizza.\n",
      "Toppings:\n",
      "- bacon\n",
      "- pineapple\n"
     ]
    }
   ],
   "source": [
    "import pizza as p\n",
    "\n",
    "p.make_new_pizza('medium', 'pepperoni')\n",
    "p.make_new_pizza('small', 'bacon', 'pineapple')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Giving a function an alias"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Making a medium pizza.\n",
      "Toppings:\n",
      "- pepperoni\n",
      "\n",
      "Making a small pizza.\n",
      "Toppings:\n",
      "- bacon\n",
      "- pineapple\n"
     ]
    }
   ],
   "source": [
    "from pizza import make_new_pizza as mnp\n",
    "\n",
    "mnp('medium', 'pepperoni')\n",
    "mnp('small', 'bacon', 'pineapple')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Importing all functions from a module\n",
    "Don't do this, but recognize it when you see it in others' code. It can result in naming conflicts, which can cause errors."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Making a medium pizza.\n",
      "Toppings:\n",
      "- pepperoni\n",
      "\n",
      "Making a small pizza.\n",
      "Toppings:\n",
      "- bacon\n",
      "- pineapple\n"
     ]
    }
   ],
   "source": [
    "from pizza import *\n",
    "\n",
    "make_new_pizza('medium', 'pepperoni')\n",
    "make_new_pizza('small', 'bacon', 'pineapple')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Notebook created by [Sujeevan Nagarajah](https://github.com/sujee81)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.6.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}