Lectures/Week-06-Functions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "# Spring 2018 Status: Done!\n",
    "\n",
    "# Week 6: Functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's start with some vocabulary:\n",
    "\n",
    "* __define a function__:  this is where you define the name, parameters, and code for your functions.  You do this with your `def` block.  E.g. `def name():`\n",
    "* __call a function__:  this is when you actually call the function to execute, and you do this via `name()` somewhere in your code\n",
    "* __parameters/arguments__:  these are the values you want to give the function when you call it, you can have 0 parameters/arguments\n",
    "* __'passing' values__: this is how you give the function the parameters and get values back, passing means that the value is handed off in the system such that it can be saved and processed.  This is different from printing values, which just spits the value out to the console and you can capture and save that value.\n",
    "* __`return`__: this is how you pass a value out of a function\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Functions capture and host a select chunk of code that can be repeatedly called.  These are widely used to help keep the flow of longer programs clear, because you can modularize the processing elsewhere.  There are also modules with specialized functions that we import and use for specific tasks as we need them.  \n",
    "\n",
    "So this is an element you can add into your program to make the structure of the program more organized or cleaner to understand, and less something that is necessary to help solve a problem.\n",
    "\n",
    "Functions can theoretically contain any piece of code, which means that people use them in a wide variety of styles and purposes.  There are books and many opinions on best practices for how to craft and use functions, so there's a lot of creativity.  This means that the structure of defining a function won't dictate to you how it should be used, so a lot of the work is your responsibility to keep yourself in line.\n",
    "\n",
    "When starting out with functions, think about elements that you might want to repeat over and over.  You can put all that code into a funtion, and then you just have to call the function.\n",
    "\n",
    "You might also want to use a function when your code is getting very long and you are having a hard time following what is going on in your program.  This is particularly useful when you have many levels of granularity and thus you program is starting to have many levels of indents.  For example:\n",
    "\n",
    "```\n",
    "for file in files:\n",
    "    for record in file:\n",
    "        for line in record:\n",
    "            for word in line:\n",
    "                ...\n",
    "```\n",
    "\n",
    "This is getting pretty unreadable even with no code under any of these things.  Imagine this code block, but with many lines of code for the processing under each.  You'll have a hard time understanding which for loop each piece of code belongs to.\n",
    "\n",
    "In this kind of case, we can first try to snip out the longest chunk of processing code and putting that into a function.  You could also consider making each of these a separate function, processing each level of granularity.\n",
    "\n",
    "Example:\n",
    "\n",
    "```\n",
    "for file in files:\n",
    "    records = get_records(file)\n",
    "    for record in records:\n",
    "        data = process_record(record)\n",
    "```\n",
    "\n",
    "This is still very much abstract, but imagine that all the processing for lines and words was sent off to live in the `process_record` function.  In this case, all the processing work has been sent out to `get_records` and `process_record`, so this might me all the code there is in the main processing section of our program.  This can make the control flow easier to understand because all the processing and data manipulation elements have been isolated. \n",
    "\n",
    "There are many nuanced pieces to understanding functions, so it is best to start with small examples where we can explore each piece independently."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# The life of a function\n",
    "\n",
    "A function will have three phases in your code.  This doesn't mean that these phases are traversed in order and never revisited, but this is how your code will be structured.\n",
    "\n",
    "1. _Thinking_ phase\n",
    "    * This is another 'hands off the keyboard' phase where you sit and think through the reason behind the function.  You need to think about the purpose of the function, names, and intended actions.\n",
    "2. _Defining_ phase\n",
    "    * This is where the function is defined in your code (and how to do that is the next section).  Functions are usually defined in the beginning or your script, although this isn't required.  You're going to write code according to the specifications that you determined in phase 1.  Well, there will be more questions you can't ask until you start the coding process, but the larger questions need to be answered in phase 1 before getting here.\n",
    "    * Once a function is defined, Python justs knows about it and what it does.  None of the code inside of it has been executed yet.  \n",
    "    * This definition must happen before you call the function.  The exception to this is when you may have multiple function definitions, which we are not at yet and will not discuss further. \n",
    "2.  _Calling_ phase\n",
    "    * Now that Python has learned about the function, you can make it actually execute the code.  You do this by calling the function.  Calling a function must come after you have defined it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Function call anatomy\n",
    "\n",
    "You've been using functions, how are these different?\n",
    "\n",
    "You should be used to calling functions like `len()` and `print()`.  Remember that when we call functions, we do so by stating the name of the function, followed by `()`, and then we sometimes need to place parameters inside the `()` to give it something to act on.\n",
    "\n",
    "So the anatomy of a function call is:\n",
    "\n",
    "``` python\n",
    "functionname(parameters)\n",
    "```\n",
    "\n",
    "There may be multiple parameters separated by commas, just one, or no parameters at all.  We know that these functions exist because we've been using them, but we've never actually seen them defined.\n",
    "\n",
    "The functions that we'll be doing next are our own home grown ones.  We decide what we want the functions to do, what their name is, the parameters, and what they return back to us."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# The fuction definition anatomy\n",
    "\n",
    "A quick skeleton:\n",
    "\n",
    "``` python\n",
    "def functionname(parameter1, parameter2): # define\n",
    "    result = parameter1 + parameter2 # do stuff\n",
    "    return result # return only one thing\n",
    "    \n",
    "hw_result = functionname(\"hello\", \"world\") # call the function\n",
    "print(hw_result) \n",
    "```\n",
    "\n",
    "There are the excurciatingly detailed steps to creating a function:\n",
    "\n",
    "1. Design phase (remember that these are thinking tasks here, so you can answer phase 1 items in your own natural lanugage)\n",
    "    1. what do you want to name the function?\n",
    "        * follow normal variable naming protocols\n",
    "    2. what should the function take as input, if anything?\n",
    "        * Inputs (parameters) are optional, but you could have one or many coming in.  There's other nuance here, but we're going to start with the mose generic form.\n",
    "    3. what does the function need to do?  (this answer may be very abstract when starting out)\n",
    "        * This is your 'do stuff' step.\n",
    "    4. what should the function return? or: what should the function give back to you\n",
    "        * While you can choose to not return something, we won't be doing that.\n",
    "        * You must pick one and only one object to return.  You can get away with returning multiple things by returning a data collection object, but we'll be sticking to strings and numbers for now.\n",
    "2. Defining phase (remember that this phase only teaches Python about your function.  None of the code in the body of the function has actually been executed after this phase).\n",
    "    1. Add the `def` block line in, providing the function name you chose.\n",
    "        * So you'll have `def whatever():` thus far\n",
    "    2. Add the parameter variables into the `()` of the def block\n",
    "        * Give these sensible names that you'll remember later, do not just ay x and y.\n",
    "        * You will provide these in the order that they should be provided when calling the function, and the variable names separated bf commas.  Leave the `()` empty if you aren't requiring that the function take any input.\n",
    "        * So you'll have `def whatever(thing1, thing2):` at this point\n",
    "    3. Inside the function definition block (so indented under the `def` line), add your do stuff items.\n",
    "        * So you'll have \n",
    "        ```python \n",
    "        def whatever(thing1, thing2):\n",
    "            new = thing1 + thing2\n",
    "        ```\n",
    "    4. Add your return statement\n",
    "        * this is a separate step because it will always come last in your function.\n",
    "        * it should always come last because your function execution will immediately stop as soon as Python hits a return statement.\n",
    "        * `return` is a keyword and not a function, so there aren't any `()`.  Provide the single object that you want to return after the keyword.  Do not add multiple items after this separated by commas. It'll look like it's working, but not working as you are intending.  So yes you can return back data collections.  \n",
    "        * So you'll have \n",
    "        ```python \n",
    "        def whatever(thing1, thing2):\n",
    "            new = thing1 + thing2\n",
    "            return new # see? no ()!\n",
    "        ```\n",
    "3. Calling phase (now is the time to make the code actually work.  When you call the function you are finally asking Python to actually execute the code now).\n",
    "    1. Somewhere later in your code, you'll call the function with the function's name and `()`.  You'll add this in your main code indent area, and not inside your function definition. \n",
    "    2. Provide the input values in the `()` according to how you defined it.  So if you said `def student(name, age):`, then you must provide the parameter inputs in that order. \n",
    "    3.  Choose where you want the returned results to go.  You essentially have two choices:  print it or save it to a variable.  I suggest saving it to a variable, that way you have the value to mess with later.\n",
    "        * So you'll have \n",
    "            ```python \n",
    "            def whatever(thing1, thing2):\n",
    "                new = thing1 + thing2\n",
    "                return new # see? no ()!\n",
    "                \n",
    "            myresult = whatever(\"fizzy\", \"pop\")\n",
    "            ```\n",
    "\n",
    "\n",
    "We're going to tackle these one at a time with small examples."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# What should we write?\n",
    "\n",
    "We're going to explore each of these elemests one at a time.  Don't be afraid to use the steps/checklist.\n",
    "\n",
    "We're going to write a madlib function.  Let's follow the steps.\n",
    "\n",
    "# Design\n",
    "\n",
    "1. What is the name? \n",
    "    * madlib\n",
    "2.  What should it take as input?\n",
    "    * we need two things:  a singular and plural version of the same noun\n",
    "3. What does it need to do?\n",
    "    * Craft the madlib using the words provided.\n",
    "4. What should the function return?\n",
    "    * The final string of our fully formed madlib.\n",
    "   \n",
    "\n",
    "# Define\n",
    "\n",
    "Let's use the information we determined to fill in our function definition.\n",
    "\n",
    "## 1. def block\n",
    "\n",
    "Python in general doesn't care, nor is it aware, of the content of your function names.  The usual restrictions of wariable names apply, but everything else is up to personal style choice.  Like variable names, remember that calling something `letter` doesn't mean that Python knows anything about letters or the content.  These nameso are for human consumption.\n",
    "\n",
    "The formal python style guidelines say this about how to format function names:\n",
    "\n",
    "```\n",
    "Function names should be lowercase, with words separated by underscores as necessary to improve readability.\n",
    "\n",
    "mixedCase is allowed only in contexts where that's already the prevailing style (e.g. threading.py), to retain backwards compatibility.\n",
    "```\n",
    "From PEP8: https://www.python.org/dev/peps/pep-0008/#function-names\n",
    "\n",
    "So the format should be lowercase, but the content is more up to you.  As with other variables, clarity is the most important.  You will need to type them in, so it needs to be of a reasonable length.\n",
    "\n",
    "This is a short and silly function we can use to explore the syntax.\n",
    "\n",
    "We're also just going to put a print statement in there to make it syntactically valid.  We also know that we're going to add parameters, but let's just get it working first."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def madlib():\n",
    "    print(\"hello\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Things to note:\n",
    "\n",
    "* this has opened with a `def` block\n",
    "* the `()` are there, even with nothing in them. So this function will take no parameters, or input.\n",
    "* the `()` are absolutely required, even if there are no parameters to pass\n",
    "* the code you want to run in the function is indented under the `def` opening line\n",
    "* after evaluation, thi function definition has been executed, but the function content has not actually executed\n",
    "\n",
    "Remember that we need to call our function to actually make it run.  Again, we just want to see it working."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello\n"
     ]
    }
   ],
   "source": [
    "def madlib():\n",
    "    print(\"hello\")\n",
    "\n",
    "madlib()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Things to note:\n",
    "\n",
    "* our function definition hasn't changed from above\n",
    "* we've added a function call, so the code within the function has executed\n",
    "* the function call:\n",
    "    * has the same name (content and case) as the function definition that you created\n",
    "    * the `()` are still there even if there are no parameters\n",
    "    * is not inside the function definition, so it is indented outside the function definition\n",
    "    \n",
    "## 2. add parameters\n",
    "\n",
    "Recall our definitions:\n",
    "\n",
    "* pass a value: we're going to tell our function that it will take a value in (see where `saythis` appears in the function definition inside those `()`?  The function will accept that value \n",
    "\n",
    "Parameter are the heart of the power of functions.  They allow us to not just make repeatable code, but they allow us to have that code operate on arbitary values.  We can do a little mad lib here.\n",
    "\n",
    "Remember our definition?  We want to take in a noun, but need it in a singular and plural form.  Let's call these `singular` and `plural`.  I'll add them into the parameter area and try running it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "ename": "TypeError",
     "evalue": "madlib() missing 2 required positional arguments: 'singular' and 'plural'",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mTypeError\u001b[0m                                 Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-3-c2f345013e2b>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[1;32m      2\u001b[0m     \u001b[0mprint\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m\"hello\"\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      3\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 4\u001b[0;31m \u001b[0mmadlib\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mTypeError\u001b[0m: madlib() missing 2 required positional arguments: 'singular' and 'plural'"
     ]
    }
   ],
   "source": [
    "def madlib(singular, plural):\n",
    "    print(\"hello\")\n",
    "\n",
    "madlib()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See that error?  What's happened here is that we've defined our function as requiring two inputs, but then didn't provide any when we called it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello\n"
     ]
    }
   ],
   "source": [
    "def madlib(singular, plural):\n",
    "    print(\"hello\")\n",
    "\n",
    "madlib(\"lizard\", \"lizards\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Well, now it works but it's still printing out hello.  Now is the time to do stuff!\n",
    "\n",
    "## 3. Do stuff!!!\n",
    "\n",
    "The first thing to do here is just print the parameters.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "lizard lizards\n"
     ]
    }
   ],
   "source": [
    "def madlib(singular, plural):\n",
    "    print(singular, plural)\n",
    "\n",
    "madlib(\"lizard\", \"lizards\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This isn't very juicy, but we can see that the input in going in and coming out.  Let's do something more.  What do we want our madlib to say?\n",
    "\n",
    "\"Nice `____` you have there. Where can I get some `____`?\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Nice lizard you have there.  Where can I get some lizards?\n"
     ]
    }
   ],
   "source": [
    "def madlib(singular, plural):\n",
    "    print(\"Nice\", singular, \"you have there.  Where can I get some\", plural + \"?\")\n",
    "\n",
    "madlib(\"lizard\", \"lizards\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's stop and think here for a second, we can just throw this into our print statement and see the results.  But we don't want just to print thing later.  We want the entire thing as one big string!\n",
    "\n",
    "Instead of using the print statement to make it, I'm going to do some string concatenation to make it one string.  Note that I'll need to add the spaces in explicitly, because I was previously depending on the print() function to add them for me."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def madlib(singular, plural):\n",
    "    sentence = \"Nice \" + singular +  \" you have there.  Where can I get some \" + plural + \"?\"\n",
    "\n",
    "madlib(\"lizard\", \"lizards\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ohhh!  So I've run it but nothing has happened!  Why is that?  I'm not printing anything.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Nice lizard you have there.  Where can I get some lizards?\n"
     ]
    }
   ],
   "source": [
    "def madlib(singular, plural):\n",
    "    sentence = \"Nice \" + singular +  \" you have there.  Where can I get some \" + plural + \"?\"\n",
    "    print(sentence)\n",
    "    \n",
    "madlib(\"lizard\", \"lizards\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4 add a return statement\n",
    "\n",
    "We've been using this print statement as a fexible way of viewing our output during the development process.  But when we leave it as a print statement, we can't capture that value.  What if we needed to collect this for batch processing?  What if we needed to pass this result to another function? Or do further manipulation?\n",
    "\n",
    "This is where `return` comes in.  Return tells the function what to pass back after execution.  So instead of printing a value for our human eyes via print, we can return back the value such that we can capture it in a variable.  Without a return we wouldn't be able to save the value returned from the function into a variable.\n",
    "\n",
    "Below I'll change only the line of code with the print to the return keyword.\n",
    "\n",
    "\n",
    "Return is completely different from print.  Print spits out the content to the console, but you can't access the content.  Only view it.\n",
    "\n",
    "Meanwhile, `return` will actually pass the value back to you to capture.  You'd then need to print it directly, should you want to.\n",
    "\n",
    "Recall sometimes you use functions that require a variable assignment to capture a new value.  Say we have a word and would like to know how long it is.  We know that we can use `len()` to get the number, and `print()` to see the results.  But what if we wanted to create a string of `-` that is however long our word is? We could do it all at once, but that can make our code look cluttered.  Instead, we want to save that value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Nice lizard you have there.  Where can I get some lizards?'"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def madlib(singular, plural):\n",
    "    sentence = \"Nice \" + singular +  \" you have there.  Where can I get some \" + plural + \"?\"\n",
    "    return sentence\n",
    "    \n",
    "madlib(\"lizard\", \"lizards\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So in Jupyter notebooks this will print an output, but try it in pycharm in a regular script.  Nothing will print!  The value will exist, but be sent off into the ether.  Neither saved or put in front of your eyes.\n",
    "\n",
    "You can do a few things here, but the two most straight forward are either printing the function call or saving the value to a variable (and then you can print that amongst other things). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Nice lizard you have there.  Where can I get some lizards?\n"
     ]
    }
   ],
   "source": [
    "def madlib(singular, plural):\n",
    "    sentence = \"Nice \" + singular +  \" you have there.  Where can I get some \" + plural + \"?\"\n",
    "    return sentence\n",
    "    \n",
    "print(madlib(\"lizard\", \"lizards\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Nice lizard you have there.  Where can I get some lizards?\n"
     ]
    }
   ],
   "source": [
    "def madlib(singular, plural):\n",
    "    sentence = \"Nice \" + singular +  \" you have there.  Where can I get some \" + plural + \"?\"\n",
    "    return sentence\n",
    "    \n",
    "result = madlib(\"lizard\", \"lizards\")\n",
    "print(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# All together now\n",
    "\n",
    "Let's look at how this can be seen in a larger program.  Say that we have a variety of word pairs and want to see them all.  This is where functions can come in handy.\n",
    "\n",
    "We can feed in other variables for our parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Nice lizard you have there.  Where can I get some lizards?\n"
     ]
    }
   ],
   "source": [
    "def madlib(singular, plural):\n",
    "    sentence = \"Nice \" + singular +  \" you have there.  Where can I get some \" + plural + \"?\"\n",
    "    return sentence\n",
    "    \n",
    "    \n",
    "animal_singular = 'lizard'\n",
    "animal_plural = 'lizards' \n",
    "\n",
    "print(madlib(animal_singular, animal_plural))\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also call this multiple times in a clean way."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Nice cat you have there.  Where can I get some cats?\n",
      "Nice human you have there.  Where can I get some humans?\n",
      "Nice child you have there.  Where can I get some children?\n"
     ]
    }
   ],
   "source": [
    "def madlib(singular, plural):\n",
    "    sentence = \"Nice \" + singular +  \" you have there.  Where can I get some \" + plural + \"?\"\n",
    "    return sentence\n",
    "    \n",
    "print(madlib(\"cat\", \"cats\"))\n",
    "print(madlib(\"human\", \"humans\"))\n",
    "print(madlib(\"child\", \"children\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Things to note:\n",
    "\n",
    "* this function takes 2 parameters:  `singular` and `plural`\n",
    "* these parameter names are separated by a comma and appear in our `()` in the def line\n",
    "* the order that I report the variable names in the `()` matches the order that I have them in my function call\n",
    "* there parameter variable names don't match the \"outside world\" variable names that I call the function with\n",
    "* I don't even need to have a variable in there at all\n",
    "* the \"do stuff\" portion of my code uses both the parameter variable names, and not the outside world one"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Things to note:\n",
    "\n",
    "* again, I have full access to whatever is passed in, but I have to use the parameter variable names\n",
    "* these variables are normal--just named and defined in the function definition and calling process (respecively) so I can use all normal stuff at my disposal to work with that content\n",
    "* there are no visual cues in your function definition as to what you parameter data types will be, so be careful about your variable names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# A common mistake\n",
    "\n",
    "What happens if we try to save the returned value of a function that has no return statement?\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Nice lizard you have there.  Where can I get some lizards?\n"
     ]
    }
   ],
   "source": [
    "def madlib(singular, plural):\n",
    "    sentence = \"Nice \" + singular +  \" you have there.  Where can I get some \" + plural + \"?\"\n",
    "    print(sentence)\n",
    "    \n",
    "result = madlib(\"lizard\", \"lizards\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Wait, we can see the result there!  That seems fine, right?\n",
    "\n",
    "But where did we print from?  Inside the function.  We haven't done anything with our result variable.  Why don't we see what's inside?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "None\n"
     ]
    }
   ],
   "source": [
    "print(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That wasn't our intent there.  We wanted our sentence in there.\n",
    "\n",
    "Things to notice:\n",
    "\n",
    "* our result still printed, because the print statement behaves no differently when an assignment statement is used.\n",
    "* our stored value is `None` which is the default value a function returns when you do not specify a value to return.\n",
    "* even though we can see the result, we cannot capture a result from a print statement.\n",
    "\n",
    "This is sort of like listening to a voice mail without a pen and paper.  You can hear the results, which may be enough, but you can't capture the values.\n",
    "\n",
    "By default all functions must return something.  When you don't specify something, it returns None.  Thus, if you start getting weird results with None all over the place, you've got an assignment statement on something that isn't returning anything.  Usually this means you've either forgotten to include a return statement, or you're trying to reassign the result of a function or method that is mutating an object in place (like appending to a list).\n",
    "\n",
    "Now we can add `return` to our function.  When starting out, you should always design your function's control flow so that the last line of the function is your return statement.  Python will stop running code in your function once it evaluates a return function, so this can save you a lot of grief when getting started.  Once you are more comfortable, you can change your patterns up."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# function vital facts\n",
    "\n",
    "There is one piece of trivia worth memorizing:\n",
    "\n",
    "* you can have an unlimited number of print statements in your function, and they won't effect the control flow of the program\n",
    "* you can have an unlimited number of return statements in your function, but only the first one to be executed will run.  After that the function will stop running and control flow will go back to the main program (or, wherever comes after where you called that function)\n",
    "\n",
    "We can play with our second function to see this in action.\n",
    "\n",
    "First, I'll add a print statement before my return statement, and you can see it execute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "HELLO, I WOULD LIKE TO SCIENCE.\n"
     ]
    }
   ],
   "source": [
    "def returnsomethinglouder(phrase_str):\n",
    "    text = phrase_str.upper()\n",
    "    print(text) # here I've added a print statement\n",
    "    return text\n",
    "\n",
    "louder2 = returnsomethinglouder(\"Hello, I would like to science.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, I'll move that print statement so it is after the return statement, and you can see that it doesn't execute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def returnsomethinglouder(phrase_str):\n",
    "    text = phrase_str.upper()\n",
    "    return text\n",
    "    print(text) # here I've added a print statement\n",
    "\n",
    "louder2 = returnsomethinglouder(\"Hello, I would like to science.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So you can see that nothing has happened, at least print-wise.  This is because that line literally never executes. \n",
    "\n",
    "We can see this for explicitly if we put in some code we know will cause an error, and yet that function will execute without it ever hitting that error."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def returnsomethinglouder(phrase_str):\n",
    "    text = phrase_str.upper()\n",
    "    return text\n",
    "    print(10/0) # this line will never run\n",
    "\n",
    "louder2 = returnsomethinglouder(\"Hello, I would like to science.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be quite sneaky, particularly as a newcomer not used to seeing these things.  Which is why, again, I suggest that you always design your functions so that the return is on the last line."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## An additional problem walkthrough\n",
    "\n",
    "Let's go back to our problem of the friend who is obsessed with finding secret messages.  This friend keeps sending you text files that they want you to check what the 'message' is.  You get so annoyed that you write a function to speed up this process.\n",
    "\n",
    "We can go through our 4 checklist items:\n",
    "\n",
    "1. what do you want to name the function?\n",
    "    * get_hidden_message\n",
    "2. what should the function take as parameters, if anything?\n",
    "    * Let's say that you want it to take the file name/path so that all the work is done for you.\n",
    "    * so 1 parameter:  file_path\n",
    "3. what does the function need to do?  (this answer may be very abstract when starting out)\n",
    "    * the function will repeat what we worked through last week, to find the first word oy each line.\n",
    "4. what should the function return? or: what should the function give back to you\n",
    "    * it should return the new string of the hidden message\n",
    "    \n",
    "Now we can remind ourselves what that code looked like:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Once\n",
      "Over\n",
      "While\n",
      "As\n",
      "“’Tis\n",
      "Only\n",
      "Ah,\n",
      "And\n",
      "Eagerly\n",
      "From\n",
      "For\n",
      "Nameless\n",
      "And\n",
      "Thrilled\n",
      "So\n",
      "“’Tis\n",
      "Some\n",
      "This\n",
      "Presently\n",
      "“Sir,”\n",
      "But\n",
      "And\n",
      "That\n",
      "Darkness\n",
      "Deep\n",
      "Doubting,\n",
      "But\n",
      "And\n",
      "This\n",
      "Merely\n",
      "Back\n",
      "Soon\n",
      "“Surely,”\n",
      "Let\n",
      "Let\n",
      "’Tis\n",
      "Open\n",
      "In\n",
      "Not\n",
      "But,\n",
      "Perched\n",
      "Perched,\n",
      "Then\n",
      "By\n",
      "“Though\n",
      "Ghastly\n",
      "Tell\n",
      "Quoth\n",
      "Much\n",
      "Though\n",
      "For\n",
      "Ever\n",
      "Bird\n",
      "With\n",
      "But\n",
      "That\n",
      "Nothing\n",
      "Till\n",
      "On\n",
      "Then\n",
      "Startled\n",
      "“Doubtless,”\n",
      "Caught\n",
      "Followed\n",
      "Till\n",
      "Of\n",
      "But\n",
      "Straight\n",
      "Then,\n",
      "Fancy\n",
      "What\n",
      "Meant\n",
      "This\n",
      "To\n",
      "This\n",
      "On\n",
      "But\n",
      "She\n",
      "Then,\n",
      "Swung\n",
      "“Wretch,”\n",
      "Respite—respite\n",
      "Quaff,\n",
      "Quoth\n",
      "“Prophet!”\n",
      "Whether\n",
      "Desolate\n",
      "On\n",
      "Is\n",
      "Quoth\n",
      "“Prophet!”\n",
      "By\n",
      "Tell\n",
      "It\n",
      "Clasp\n",
      "Quoth\n",
      "“Be\n",
      "“Get\n",
      "Leave\n",
      "Leave\n",
      "Take\n",
      "Quoth\n",
      "And\n",
      "On\n",
      "And\n",
      "And\n",
      "And\n",
      "Shall\n"
     ]
    }
   ],
   "source": [
    "infile = open('raven.txt', 'r') # makes our fileio object\n",
    "\n",
    "text = infile.read()\n",
    "\n",
    "infile.close()\n",
    "\n",
    "corrected_text = text.replace('\\n\\n', '\\n')\n",
    "lines = corrected_text.split('\\n')\n",
    "\n",
    "for line in lines:\n",
    "    words = line.split()\n",
    "    print(words[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "We can go ahead and plop this into a function definition.  Right now we're not going to worry about the parameters or the return statement, we just want to start somewhere and check that it continues to work as we go along.  Don't forget that we'll need to call our function to make it actually execute!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Once\n",
      "Over\n",
      "While\n",
      "As\n",
      "“’Tis\n",
      "Only\n",
      "Ah,\n",
      "And\n",
      "Eagerly\n",
      "From\n",
      "For\n",
      "Nameless\n",
      "And\n",
      "Thrilled\n",
      "So\n",
      "“’Tis\n",
      "Some\n",
      "This\n",
      "Presently\n",
      "“Sir,”\n",
      "But\n",
      "And\n",
      "That\n",
      "Darkness\n",
      "Deep\n",
      "Doubting,\n",
      "But\n",
      "And\n",
      "This\n",
      "Merely\n",
      "Back\n",
      "Soon\n",
      "“Surely,”\n",
      "Let\n",
      "Let\n",
      "’Tis\n",
      "Open\n",
      "In\n",
      "Not\n",
      "But,\n",
      "Perched\n",
      "Perched,\n",
      "Then\n",
      "By\n",
      "“Though\n",
      "Ghastly\n",
      "Tell\n",
      "Quoth\n",
      "Much\n",
      "Though\n",
      "For\n",
      "Ever\n",
      "Bird\n",
      "With\n",
      "But\n",
      "That\n",
      "Nothing\n",
      "Till\n",
      "On\n",
      "Then\n",
      "Startled\n",
      "“Doubtless,”\n",
      "Caught\n",
      "Followed\n",
      "Till\n",
      "Of\n",
      "But\n",
      "Straight\n",
      "Then,\n",
      "Fancy\n",
      "What\n",
      "Meant\n",
      "This\n",
      "To\n",
      "This\n",
      "On\n",
      "But\n",
      "She\n",
      "Then,\n",
      "Swung\n",
      "“Wretch,”\n",
      "Respite—respite\n",
      "Quaff,\n",
      "Quoth\n",
      "“Prophet!”\n",
      "Whether\n",
      "Desolate\n",
      "On\n",
      "Is\n",
      "Quoth\n",
      "“Prophet!”\n",
      "By\n",
      "Tell\n",
      "It\n",
      "Clasp\n",
      "Quoth\n",
      "“Be\n",
      "“Get\n",
      "Leave\n",
      "Leave\n",
      "Take\n",
      "Quoth\n",
      "And\n",
      "On\n",
      "And\n",
      "And\n",
      "And\n",
      "Shall\n"
     ]
    }
   ],
   "source": [
    "def get_hidden_message():\n",
    "    infile = open('raven.txt', 'r') # makes our fileio object\n",
    "\n",
    "    text = infile.read()\n",
    "\n",
    "    infile.close()\n",
    "\n",
    "    corrected_text = text.replace('\\n\\n', '\\n')\n",
    "    lines = corrected_text.split('\\n')\n",
    "\n",
    "    for line in lines:\n",
    "        words = line.split()\n",
    "        print(words[0])\n",
    "        \n",
    "get_hidden_message()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's first tackle our parameter input.  We want it to take a file path, so that the function can operate on pretty much any file.  \n",
    "\n",
    "We need to do 3 things to make this happen:\n",
    "\n",
    "1. add our parameter variable into the function definition line\n",
    "2. change our code so that it is using that paramter value instead of the hard coded file path we have right now\n",
    "3. move our file path to the raven into our parameter area when we call our function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Once\n",
      "Over\n",
      "While\n",
      "As\n",
      "“’Tis\n",
      "Only\n",
      "Ah,\n",
      "And\n",
      "Eagerly\n",
      "From\n",
      "For\n",
      "Nameless\n",
      "And\n",
      "Thrilled\n",
      "So\n",
      "“’Tis\n",
      "Some\n",
      "This\n",
      "Presently\n",
      "“Sir,”\n",
      "But\n",
      "And\n",
      "That\n",
      "Darkness\n",
      "Deep\n",
      "Doubting,\n",
      "But\n",
      "And\n",
      "This\n",
      "Merely\n",
      "Back\n",
      "Soon\n",
      "“Surely,”\n",
      "Let\n",
      "Let\n",
      "’Tis\n",
      "Open\n",
      "In\n",
      "Not\n",
      "But,\n",
      "Perched\n",
      "Perched,\n",
      "Then\n",
      "By\n",
      "“Though\n",
      "Ghastly\n",
      "Tell\n",
      "Quoth\n",
      "Much\n",
      "Though\n",
      "For\n",
      "Ever\n",
      "Bird\n",
      "With\n",
      "But\n",
      "That\n",
      "Nothing\n",
      "Till\n",
      "On\n",
      "Then\n",
      "Startled\n",
      "“Doubtless,”\n",
      "Caught\n",
      "Followed\n",
      "Till\n",
      "Of\n",
      "But\n",
      "Straight\n",
      "Then,\n",
      "Fancy\n",
      "What\n",
      "Meant\n",
      "This\n",
      "To\n",
      "This\n",
      "On\n",
      "But\n",
      "She\n",
      "Then,\n",
      "Swung\n",
      "“Wretch,”\n",
      "Respite—respite\n",
      "Quaff,\n",
      "Quoth\n",
      "“Prophet!”\n",
      "Whether\n",
      "Desolate\n",
      "On\n",
      "Is\n",
      "Quoth\n",
      "“Prophet!”\n",
      "By\n",
      "Tell\n",
      "It\n",
      "Clasp\n",
      "Quoth\n",
      "“Be\n",
      "“Get\n",
      "Leave\n",
      "Leave\n",
      "Take\n",
      "Quoth\n",
      "And\n",
      "On\n",
      "And\n",
      "And\n",
      "And\n",
      "Shall\n"
     ]
    }
   ],
   "source": [
    "def get_hidden_message(file_path): # parameter variable\n",
    "    infile = open(file_path, 'r') # using variable here\n",
    "\n",
    "    text = infile.read()\n",
    "\n",
    "    infile.close()\n",
    "\n",
    "    corrected_text = text.replace('\\n\\n', '\\n')\n",
    "    lines = corrected_text.split('\\n')\n",
    "\n",
    "    for line in lines:\n",
    "        words = line.split()\n",
    "        print(words[0])\n",
    "        \n",
    "get_hidden_message('raven.txt') # now the file path is in the call"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Last step, we need to fix our output.  We can solve this a variety of ways, but an accumulator will do the job."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Once Over While As “’Tis Only Ah, And Eagerly From For Nameless And Thrilled So “’Tis Some This Presently “Sir,” But And That Darkness Deep Doubting, But And This Merely Back Soon “Surely,” Let Let ’Tis Open In Not But, Perched Perched, Then By “Though Ghastly Tell Quoth Much Though For Ever Bird With But That Nothing Till On Then Startled “Doubtless,” Caught Followed Till Of But Straight Then, Fancy What Meant This To This On But She Then, Swung “Wretch,” Respite—respite Quaff, Quoth “Prophet!” Whether Desolate On Is Quoth “Prophet!” By Tell It Clasp Quoth “Be “Get Leave Leave Take Quoth And On And And And Shall\n"
     ]
    }
   ],
   "source": [
    "def get_hidden_message(file_path):\n",
    "    infile = open(file_path, 'r')\n",
    "\n",
    "    text = infile.read()\n",
    "\n",
    "    infile.close()\n",
    "\n",
    "    corrected_text = text.replace('\\n\\n', '\\n')\n",
    "    lines = corrected_text.split('\\n')\n",
    "\n",
    "    startwords = [] # adding accumulator\n",
    "    \n",
    "    for line in lines:\n",
    "        words = line.split()\n",
    "        startwords.append(words[0]) # incrementing\n",
    "        \n",
    "    assestence = \" \".join(startwords) # putting all the words together\n",
    "    \n",
    "    print(assestence)\n",
    "        \n",
    "get_hidden_message('raven.txt')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we're still just printing it to check that it looks good.\n",
    "\n",
    "Now we can return it, but need to remember that we need to print the value to see it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Once Over While As “’Tis Only Ah, And Eagerly From For Nameless And Thrilled So “’Tis Some This Presently “Sir,” But And That Darkness Deep Doubting, But And This Merely Back Soon “Surely,” Let Let ’Tis Open In Not But, Perched Perched, Then By “Though Ghastly Tell Quoth Much Though For Ever Bird With But That Nothing Till On Then Startled “Doubtless,” Caught Followed Till Of But Straight Then, Fancy What Meant This To This On But She Then, Swung “Wretch,” Respite—respite Quaff, Quoth “Prophet!” Whether Desolate On Is Quoth “Prophet!” By Tell It Clasp Quoth “Be “Get Leave Leave Take Quoth And On And And And Shall\n"
     ]
    }
   ],
   "source": [
    "def get_hidden_message(file_path):\n",
    "    infile = open(file_path, 'r') \n",
    "\n",
    "    text = infile.read()\n",
    "\n",
    "    infile.close()\n",
    "\n",
    "    corrected_text = text.replace('\\n\\n', '\\n')\n",
    "    lines = corrected_text.split('\\n')\n",
    "\n",
    "    startwords = []\n",
    "    \n",
    "    for line in lines:\n",
    "        words = line.split()\n",
    "        startwords.append(words[0])\n",
    "        \n",
    "    assestence = \" \".join(startwords)\n",
    "    \n",
    "    return assestence # returning now!\n",
    "        \n",
    "print(get_hidden_message('raven.txt')) # and now printing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Excellent! Let's test this on a few files."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "A \"Wheee!\" Chicka and Chicka And The Skit Mamas \"Help Next H M Look Last But A Chicka I'll Chicka\n"
     ]
    }
   ],
   "source": [
    "print(get_hidden_message('boomboom.txt'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello, Please I\n"
     ]
    }
   ],
   "source": [
    "print(get_hidden_message('smalltext.txt'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So your friend remains full of crap, but you can more efficiently process that crap."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "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.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}