lessons/python_intro/python_review_and_best_practices.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Python Version Checking"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sys\n",
    "print(\"Python Version:\", sys.version, '\\n')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Python Data Types Review"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before we start into \"how we want to write Python code\" let's make sure we've reviewed some of the basics of Python. In particular we'll focus on data types and \"specific to python\" tools in our toolbox."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### \"Normal Data Types\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Integer (int): \", type(1))\n",
    "print(\"Float (float): \", type(1.5))\n",
    "print(\"String (str): \", type(\"test\"))\n",
    "print(\"Boolean (bool): \", type(True))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These are the basic types of data that we'll mostly work with in Python. \n",
    "\n",
    "* Integers are whole numbers. \n",
    "* Floats are all other numbers. \n",
    "* Strings are text data (and can contain numbers, but aren't \"actually numbers\"). \n",
    "* Booleans are a true/false value. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Tuples and Python Selection/Slicing Rules"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A tuple is essentially a collection of other data. Let's see an example (note that tuples are designated with parenthesis):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "example_tuple = (1, 2, \"bob\", 19, \"eleventeen\", 37)\n",
    "print(example_tuple)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that we have this collection, what if we want to grab an individual piece out of it?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(example_tuple[0]) # Remember, Python starts at 0 index\n",
    "print(example_tuple[2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What if we want more than one element? Let's slice this up.\n",
    "\n",
    "Python Slicing: \n",
    "\n",
    "```python\n",
    "# short version\n",
    "name_of_object_to_slice[start:stop:step] \n",
    "\n",
    "# longer version\n",
    "name_of_object_to_slice[start_index : up_to_but_not_this_index : how many steps between returns]\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Note that we only get 3 total things, indexes 1, 2, 3\n",
    "print(example_tuple[1:4]) "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Let's go beginning to end, but skip by 2's \n",
    "# (if start is empty, assumes 0. If end is empty, assumes last value)\n",
    "print(example_tuple[::2])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Grabbing the last 2 digits\n",
    "print(example_tuple[-2:])\n",
    "print(example_tuple[-1])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What if we want to change one of the elements of a tuple?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "example_tuple[1] = 7"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Nope. Tuples don't do that. This is introduces us to the idea of **immutability**. Tuples don't allow the pieces they own to be changed any more. That's both a blessing and a curse:\n",
    "\n",
    "* Blessing: If I have correlated data that I don't want a user to be able to break, I can put it in a tuple and it's safe from them breaking the correlation.\n",
    "* Curse: I can't change my own data, and I want to. Can't add data to the tuple after the fact.\n",
    "\n",
    "Tuples are often a great choice for working with data. However, they aren't as flexible as we might need. When we run into this case... _Enter Lists_"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Lists"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Lists are also a combination of other objects, but now we're allowed to change it on the fly. Lists are super flexible, however they shouldn't be your only data type. Let's see what they do, then we'll talk about the downsides. Note, lists are designated with square brackets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "example_list = [1,2,3,4,5,6,7,8]\n",
    "print(example_list)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(example_list[0:4])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "example_list[0] = 'DIFFERENT NOW'\n",
    "print(example_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Lists are a lot like tuples, except we're allowed to change things. Lists are **mutable**.\n",
    "\n",
    "It's tempting to just always use lists for everything. Please don't. Lists are a great catch-all, but whenever you're loading a row of data or just need to put the data somewhere and then use it again later, tuples are a better choice because they are immutable and you can't really \"break\" the data as easily.\n",
    "\n",
    "You can map between lists and tuples easily by just calling the constructor like so."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_tuple = tuple(example_list)\n",
    "print(new_tuple)\n",
    "print(type(new_tuple))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_list = list(example_tuple)\n",
    "print(new_list)\n",
    "print(type(new_list))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We also want to be able add and subtract data pieces from our list."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Let's add some data to the list\n",
    "new_list.append(\"NEW DATA\")\n",
    "print(new_list)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Remove data piece\n",
    "print(new_list.pop())\n",
    "print(new_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Sets"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Sets are another type of collection, but one that allows us to do a lot of extra operations at the expense of not allowing duplication. Let's take a look. Note that sets are denoted by curly brackets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "list_to_be_made_a_set = [1,1,1,1,5,2,6,8,0]\n",
    "set_from_list = set(list_to_be_made_a_set)\n",
    "print(set_from_list)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "set_A = {0,1,2,3,4}\n",
    "set_B = {2,3,4,5,6,7}\n",
    "\n",
    "print(\"Union: \", set_A.union(set_B))\n",
    "print(\"Intersect: \", set_A.intersection(set_B))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# We can't adjust sets or look up a single element\n",
    "set_A[3]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "set_A[3] = 7"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Dictionaries"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The final major data type to consider is the dictionary. It also allows us to have \"groups\" of things, but now instead of working by index - we're going to use key-value pairs. This has some major benefits, but let's see how it works before discussing. Dictionaries are _also_ denoted with curly braces, but we have to provide keys AND values to make it not a set."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_dictionary = {'key_for_this_thing': 3}\n",
    "print(new_dictionary['key_for_this_thing'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Dictionaries can store more than just integers though. Let's look."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_dictionary = {'key_for_a_list': [0,1,2,3,4], 'key_for_another_dictionary': {'bob': 1}}\n",
    "print(new_dictionary['key_for_a_list'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(new_dictionary['key_for_another_dictionary'])\n",
    "print(new_dictionary['key_for_another_dictionary']['bob'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Example with some baseball stats!\n",
    "# Let's assume a format like [Team, Games, Plate Apperance, Home Runs]\n",
    "career_stats = {'babe_ruth': {1914: [\"Red Sox\", 5, 10, 0], 1915:['Red Sox', 43, 104, 4]},\n",
    "                'gavvy_cravath': {1914: ['Phillies',149,604,14]}} # Yes, that's a real baseball player's name\n",
    "print(career_stats['babe_ruth'])\n",
    "print(career_stats['babe_ruth'][1914])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that I was able to use an integer as a key. Any object that's immutable can be used as a key. So that means we can't use lists as keys, but we can use tuples. Let's try to add some things to our dictionary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# New entry using a tuple\n",
    "career_stats[('a','new','player')] = ['Reds',12, 34, 8]\n",
    "\n",
    "for key, val in career_stats.items(): #items allows us to access each key-value pair\n",
    "    print(key, val)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# We can also access just the keys or just the values with the proper methods\n",
    "print(career_stats.keys())\n",
    "print(career_stats.values())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# New entry with a list\n",
    "career_stats[['a','new','player']] = ['Reds',12, 34, 8]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So dictionaries allow us to assign a key to each value we want to contain. The keys must be immutable to be `hashable`, which is why it's complaining about the list. \n",
    "\n",
    "What's a `hash` though? The reason we like dictionaries is that they are really fast at retrieving data. A hash essentially says, \"I'm going to store this data about `babe_ruth` (the key given) in memory over at address XYZ. So when someone asks for the key `babe_ruth` I'll just know to go to XYZ right away. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Arrays\n",
    "\n",
    "The final Python datatype that is super common in data science is the array. It's like a list, but it only accepts one datatype. So it will be all integers or all floats. It's the backbone of Pandas, SkLearn, and many other programs. It's so important, we'll have a stand alone discussion of arrays once we finish this notebook. The module `numpy` is what we will use to get and manage arrays."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Following the Pythonic Coding Style"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Python has a set of rules that determine \"how we should write Python\" code. It's called [PEP8](https://www.python.org/dev/peps/pep-0008/). For the next section, we're going to go through some of the more important parts of PEP 8 that may be counter-intuitive when new to programming. We'll also highlights some of the special Python-specific types of code are. Note this is not a total demonstration of all of PEP8, we're just focusing on some specific aspects.\n",
    "\n",
    "To start, let's look at `import this` which is a small easter egg built into Python. It's meant to be a high-level guide to how we should think about Python coding. It is not binding, nor does everyone agree with all the statements, but it's a cute way to center yourself before programming in Python."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "import this"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you remember nothing else, remember these points about coding in Python:\n",
    "\n",
    ">Code is for people. 95% of the time it's not running. Write your code so that it can be read. Executing is 'secondary'. Your future self will thank you while debugging. A super clever solution that is only one line long, but no one can quickly debug is worse than a five line solution that everyone understands.\n",
    "\n",
    "> **The correct order of code development (in a nutshell)**\n",
    "> * Make it work\n",
    "> * Make it right\n",
    "> * Make it readable\n",
    "> * Make it fast (you rarely get to do this part)\n",
    "\n",
    "> \"Premature optimization of code is the root of all evil.\"\n",
    "> - Donald Knuth (Famous Computer Scientist)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Variable Names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A few quick rules on variable names. In general, I try to follow the rule, \"would an innebriated version of myself be able to figure out what this variable does from the name? If not, change it.\"\n",
    "\n",
    "More specifically:\n",
    "    \n",
    "* Your variables should be named sensible things. `x` is not a sensible thing.\n",
    "* Long-winded variable names are preferable to vague names. Shorter, but still specific names are even better.\n",
    "* Use hyphens to stand in for spaces in names (Python convention)\n",
    "* No capitalization, typically\n",
    "\n",
    "Here are some example variable names:\n",
    "\n",
    "`customer_order_value`, `ordered_document_list`, `mlb_batting_statistics_1887_1990`\n",
    "\n",
    "Even without context, I know what these variable contain. That's the type of response we want."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Functions - How we don't repeat ourselves\n",
    "\n",
    "\n",
    "If you find yourself copy-and-pasting code, don't do that. \n",
    "\n",
    "We should never copy-paste code. The solution is to build functions. Let's imagine I'm processing a bunch of rows of data where I want to pull out a user name from the sales record and keep track of how many times I've seen a user in that table. Like so:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "table1 = [['Sam', 36, 85.95],\n",
    " ['Carol', 75, 53.65],\n",
    " ['Sam', 90, 95.37],\n",
    " ['Doug', 61, 19.8],\n",
    " ['Sam', 41, 45.22],\n",
    " ['Doug', 29, 42.98],\n",
    " ['Oliver', 61, 95.74],\n",
    " ['Carol', 32, 17.12],\n",
    " ['Tari', 27, 68.83],\n",
    " ['Tari', 81, 62.47]]\n",
    "\n",
    "name_counter = {}\n",
    "for row in table1:\n",
    "    name = row[0]\n",
    "    if name in name_counter.keys():\n",
    "        name_counter[name] += 1\n",
    "    else:\n",
    "        name_counter[name] = 1\n",
    "print(name_counter)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But what if I get a new table and want to do the same thing? I have two options, I can copy that code above, or I could just make it into a function. Let's see how I would do the latter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def count_names_in_tables(table_to_count):\n",
    "    \"\"\"\n",
    "    Takes in a table of data, where the first (0th) column\n",
    "    is the name of the user, and counts how many time each\n",
    "    user appears.\n",
    "    ---\n",
    "    Inputs: table (list of lists or array)\n",
    "    Outputs: Dictionary (keys are names, values are counts)\n",
    "    \"\"\"\n",
    "    name_counter = {}\n",
    "    for row in table_to_count:\n",
    "        name = row[0]\n",
    "        if name in name_counter.keys():\n",
    "            name_counter[name] += 1\n",
    "        else:\n",
    "            name_counter[name] = 1\n",
    "    return name_counter\n",
    "\n",
    "print(count_names_in_tables(table1))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "table2 = [['Oliver', 12, 49.95],\n",
    " ['Tari', 76, 30.71],\n",
    " ['Carol', 98, 25.07],\n",
    " ['Carol', 24, 11.85],\n",
    " ['Carol', 34, 13.36],\n",
    " ['Kelly', 14, 34.31],\n",
    " ['Tari', 6, 86.11],\n",
    " ['Tari', 90, 29.08],\n",
    " ['Carol', 55, 45.61],\n",
    " ['Sam', 88, 97.47]]\n",
    "\n",
    "print(count_names_in_tables(table2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's note a few things about my function:\n",
    "\n",
    "* This didn't hard code any variables. We want our functions to be flexible.\n",
    "* This isn't something that I would only call one time - we don't want our functions to be 'python scripts' that are pretending to be functions.\n",
    "* This does one thing. At the end of the day, every function should accomplish one goal. That might mean we need to call a function within a function to make sure each function is only acheiving one goal at a time.\n",
    "\n",
    "So for example, you might have a function structure like this:\n",
    "\n",
    "```python\n",
    "def clean_person_name(name):\n",
    "    \"\"\"\n",
    "    Cleans the user name and returns it back\n",
    "    \"\"\"\n",
    "    name = name.lower()\n",
    "    name = name.replace(\"'\",\"\") # replace apostrophes with nothing for simplicity!\n",
    "    return name\n",
    "\n",
    "def process_row(row):\n",
    "    \"\"\"\n",
    "    Takes a row of data and cleans all of the columns\n",
    "    before sending it back to the main processing loop\n",
    "    \"\"\"\n",
    "    name = clean_person_name(row[0])\n",
    "    product_name = lookup_product_name_from_id(row[1])\n",
    "    converted_price = convert_pounds_to_dollars(row[2])\n",
    "    return (name, product_name, converted_price)\n",
    "```\n",
    "\n",
    "In this example, process_row only really accomplishes one task - processing each row. However, it needed some help in cleaning the persons name, so we outsourced that to the other function of `clean_person_name` which only has one job - cleaning the person's name.\n",
    "\n",
    "Those functions allow us to perform repeated actions efficiently, with minimal code. They also give us a few other benefits:\n",
    "\n",
    "* If we need to upgrade our process, we just have to change the function in one place and it will propagate to the rest of the code.\n",
    "* When we get errors, Python tracks what function broke and where, so we'll be able to quickly track down errors.\n",
    "* If we're clever with args and kwargs, we should be able to build very flexible solutions to many problems.\n",
    "    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### An exercise (finally!)\n",
    "\n",
    "Write a function that takes two strings. Return a boolean that tells us whether the two strings are anagrams of one another (I can use all the characters from one to make the other). You can then use the exercise tester to check if your code is working!\n",
    "\n",
    "When you write the function, make sure it follows all the standards we've talked about above."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# write your function here\n",
    "def anagram_checker():\n",
    "    pass"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# DON'T CHANGE THIS CELL! IT'S JUST HERE TO TEST YOUR CODE\n",
    "\n",
    "def exercise_tester():\n",
    "    \"\"\"\n",
    "    This function will test your anagram_checker function\n",
    "    by putting in some values and making sure you get the\n",
    "    correct answer!\n",
    "    \n",
    "    If you've written your code well, you should see \n",
    "    \"you passed all tests!\" as your output of this cell.\n",
    "    \"\"\"\n",
    "    \n",
    "    assert anagram_checker('cat','tac') == True, \"Failed on First Test!\"\n",
    "    assert anagram_checker('taCo','taco') == False, \"Failed on Second Test!\"\n",
    "    assert anagram_checker('realm','realm ') == False, \"Failed on Third Test!\"\n",
    "    assert anagram_checker('rail safety','fairy tales') == True, \"Failed on Fourth Test!\"\n",
    "    assert anagram_checker('steve','bob') == False, \"Failed on Fifth Test!\"\n",
    "    return \"You passed all tests!\"\n",
    "\n",
    "exercise_tester()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Document, but document well\n",
    "\n",
    "We should always heavily comment our code. However, there are bad and good ways to comment code. Let's see some examples."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Bad:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "# loop over s_list\n",
    "for x in s_list:\n",
    "    x.update() # update each thing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is just not something I'll be able to understand in 6 months. What is X? What is s_list? My comments tell me I'm updating something, but not how, what, or why. Let's see a better version."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Better:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "# Loop through all the songs in the song list to clean the titles for \n",
    "# storage in the database.\n",
    "for song in song_list:\n",
    "    song.update_title() "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Docstrings are even nicer\n",
    "\n",
    "Docstrings are triple-quoted strings places after a def or class that describes the functionality of that thing.\n",
    "\n",
    "Many tools expect and use this feature. e.g. Jupyter notebook"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "def multiply_by_two(x):\n",
    "    \"\"\"\n",
    "    This function multiplys the input by 2\n",
    "    ---\n",
    "    Input: Numerical\n",
    "    Output: Numerical\n",
    "    \"\"\"\n",
    "    return 2*x"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "multiply_by_two.__doc__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "# Put your cursor in between the parens and hit shift-tab 4-times\n",
    "# You should see that Jupyter automatically tracks the docstring as\n",
    "# documentation! There are many programs to auto-complete documentation\n",
    "# websites from docstrings.\n",
    "multiply_by_two()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## How to check for truth in Python\n",
    "\n",
    "In many languages, you need to explicitly check for equivalence. So something like:\n",
    "\n",
    "```python\n",
    "if (amount_spent == 0):\n",
    "    do_something_with_amount_spent(amount_spent)\n",
    "else:\n",
    "    yada yada yada\n",
    "```\n",
    "\n",
    "However, in Python that's considered bad form. Let's see how we can handle things in a nicer, more readable way."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "test_value = 0\n",
    "\n",
    "if test_value:\n",
    "    print(\"In the loop\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "test_value = 1\n",
    "\n",
    "if test_value:\n",
    "    print(\"In the loop\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "def evaluate_as_bool(value):\n",
    "    \"\"\"\n",
    "    Asks python what the boolean representation\n",
    "    is for the provided value\n",
    "    \"\"\"\n",
    "    print(\"{} as bool: \".format(value), bool(value))\n",
    "\n",
    "\n",
    "evaluate_as_bool(1)\n",
    "evaluate_as_bool(0)\n",
    "evaluate_as_bool(0.00001)\n",
    "evaluate_as_bool(-50000)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So python treats any non-zero number as a `True`, and exactly 0 as a `False`. What about other data structures?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "evaluate_as_bool([])\n",
    "evaluate_as_bool([\"test\"])\n",
    "evaluate_as_bool([\"test\", 2, 5])\n",
    "evaluate_as_bool((\"test\", 2, 5))\n",
    "evaluate_as_bool(())\n",
    "evaluate_as_bool({})\n",
    "evaluate_as_bool({'test'})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Python also treats empty lists/tuples/sets as `False` and non-empty lists as `True`. Using this methodology is much preferable to doing something like:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "a_list = [1,2,3,4]\n",
    "\n",
    "if len(a_list) > 0:\n",
    "    print(\"This is a terrible way to write Python\")\n",
    "    \n",
    "if a_list:\n",
    "    print(\"Yeah, this is much nicer.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "What about strings?\n",
    "\n",
    "Given what we've learned so far, what do we think these three lines will evaluate to?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "evaluate_as_bool('False')\n",
    "evaluate_as_bool('')\n",
    "evaluate_as_bool(' ') # There's a space here!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Same idea as lists. Is it an empty string? `False` otherwise, `True`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Loops are vital and should be cleanly written\n",
    "\n",
    "`for` loops are great for almost any iterable. Let's see how we SHOULD write them. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Good:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for row in table1:\n",
    "    print(row)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Bad:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for i in range(len(table1)):\n",
    "    print(table1[i])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the bad example above, I can't immediately tell what you're doing. It's opaque and hard to read. That's bad form. If you do need to get the index, use `enumerate`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for ix, row in enumerate(table1):\n",
    "    print(ix, row, table1[ix])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### List Comprehensions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When you can, you should use list comprehensions. These are specific to Python, and are great for making your code small and efficient. Let's check them out. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a_list_of_numbers = [1,2,3,4,5,7]\n",
    "\n",
    "new_list_of_numbers = [x + 1 for x in a_list_of_numbers if x > 2]\n",
    "print(new_list_of_numbers)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Unless you have a specific reason not to use a `for` loop, you shouldn't be using `while` loops. A common edge case is, what if we want to modify the object we're looping over in real-time and apply that update inside the loop. Then we might need to use a `while`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using `in` for checking existence\n",
    "\n",
    "In the above example, we used `in` to check if something was in a Python structure. Let's examine that a bit by trying to see if a letter exists in a string."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "test_string = \"test string of words, yep\"\n",
    "\n",
    "if 'z' in test_string:\n",
    "    print(\"Found a 'z'\")\n",
    "if 'e' in test_string:\n",
    "    print(\"Found an 'e'\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What about a list?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "test_list = [1,2,3,4,5]\n",
    "\n",
    "if 1 in test_list:\n",
    "    print(\"Found a '1'\")\n",
    "if 6 in test_list:\n",
    "    print(\"Found an '6'\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Lambda functions and Sorting"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "There are two \"ways\" to do sorting in Python. There's a subtle difference. Let's see them both in action and see if you can spot the difference."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "# The columns are (name, age, salary)\n",
    "alumni = [('bob',32,72000),\n",
    "          ('alice',29,115000),\n",
    "          ('charlie',25,95000)]\n",
    "\n",
    "sorted(alumni) # This is the keyword for the built in python sorter\n",
    "print(alumni)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "alumni.sort() # This is the method that a list has to sort itself\n",
    "print(alumni)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What happened? When we ran `sorted` it didn't appear to work. Why? \n",
    "\n",
    "Let's try it this way:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "alumni = [('bob',32,72000),\n",
    "          ('alice',29,115000),\n",
    "          ('charlie',25,95000)]\n",
    "print(sorted(alumni))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now it worked! That's because when we run `sorted(input_list)`, it actually makes a new list that is the sorted list, instead of changing the data in place. \n",
    "\n",
    "It's usually safer to run `sorted` than `.sort`, because if you accidentally `.sort` wrongly, you are changing your source data. Let's play around with our sorting options a bit to try to sort backwards, and then by salary instead."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "print(sorted(alumni, reverse=True))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To sort by some value other than the first object in the record, we need to tell Python how to sort. This is a great use for a `lambda` function. Lambda functions are functions we can define that we don't want to save. We just want them to stick around for one line, then go away and not steal memory space. Let's see one in action, then discuss below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "print(sorted(alumni,key=lambda row: row[2]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `key` argument for sorted takes in a function that defines which piece of each data we want to sort on. Here we told it to sort on the salary (column 2) information. The function itself isn't very interesting, we don't want it to live beyond this line. So we told Python, \"hey, here's a function that takes in a single argument `row` and returns this part of the row. The sorted function knows we can automatically loop over every row using that function. Here's what it would look like:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def get_second_column_of_row(row):\n",
    "    \"\"\"\n",
    "    Returns the second column of the row\n",
    "    \"\"\"\n",
    "    return row[2]\n",
    "\n",
    "print(sorted(alumni,key=get_second_column_of_row))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But realistically, I don't want to save that function in my name space, I'll never want it again. So instead, I just use a quick lambda function to define the behavior without dirtying up all of my code with one-time-use functions. Lambda functions are a common part of the python language, especially when doing things like using `map` or `filter` functions. But those are better discussed another time."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Errors should never pass silently\n",
    "\n",
    "When things happen that are unexpected, have your code raise an exception"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "class_list = [1,2,3]\n",
    "if len(class_list) % 2 !=0:\n",
    "    raise ValueError('list should have an even number of elements')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also use `assert` to check if something is behaving correctly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def sum_up_a_list(list_to_sum):\n",
    "    \"\"\"\n",
    "    Takes a list of numbers and returns the sum\n",
    "    \"\"\"\n",
    "    assert type(list_to_sum) == list, \"Input must be a list!\"\n",
    "    return sum(list_to_sum)\n",
    "\n",
    "print(sum_up_a_list(3))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(sum_up_a_list([1,2,3]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Try-Except"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `try-except` paradigm is a great way of building code that can react to errors on the fly. The way of doing things is to put a block of code inside a `try` statement, then the \"how to react\" in the `except`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = \"1\" # this is a string version of 1, can't do math on it\n",
    "\n",
    "try:\n",
    "    print(\"Trying to divide\")\n",
    "    print(x/2)\n",
    "    print(\"This won't happen because of the error\")\n",
    "    \n",
    "except TypeError:\n",
    "    print(\"\\nOops, forgot to make it a number\")\n",
    "    print(float(x)/2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It's bad form to have an except statement that doesn't tell you what type of contingency it's planning for. These are called \"bare excepts\" and you should try to avoid them because you don't really know what's happening in the error."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "del x # Let's make sure x doesn't exist\n",
    "\n",
    "try:\n",
    "    str(x)\n",
    "except:\n",
    "    print(\"¯\\_(ツ)_/¯\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "try instead and we'll see that the error isn't a \"TypeError\" so we get a different error message telling us that this isn't the error we planned for:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "try:\n",
    "    str(x)\n",
    "except TypeError:\n",
    "    print(\"x could not be made a string\")\n",
    "    raise"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Exercise:\n",
    "\n",
    "Let's use try except to check whether something is a number. Write a function that takes in a value, and returns the integer version of the value is possible, and the string, \"NOT A NUMBER\" if it's not possible."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Your code here. \n",
    "\n",
    "\n",
    "\n",
    "# Test cases:\n",
    "# your_function_name(\"Steve\") -> \"NOT A NUMBER\"\n",
    "# your_function_name(5.41) -> 5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Reference vs Values"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Variables are not boxes, they're labels for spots in memory where things live. That means we have to be careful about how we assign things, because we might just be telling two things to point to the same address."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "a = [1,2,3]\n",
    "b = a\n",
    "b.append(4)\n",
    "\n",
    "# Even though we only modified b, do we think a will have changed?\n",
    "print(a)\n",
    "print(b)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "`b = a` does not create a new object called `b`. It pastes `b` as another label to `[1,2,3]`.\n",
    "\n",
    "If you want a new object, you will have to call some kind of constructor (like telling python to make a list out of the data at `a`'s address)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "a = [1,2,3]\n",
    "b = list(a)\n",
    "b.append(4)\n",
    "\n",
    "print(a)\n",
    "print(b)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is a tricky subject, which we'll discuss in more detail when we get to the lectuer on `deepcopy` vs `copy` later in the course."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Summary\n",
    "\n",
    "We've only touched on some of the most common \"got ya's\" in Python coding. There are many more parts of the standard that can be found here:\n",
    "\n",
    "[PEP8 Guide](https://www.python.org/dev/peps/pep-0008/)\n",
    "\n",
    "Remember: make your code easy to read. Your future self and all future team members will thank you."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "kernelspec": {
   "display_name": "Python [default]",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.6"
  },
  "toc": {
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": "block",
   "toc_window_display": false
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}