Lectures/Week-05-Functions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "# Week 5: Functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's start with some vocabulary.  There are a lot of these with functions, and a lot of them won't make sense until we use them - chicken or the egg type of problem. We'll briefly introduce these, but just remember that these won't make a lot of sense if they aren't being used in context.\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, THIS WON'T WRITE ANYTHING OUT THOUGH!\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Try:\n",
    "\n",
    "```python\n",
    "print(\"***\\n***\\n***\") a bunch\n",
    "```\n",
    "\n",
    "or\n",
    "\n",
    "```python\n",
    "print(\"Jerry is 51 years old\")\n",
    "print(\"Agatha is 5 years old\")\n",
    "```\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "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",
    "This is a little life cycle of how a function will appear in your code.\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 (for the humans)\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.**  Think of this like a receipe, *not* the making of cookies.\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.\n",
    "    * This is where you can find out problems, for the most part.  This is you actually trying to make the cookies, but realizing you don't have flour!\n",
    "    \n",
    "There are entire books around how to format and design functions.  I'm going to give you some clear starter directions that will serve you well for this class, but be prepared as you keep going in python that you'll see some other traditions.  There are many potential cool things you can do with functions, but it's best to start off simple.  Then we can explore extra goodies."
   ]
  },
  {
   "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 function definition anatomy\n",
    "\n",
    "**NOTE: you can copy paste this into PyCharm!**  Go over these details.\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",
    "**NOTE: this printing here is helpful in debugging!!**\n",
    "\n",
    "Please look over these in detail on your own!\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? A HUGE step-by-step \n",
    "\n",
    "**If you find yourself asking WHAT ON EARTH DO I DO??**\n",
    "\n",
    "So now you want to make a function.  Here are some brief steps to making that happen.\n",
    "\n",
    "1. After the thinking phase, **use some code comments to describe what you want to do**.  Answer what the name is going to be, what it will do (using your own words), and describe in detail or give an example of the output.\n",
    "2. Decide where you should define your function.  Function definitions generally go in the top of your code, just after your import statements.  You may eventually end up with a chunk of your script that has many functions within it.  For now, **put your function definitions just after your import statements.**  If you have multiple, the order doesn't really matter at this point.  Scoot your code comments from step one up here, too.\n",
    "3.  Start you definition block. (see notes below on what this looks like).\n",
    "    * Give it the name that you chose in your thinking phase.\n",
    "    * Set this to accept one parameter, call it test.\n",
    "4.  In the first round through, I don't want you to worry about doing anything cool in your function.\n",
    "    * So in the block of your function, the only thing that I want you to have here is `return test`\n",
    "    * What we're doing here is strictly testing the input/output of your function.  Sort of the equivalent of \"Can I get the water to run through the sink?\" Only once you've established that the water will come in from the faucet and leave through the drain, you can then start thinking about washing dishes.\n",
    "\n",
    "    * At this point your function should look only like this:\n",
    "\n",
    "    ``` python\n",
    "    def thenameyouwant(test):\n",
    "        return test\n",
    "    ```\n",
    "    Seriously, that's it.  **Try running this - no errors means you are good to go!**\n",
    "5. Add your function call where you need to use it.\n",
    "    * Pass in a test input or just a string.\n",
    "    * Put your function call into a `print()` statement so you can see the output.\n",
    "    * So you should have added something like:\n",
    "    \n",
    "    ``` python\n",
    "    print(thenameyouwant(\"just testing\"))\n",
    "    ```\n",
    "6. Run your code, checking to see that what you've put in the input is coming out and there aren't any errors coming up.\n",
    "7. Now that you've proved that you can send data away and get it back, start actually writing the content of your function.\n",
    "    * redo the input parameters, removing test and adding what you really need.\n",
    "    * change the return expression to something real within the function.\n",
    "8. As you develop you function's code, test along the way.\n",
    "\n",
    "This system creates a two phased development process.  The first phase is simply hooking the function into the code and checking that the input/output is working correctly.  This can be a the hardest thing to get right when you are learning functions, so isolating it from the actual problem to solve can help keep your mind on track.  \n",
    "\n",
    "Only once you've gotten all the plumbing sorted out should you turn your attention to whatever the code should be within your function.\n",
    "\n",
    "**Try:**\n",
    "* find avg of 3 values -> a worked example\n",
    "* NOTE: no parenthesis after or around return!!\n",
    "\n",
    "# Let's work through an example\n",
    "We're going to explore each of these elements 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": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello, just testing\n"
     ]
    }
   ],
   "source": [
    "def madlib(test):\n",
    "    return test\n",
    "\n",
    "print(madlib(\"hello, just testing\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Things to note:\n",
    "\n",
    "* this has opened with a `def` block\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, this function definition has been executed, but the function content has not actually executed\n",
    "\n",
    "**Common problem!!!**  Remember that we need to call our function to actually make it run.  Again, we just want to see it working.\n",
    "\n",
    "Let's see what happens if we forget it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def madlib(test):\n",
    "    return test"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This has executed, but nothing has happened.  The code in the function has been 'learned' by python, but not actually executed.\n",
    "\n",
    "**Common problem!!**\n",
    "Let's see what happens if we run this, but forget that print statement."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'hello, just testing'"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def madlib(test):\n",
    "    return test\n",
    "\n",
    "madlib(\"hello, just testing\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once you have the plumbing phase sorted out, now you can add juicy things.\n",
    "\n",
    "When you are approaching this phase, don't forget that good variable names are so important for understanding what's going on with your code.\n",
    "\n",
    "You should know exactly what you want to send it, and put that in the variable name.\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.\n",
    "\n",
    "**Common problem!!!** You're getting an error about missing positional arguments."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "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-7-b7211d8c4d94>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[1;32m      2\u001b[0m     \u001b[0;32mreturn\u001b[0m \u001b[0msingular\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mplural\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",
    "    return singular, plural\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": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('lizard', 'lizards')"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def madlib(singular, plural):\n",
    "    return singular, plural\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",
    "    return 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 `____`?\"\n",
    "\n",
    "Let's also explore the meaning of using print and return statements.\n",
    "\n",
    "So in the following code we've got a print statement using the values in a larger thing and a return statement using just the input values. \n",
    "\n",
    "You may absolutely use print statements within your functions!  Just be mindful that they can trip you up, but they can be an excellent tool for viewing what's going on within your function.\n",
    "\n",
    "Pay careful attention to the return statement needing to be the last thing in your function."
   ]
  },
  {
   "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",
    "    return singular, 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.\n",
    "\n",
    "As you develop a function, you might start by printing values for testing, but you should quickly turn to the return statement."
   ]
  },
  {
   "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": [
      "None\n"
     ]
    }
   ],
   "source": [
    "def madlib(singular, plural):\n",
    "    sentence = \"Nice \" + singular +  \" you have there.  Where can I get some \" + plural + \"?\"\n",
    "    \n",
    "print(madlib(\"lizard\", \"lizards\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Common problem!!!** What is this `None` crap?  This happens when you print the results of a function that has no return expression.  By default, functions need to return something.  So what you don't say what you want returned, it'll give you a `None` object.\n",
    "\n",
    "You can largely ignore what this thing is, but the solution to getting rid of it is adding a return expression."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "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": "markdown",
   "metadata": {},
   "source": [
    "## Deeper dive into what `return` is\n",
    "\n",
    "Return tells the function what to pass back after execution.  Remember in the plumbing setup you were printing the value of the function call?\n",
    "\n",
    "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": [
    "# Assert statements\n",
    "\n",
    "Many students are slightly horrified that there's no control or check that the right thing is being sent into the function.  There as a way that you can do this, and it's called an `assert` statement.\n",
    "\n",
    "So here's how it goes:  you've designed a function that is supposed to take in a string into a certain variable.  You're concerned you might end up sending it a list or a number or something.\n",
    "\n",
    "While assert won't fix your program for you, you can set it to give you a more helpful error message if this assertion is violated.\n",
    "\n",
    "An assert statement creates a little gatekeeper in your program.  You are asserting a value you are declaring to be true, and if the program finds that it's not true, it will crash.\n",
    "\n",
    "I know this can sound a little scary, but you can also set it to give you a custom helpful message!\n",
    "\n",
    "Imagine that you gave someone some directions for a craft or painting project over email. In that email you have a direction like \"The mixture you make should be red.  Do not proceed with any other step if the color of the mixture is not red.  If that's the case, stop immediately and tell me.\"\n",
    "\n",
    "In this statement we are establishing a truth value (it should be red) and saying if that truth value is violated (where it is not red) then they should halt and email you.\n",
    "\n",
    "Let's see this in our madlib program.\n",
    "\n",
    "## Syntax of an assert statement\n",
    "\n",
    "You can provide a plain version of this that will crash your program, but offer no more specific message about why.  This can be sufficient, but not always helpful if you don't remember why you made that assert statement.\n",
    "\n",
    "Anywhere in your code, you can say:  \n",
    "\n",
    "``` python\n",
    "assert something == the_value_you_want\n",
    "```\n",
    "\n",
    "This will be your first time encountering the `==` operator, which is the check for equality.\n",
    "\n",
    "A more specific example will make this clearer.  In the mad lib program we want to take in two strings. We can assert that each of those variables should have a data type of string.  Remember that we can use the `type()` function to check what the data type is.  Equality checks with this function work strangely, but follow a pretty reasonable pattern that you can replicate.\n",
    "\n",
    "Let's see `==` and `type()` in action together first."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n"
     ]
    }
   ],
   "source": [
    "print(type(1) == int)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "False\n"
     ]
    }
   ],
   "source": [
    "print(type(\"not a number, yo\") == int)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n"
     ]
    }
   ],
   "source": [
    "print(type(\"this is a string\") == str)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What you say is `type(something) == keyword_of_datatype`.\n",
    "\n",
    "So integers are `int`.  Strings are `str`.  Lists are `list` etc.\n",
    "\n",
    "Now that we can create a little expression that checks the truth of our data type, we can plunk that right into this assertion statement.  If the value you assert is indeed true, python will progress through the code as normal.  Nothing will happen, nothing will confirm that this was done.  Except for the fact that the program continues on."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello fellow human\n"
     ]
    }
   ],
   "source": [
    "thing = 'hello fellow human'\n",
    "assert type(thing) == str\n",
    "print(thing)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We're going to make it fail now."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "ename": "AssertionError",
     "evalue": "",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mAssertionError\u001b[0m                            Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-16-bf16233b25dd>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[0mthing\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0;36m1\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 2\u001b[0;31m \u001b[0;32massert\u001b[0m \u001b[0mtype\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mthing\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;34m==\u001b[0m \u001b[0mstr\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m      3\u001b[0m \u001b[0mprint\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mthing\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mAssertionError\u001b[0m: "
     ]
    }
   ],
   "source": [
    "thing = 1\n",
    "assert type(thing) == str\n",
    "print(thing)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this example, we've given `thing` an integer value.  So when the assert statement hits it, the true value is checked, found to be false, and throws an assertion error.\n",
    "\n",
    "Here, let's add it to our function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "def madlib(singular, plural):\n",
    "    assert type(singular) == str\n",
    "    assert type(plural) == str\n",
    "    sentence = \"Nice \" + singular +  \" you have there.  Where can I get some \" + plural + \"?\"\n",
    "    return sentence"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we're going to run it with two strings, our asserted correct values.  We should see that this runs as normal."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Nice lizard you have there.  Where can I get some lizards?\n"
     ]
    }
   ],
   "source": [
    "animal_singular = 'lizard'\n",
    "animal_plural = 'lizards' \n",
    "\n",
    "print(madlib(animal_singular, animal_plural))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But if we try to run this with a number or list:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "ename": "AssertionError",
     "evalue": "",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mAssertionError\u001b[0m                            Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-20-69a047ae5255>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mmadlib\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;36m1\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;36m2\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;32m<ipython-input-18-55c68dcaf26d>\u001b[0m in \u001b[0;36mmadlib\u001b[0;34m(singular, plural)\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[0;32mdef\u001b[0m \u001b[0mmadlib\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msingular\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mplural\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 2\u001b[0;31m     \u001b[0;32massert\u001b[0m \u001b[0mtype\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msingular\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;34m==\u001b[0m \u001b[0mstr\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m      3\u001b[0m     \u001b[0;32massert\u001b[0m \u001b[0mtype\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mplural\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;34m==\u001b[0m \u001b[0mstr\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      4\u001b[0m     \u001b[0msentence\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0;34m\"Nice \"\u001b[0m \u001b[0;34m+\u001b[0m \u001b[0msingular\u001b[0m \u001b[0;34m+\u001b[0m  \u001b[0;34m\" you have there.  Where can I get some \"\u001b[0m \u001b[0;34m+\u001b[0m \u001b[0mplural\u001b[0m \u001b[0;34m+\u001b[0m \u001b[0;34m\"?\"\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      5\u001b[0m     \u001b[0;32mreturn\u001b[0m \u001b[0msentence\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mAssertionError\u001b[0m: "
     ]
    }
   ],
   "source": [
    "madlib(1, 2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "ename": "AssertionError",
     "evalue": "",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mAssertionError\u001b[0m                            Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-21-6d14c42d0d70>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mmadlib\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;34m'cat'\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m[\u001b[0m\u001b[0;34m'cats'\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;32m<ipython-input-18-55c68dcaf26d>\u001b[0m in \u001b[0;36mmadlib\u001b[0;34m(singular, plural)\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[0;32mdef\u001b[0m \u001b[0mmadlib\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msingular\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mplural\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 2\u001b[0;31m     \u001b[0;32massert\u001b[0m \u001b[0mtype\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msingular\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;34m==\u001b[0m \u001b[0mstr\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m      3\u001b[0m     \u001b[0;32massert\u001b[0m \u001b[0mtype\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mplural\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;34m==\u001b[0m \u001b[0mstr\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      4\u001b[0m     \u001b[0msentence\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0;34m\"Nice \"\u001b[0m \u001b[0;34m+\u001b[0m \u001b[0msingular\u001b[0m \u001b[0;34m+\u001b[0m  \u001b[0;34m\" you have there.  Where can I get some \"\u001b[0m \u001b[0;34m+\u001b[0m \u001b[0mplural\u001b[0m \u001b[0;34m+\u001b[0m \u001b[0;34m\"?\"\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      5\u001b[0m     \u001b[0;32mreturn\u001b[0m \u001b[0msentence\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mAssertionError\u001b[0m: "
     ]
    }
   ],
   "source": [
    "madlib(['cat'], ['cats'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Even though our values inside the lists are correctly strings, they are inside of a list and thus do not pass our assertion that the data type be strings.\n",
    "\n",
    "These errors have been sort of helpful in preventing python from going forward with weird data and potentially causing odd behaviors that would have been difficult to diagnose.\n",
    "\n",
    "Let's add a helpful message to ourselves, so that if we see this error come up, we can better understand what's gone wrong.  \n",
    "\n",
    "You can add a string parameter after your truth check, which will be spat out to you upon the failure of that truth check."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def madlib(singular, plural):\n",
    "    assert type(singular) == str, \"Elizabeth, singular should have been a string\"\n",
    "    assert type(plural) == str, \"Elizabeth, plural should have been a string\"\n",
    "    sentence = \"Nice \" + singular +  \" you have there.  Where can I get some \" + plural + \"?\"\n",
    "    return sentence"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Nice gecko you have there.  Where can I get some geckos?\n"
     ]
    }
   ],
   "source": [
    "print(madlib('gecko', 'geckos'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "ename": "AssertionError",
     "evalue": "Elizabeth, plural should have been a string",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mAssertionError\u001b[0m                            Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-24-3a78fcff9538>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mprint\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mmadlib\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m'gecko'\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m[\u001b[0m\u001b[0;34m'geckos'\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;32m<ipython-input-22-3cec62f3efd0>\u001b[0m in \u001b[0;36mmadlib\u001b[0;34m(singular, plural)\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[0;32mdef\u001b[0m \u001b[0mmadlib\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msingular\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mplural\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      2\u001b[0m     \u001b[0;32massert\u001b[0m \u001b[0mtype\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msingular\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;34m==\u001b[0m \u001b[0mstr\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m\"Elizabeth, singular should have been a string\"\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 3\u001b[0;31m     \u001b[0;32massert\u001b[0m \u001b[0mtype\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mplural\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;34m==\u001b[0m \u001b[0mstr\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m\"Elizabeth, plural should have been a string\"\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m      4\u001b[0m     \u001b[0msentence\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0;34m\"Nice \"\u001b[0m \u001b[0;34m+\u001b[0m \u001b[0msingular\u001b[0m \u001b[0;34m+\u001b[0m  \u001b[0;34m\" you have there.  Where can I get some \"\u001b[0m \u001b[0;34m+\u001b[0m \u001b[0mplural\u001b[0m \u001b[0;34m+\u001b[0m \u001b[0;34m\"?\"\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      5\u001b[0m     \u001b[0;32mreturn\u001b[0m \u001b[0msentence\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mAssertionError\u001b[0m: Elizabeth, plural should have been a string"
     ]
    }
   ],
   "source": [
    "print(madlib('gecko', ['geckos']))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be a real saving moment, particularly if you are moving content back and forth between a string and a list.  \n",
    "\n",
    "You also don't have to have these things inside of a function.  You can put them anywhere within your program.  This is especially helpful if you've gotten something working and want to assert a length or a data type.  That way, you can start messing with things around it and will have some idea of what is messing up.\n",
    "\n",
    "There are so many things that can change what you are working on but your later operations can still sort of work.  Assert is an optional but potentially butt saving activity."
   ]
  },
  {
   "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.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}