2023 07July 27.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "9244239b-2c1f-4e78-993b-a9249494d29d",
   "metadata": {},
   "source": [
    "# Agenda, week 4: Functions\n",
    "\n",
    "1. Questions\n",
    "2. What are functions? Nouns vs. verbs in programming\n",
    "3. Running functions\n",
    "4. Writing functions\n",
    "5. Arguments and parameters\n",
    "6. Return values\n",
    "7. Default argument values\n",
    "8. Complex return values and unpacking\n",
    "9. Local vs. global variables\n",
    "\n",
    "Online Python challenge"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e326469f-371a-4624-9c51-f61490183e1f",
   "metadata": {},
   "source": [
    "# What are functions?\n",
    "\n",
    "Until now, we have mostly been discussing *data*. We've talked about data types, assigning to variables, and printing values. All of that is about the data, which we can think of as the nouns of the programming world.\n",
    "\n",
    "We've seen a bunch of functions and methods, as well. Those are the verbs of the programming world. If you want to know the length of a string, you can say\n",
    "\n",
    "    len(s)\n",
    "\n",
    "and we'll get a value back.\n",
    "\n",
    "We have seen many functions and many methods so far. Wouldn't it be nice if we could define our own functions? \n",
    "\n",
    "What would that give us?  Functions allow us to think at a higher level, to use abstraction.\n",
    "\n",
    "Abstraction is a very important idea in the world of engineering in general, and programming in particular. It allows us to wrap up a bunch of complex idea in a single word or phrase. Then, when we want to build on that idea, we can simply reference that word or phrase, and build something even more complex.\n",
    "\n",
    "When we define a function, we don't add new functionality to our computer or to its program. But we do make it easier for us to think about the functionality, to reason about it and how it works relative to other functions, and we can then build more complex functions on top of it.\n",
    "\n",
    "When we define a function, we are teaching Python a new vocabulary word, one which we can then use to execute commands, and which allows us to think at this higher level.\n",
    "\n",
    "To define a function in Python:\n",
    "\n",
    "- We use the reserved word `def`\n",
    "- After saying `def`, we give the function a name -- the name is traditionally all lowercase letters, with `_` between word, aka \"snake case\"\n",
    "- After the name, we have round parentheses -- these will be empty for now, but we will put parameters in them later\n",
    "- Then, on that first line, we end with `:`\n",
    "- After that, we have an indented block\n",
    "- When the indentation ends, the function definition ends\n",
    "- Inside of a function, you can have *any* Python code you want: `for` loops, `while` loops, `input`, `print`, operations of other sorts... anything at all\n",
    "\n",
    "Once the function is defined, then we can invoke it by using its name and round parentheses."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "b7a4c988-c9e3-443f-afbd-920784a53d6e",
   "metadata": {},
   "outputs": [],
   "source": [
    "def hello():\n",
    "    print('Hello!')\n",
    "    "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "dc7d5a63-7610-4e35-9ac6-3b1aab9bd1bf",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello!\n"
     ]
    }
   ],
   "source": [
    "# now, after having executed the above cell, Python has a new verb it can run, namely \"hello\"\n",
    "\n",
    "hello()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "99501a3e-3371-42ba-a1f2-e934aa6c2f98",
   "metadata": {},
   "source": [
    "# Exercise: Simple calculator\n",
    "\n",
    "1. Define a function, `calc`, which will ask the user to enter two numbers and an operator (all separately), and will print the result on the screen.\n",
    "2. When someone calls the function, they will be asked three questions:\n",
    "    - What is the first number?\n",
    "    - What is the operator?\n",
    "    - What is the second number?\n",
    "3. Your function will know how to handle `+` and `-` (if you want, other things as well), and will then print the result of adding these two numbers together.\n",
    "\n",
    "Example:\n",
    "\n",
    "    calc()\n",
    "    Enter first number: 5\n",
    "    Enter operator: +\n",
    "    Enter second number: 7\n",
    "    5 + 7 = 12\n",
    "\n",
    "- You can assume that the user's input is numeric, but if you want to be fancy and check it, that's OK as well.\n",
    "- Don't forget that `input` always returns a string, which means that you need to use `int` to get an integer from it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "05248040-3a2f-4077-889c-a4bde1af7d1e",
   "metadata": {},
   "outputs": [],
   "source": [
    "def calc():\n",
    "    n1 = input('Enter first number: ').strip()\n",
    "    op = input('Enter operator: ').strip()\n",
    "    n2 = input('Enter second number: ').strip()\n",
    "\n",
    "    n1 = int(n1)\n",
    "    n2 = int(n2)\n",
    "\n",
    "    if op == '+':           # if has a condition\n",
    "        result = n1 + n2\n",
    "    elif op == '-':         # elif has a condition\n",
    "        result = n1 - n2  \n",
    "    else:                   # else is the fallback/default -- if none of the others fired, then this will\n",
    "        result = f'Unsupported operator {op}!'\n",
    "\n",
    "    print(f'{n1} {op} {n2} = {result}')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "13f60473-d652-4f9d-8da4-bae45b26c36f",
   "metadata": {},
   "outputs": [
    {
     "name": "stdin",
     "output_type": "stream",
     "text": [
      "Enter first number:  3\n",
      "Enter operator:  +\n",
      "Enter second number:  9\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3 + 9 = 12\n"
     ]
    }
   ],
   "source": [
    "calc()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5be366a0-36a2-49d8-8a60-310f5e24a919",
   "metadata": {},
   "outputs": [],
   "source": [
    "# A F\n",
    "\n",
    "def calc():\n",
    "    numone = input('Please enter the first number:').strip()\n",
    "    op = input('Please enter the operator:').strip()\n",
    "    numtwo = input('Please enter the second number:').strip()   \n",
    "    if op == '+':\n",
    "        print (int(numone) + int(numtwo))\n",
    "    if op == '-':\n",
    "        print (int(numone) - int(numtwo))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5f1d2861-91e8-413f-972c-4d803c82728b",
   "metadata": {},
   "source": [
    "# The story so far\n",
    "\n",
    "We now know how to write a function.  When I define a function, I'm replacing any previous function that had that name. So if I want to go back and edit a function, and then define it (with shift-enter in Jupyter), that's totally fine.  The new version will overwrite the old version.\n",
    "\n",
    "If you're writing in an editor of some sort, then every time you run the program, you're getting a new definition of the function, so it's not an issue.\n",
    "\n",
    "Defining a function is *not* the same as running it:\n",
    "\n",
    "1. First, you define it\n",
    "2. Then, you run it (using parentheses)\n",
    "\n",
    "In some programming languages, it's OK (and even traditional) to define functions at the bottom of a file, and then call them at the top of the file. That **WILL NOT WORK** in Python. First, you define the functions and then you execute the functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "84769de7-69b6-4809-8b84-e39ddae6c120",
   "metadata": {},
   "outputs": [
    {
     "name": "stdin",
     "output_type": "stream",
     "text": [
      "Enter first number:  10\n",
      "Enter operator:  *\n",
      "Enter second number:  3\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "10 * 3 = Unsupported operator *!\n"
     ]
    }
   ],
   "source": [
    "# first, the definition\n",
    "\n",
    "def calc():\n",
    "    n1 = input('Enter first number: ').strip()\n",
    "    op = input('Enter operator: ').strip()\n",
    "    n2 = input('Enter second number: ').strip()\n",
    "\n",
    "    n1 = int(n1)\n",
    "    n2 = int(n2)\n",
    "\n",
    "    if op == '+':           # if has a condition\n",
    "        result = n1 + n2\n",
    "    elif op == '-':         # elif has a condition\n",
    "        result = n1 - n2  \n",
    "    else:                   # else is the fallback/default -- if none of the others fired, then this will\n",
    "        result = f'Unsupported operator {op}!'\n",
    "\n",
    "    print(f'{n1} {op} {n2} = {result}')\n",
    "\n",
    "# then, the invocation\n",
    "calc()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "90a838e2-00cf-4f6d-af95-8f6f259a0d10",
   "metadata": {},
   "source": [
    "# This is annoying!\n",
    "\n",
    "Every time I want to calculate numbers, I not only need to invoke `calc`, but I need to be sitting in front of the computer and type the numbers and the operator.\n",
    "\n",
    "There must be a better way to do this, such that I can pass values to the function without having to type them (or get them from a file, or get them from the network, etc.)\n",
    "\n",
    "Of course this is the case, and we've seen it already -- we can pass *arguments* to functions. Those are values that are then assigned to *parameters*, variables that expect to get values passed to them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "7a2890d2-1231-446d-8963-53bf07ec7f37",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "4"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# example 1: len\n",
    "\n",
    "len('abcd')   # we're passing the string 'abcd' as an argument to \"len\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "17c14a2f-8138-4f3f-866b-1a5385ce563f",
   "metadata": {},
   "outputs": [
    {
     "name": "stdin",
     "output_type": "stream",
     "text": [
      "Enter a string:  asdfafd\n"
     ]
    }
   ],
   "source": [
    "# example 2: input\n",
    "\n",
    "s = input('Enter a string: ')   # we're passing the string 'Enter a string' to \"input\" as an argument"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "6537bdf1-65ab-4613-b8a5-aaee8962fedb",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello!\n"
     ]
    }
   ],
   "source": [
    "# what happens now if I call \"hello\" with an argument?\n",
    "\n",
    "hello()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "e5449882-2d2f-424a-a1ed-f83881574922",
   "metadata": {},
   "outputs": [
    {
     "ename": "TypeError",
     "evalue": "hello() takes 0 positional arguments but 1 was given",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mTypeError\u001b[0m                                 Traceback (most recent call last)",
      "Cell \u001b[0;32mIn[14], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m \u001b[43mhello\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;124;43m'\u001b[39;49m\u001b[38;5;124;43mworld\u001b[39;49m\u001b[38;5;124;43m'\u001b[39;49m\u001b[43m)\u001b[49m\n",
      "\u001b[0;31mTypeError\u001b[0m: hello() takes 0 positional arguments but 1 was given"
     ]
    }
   ],
   "source": [
    "hello('world')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "03a51d29-e32e-4128-9a81-7f03ae3c863e",
   "metadata": {},
   "outputs": [],
   "source": [
    "def hello():            # empty parentheses after the function name means: no arguments\n",
    "    print('Hello!')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "02d00c04-0dbf-4e3a-ad8a-28348b3a7705",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello!\n"
     ]
    }
   ],
   "source": [
    "hello()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "e7b4e00c-44a0-468b-bd4d-37a0ac9c9cc9",
   "metadata": {},
   "outputs": [],
   "source": [
    "# we can change this by re-defining our function, such that it takes one argument\n",
    "# we do this by adding a *parameter* name inside of the parentheses\n",
    "\n",
    "# arguments -- values we pass when we call a function\n",
    "# parameters -- variables we declare in a function definition, and which get arguments when the function is run\n",
    "\n",
    "def hello(name):\n",
    "    print(f'Hello, {name}!')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "35c97271-5d2f-4131-a01b-041d128cd95d",
   "metadata": {},
   "outputs": [
    {
     "ename": "TypeError",
     "evalue": "hello() missing 1 required positional argument: 'name'",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mTypeError\u001b[0m                                 Traceback (most recent call last)",
      "Cell \u001b[0;32mIn[18], line 7\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[38;5;66;03m# I have now defined the function \"hello\" twice:\u001b[39;00m\n\u001b[1;32m      2\u001b[0m \u001b[38;5;66;03m# - once with zero parameters\u001b[39;00m\n\u001b[1;32m      3\u001b[0m \u001b[38;5;66;03m# - once with one parameter\u001b[39;00m\n\u001b[1;32m      4\u001b[0m \n\u001b[1;32m      5\u001b[0m \u001b[38;5;66;03m# both cannot exist at the same time! The later definition wins. The earlier one is gone.\u001b[39;00m\n\u001b[0;32m----> 7\u001b[0m \u001b[43mhello\u001b[49m\u001b[43m(\u001b[49m\u001b[43m)\u001b[49m  \u001b[38;5;66;03m# try with zero arguments\u001b[39;00m\n",
      "\u001b[0;31mTypeError\u001b[0m: hello() missing 1 required positional argument: 'name'"
     ]
    }
   ],
   "source": [
    "# I have now defined the function \"hello\" twice:\n",
    "# - once with zero parameters\n",
    "# - once with one parameter\n",
    "\n",
    "# both cannot exist at the same time! The later definition wins. The earlier one is gone.\n",
    "\n",
    "hello()  # try with zero arguments"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "8610d861-5c65-40db-a3b4-6cacdfdf49b9",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello, world!\n"
     ]
    }
   ],
   "source": [
    "hello('world')   # the argument 'world' is assigned to the parameter \"name\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "4222d916-f65b-4d0c-b22c-6177829faa28",
   "metadata": {},
   "outputs": [
    {
     "ename": "NameError",
     "evalue": "name 'name' is not defined",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mNameError\u001b[0m                                 Traceback (most recent call last)",
      "Cell \u001b[0;32mIn[20], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m \u001b[38;5;28mprint\u001b[39m(\u001b[43mname\u001b[49m)   \u001b[38;5;66;03m# what about outside of the function?\u001b[39;00m\n",
      "\u001b[0;31mNameError\u001b[0m: name 'name' is not defined"
     ]
    }
   ],
   "source": [
    "print(name)   # what about outside of the function?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "82f69288-9f93-44f4-998c-27bee9549a16",
   "metadata": {},
   "source": [
    "# Sneak preview of local variables\n",
    "\n",
    "Any variable you define in a function does not exist outside of the function!  It is *local*."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a1059c1c-124b-4fcd-8a33-b9bb39b48b57",
   "metadata": {},
   "source": [
    "# Exercise: Better calc (with arguments!)\n",
    "\n",
    "1. Rewrite the `calc` function such that it takes three arguments -- `n1`, `op`, and `n2`.\n",
    "2. It should no longer ask the user for any inputs\n",
    "3. It should still produce the same outputs as before.\n",
    "\n",
    "Example:\n",
    "\n",
    "    calc(3, '+', 5)   # should print \"3 + 5 = 8\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "9b08dbd6-a596-47da-ae05-dcc96b7d4bbf",
   "metadata": {},
   "outputs": [],
   "source": [
    "def calc(n1, op, n2):\n",
    "    if op == '+':\n",
    "        result = n1 + n2\n",
    "    elif op == '-':\n",
    "        result = n1 - n2\n",
    "    else:\n",
    "        result = f'Bad op {op}'\n",
    "\n",
    "    print(f'{n1} {op} {n2} = {result}')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "5077f483-bceb-44c6-8ddd-72f529c89ee4",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2 + 3 = 5\n"
     ]
    }
   ],
   "source": [
    "calc(2, '+', 3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "8c4d6376-f5c3-4cd7-b57f-8cc8fd1682a1",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2 - 10 = -8\n"
     ]
    }
   ],
   "source": [
    "calc(2, '-', 10)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "867d501b-8d7e-42bc-8c46-8cef9b2b453e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2.5 - 3.8 = -1.2999999999999998\n"
     ]
    }
   ],
   "source": [
    "calc(2.5, '-', 3.8)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "id": "ea5d49e3-0086-4006-949e-79364d863863",
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "ename": "TypeError",
     "evalue": "calc() missing 1 required positional argument: 'n2'",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mTypeError\u001b[0m                                 Traceback (most recent call last)",
      "Cell \u001b[0;32mIn[25], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m \u001b[43mcalc\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;241;43m3\u001b[39;49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;124;43m'\u001b[39;49m\u001b[38;5;124;43m+\u001b[39;49m\u001b[38;5;124;43m'\u001b[39;49m\u001b[43m)\u001b[49m\n",
      "\u001b[0;31mTypeError\u001b[0m: calc() missing 1 required positional argument: 'n2'"
     ]
    }
   ],
   "source": [
    "calc(3, '+')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "id": "cbd9ad0f-3e71-4d4e-9d3a-dc0710472b07",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3 + 2 = 5\n"
     ]
    }
   ],
   "source": [
    "calc(int('3'), '+', int('2'))  # Python sees this as the same as calc(3, '+', 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "639bb87b-b143-428c-8950-3f2a470c1f9c",
   "metadata": {},
   "source": [
    "# Positional vs. keyword arguments\n",
    "\n",
    "So far, when we have called a function, the arguments have been *positional*. That means: They are assigned to parameters based on their positions.\n",
    "\n",
    "In our `calc` function, we have three parameters:\n",
    "\n",
    "    n1,    op,    n2\n",
    "\n",
    "When we called the function, we passed three arguments:\n",
    "\n",
    "    2,      '+',   3\n",
    "\n",
    "Python sees three arguments and three parameters, and assigns them in order based on their positions:\n",
    "\n",
    "- n1 = 2\n",
    "- op = '+'\n",
    "- n2 = 3\n",
    "\n",
    "Most of the time, when we call a function, we'll be passing positional arguments. *BUT* there is another kind of argument as well, known as a \"keyword argument.\" In this case, the caller specifies the name of the parameter to which the argument should be assigned.\n",
    "\n",
    "You can always tell keyword arguments, because they look like `name=value`, with an `=` in the middle.\n",
    "\n",
    "So I could also call `calc` as:\n",
    "\n",
    "    calc(n1=2, op='+', n2=3)\n",
    "\n",
    "In this case, Python will assign each argument based on the names we give.\n",
    "\n",
    "Keyword arguments are a bit clearer, and there are some cases when you *need* to use them. But most of the time, we use positional arguments.\n",
    "\n",
    "If you're wondering whether you can mix and match them, the answer is \"yes,\" but only if positional arguments all come before keyword arguments.\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "id": "368f3184-709d-4d0c-9268-89c2cfd5e501",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2 + 3 = 5\n"
     ]
    }
   ],
   "source": [
    "# all keyword\n",
    "\n",
    "calc(n1=2, op='+', n2=3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "id": "aeb05235-6023-439b-bba4-034d94cb882a",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2 + 3 = 5\n"
     ]
    }
   ],
   "source": [
    "# one positional, two keyword\n",
    "calc(2, op='+', n2=3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "id": "17d9ecdb-52fc-43ec-ab96-764438fb75ab",
   "metadata": {},
   "outputs": [
    {
     "ename": "SyntaxError",
     "evalue": "positional argument follows keyword argument (874467577.py, line 2)",
     "output_type": "error",
     "traceback": [
      "\u001b[0;36m  Cell \u001b[0;32mIn[29], line 2\u001b[0;36m\u001b[0m\n\u001b[0;31m    calc(n1=2, '+', 3)\u001b[0m\n\u001b[0m                     ^\u001b[0m\n\u001b[0;31mSyntaxError\u001b[0m\u001b[0;31m:\u001b[0m positional argument follows keyword argument\n"
     ]
    }
   ],
   "source": [
    "# But all positional arguments must come before all keyword arguments\n",
    "calc(n1=2, '+', 3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "id": "021ca25a-9707-4177-bb5a-8bfed9c6e921",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[10, 20, 30] + [40, 50, 60] = [10, 20, 30, 40, 50, 60]\n"
     ]
    }
   ],
   "source": [
    "calc([10, 20, 30], '+', [40, 50, 60])   # I can pass two lists and add them!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f20f7578-4da1-4f53-aaeb-f46ed40cdf22",
   "metadata": {},
   "source": [
    "# Dynamic languages\n",
    "\n",
    "There are several ways that programming languages are distinguished from one another. One of them is the static/dynamic divide.\n",
    "\n",
    "- In static languages, each variable can hold one specific type of value, such an integer or string. If you try to assign the wrong value to the wrong variable, you'll get an error -- typically when the program is compiled (checked and translated), before it is run. This is super annoying, but discovers all sorts of bugs early on. Examples: C, C++, Java, C#.\n",
    "\n",
    "- In dynamic languages, any variable can refer to any value. This allows us to write a single function that handles many different types of inputs, and also makes for shorter and more elegant code -- but it means that you can easily write code whose problems only show up when you run them. Examples: Python, Ruby, Lisp."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ee7ca485-17ee-40d9-97d9-c8e8069191a4",
   "metadata": {},
   "source": [
    "# Next up\n",
    "\n",
    "- Return values -- how can our function return things, not just print them?\n",
    "- Complex return values"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e2780b7d-b9a4-4612-aa16-c6fdcfdb8f81",
   "metadata": {},
   "source": [
    "# Return values\n",
    "\n",
    "So far, our functions have been able to print things on the screen. But most of the functions we've used so far don't print things (except for `print`). Rather, they *return* values which we can then print (if we want) or we can assign to a variable.\n",
    "\n",
    "In Jupyter it's often hard to see the difference between a return value and a printed value. But there is a *huge* difference. Basically, if a function returns a value, then the caller can decide what to do with it -- assign, calculate, pass, transform, or even print. But if the function prints a value, then the caller has no idea what was displayed, and cannot use it.\n",
    "\n",
    "It's almost always better for a function to return a value than to print a value.  Rather, you want to return values from a function with the `return` statement:\n",
    "\n",
    "- You can have `return` as many times as you want in a function; the first one encountered will actually fire. (You might want more than one if you have them in an `if`/`elif`/`else` condition.\n",
    "- If you use `return` without a value, then that just stops the function, and it returns the special value `None`\n",
    "- If you do not use `return` in a function, then it returns `None` at the end\n",
    "- Each time you use `return`, you can actually return a different value or type"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "id": "9957ad1e-ecc4-49bb-8b5a-e64af203f431",
   "metadata": {},
   "outputs": [],
   "source": [
    "# better version of \"hello\"\n",
    "\n",
    "def hello(name):\n",
    "    return f'Hello, {name}!'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "id": "9cd4596c-0ef0-44d1-afe8-c50b0961e20e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Hello, world!'"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hello('world')   # this returns a string... which in Jupyter is then displayed"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "id": "1ff591be-d41e-41d7-b762-11e84b3d1100",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello, world!\n"
     ]
    }
   ],
   "source": [
    "print(hello('world'))  # this is displaying on the screen, so no quotes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "id": "db214cf9-2e03-4a54-8fae-b213b8cdca10",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "str"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# we can capture the value in a variable\n",
    "\n",
    "x = hello('world')\n",
    "type(x)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "id": "61f35dbe-85cc-4f55-b022-c25827b0d193",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello, world!\n"
     ]
    }
   ],
   "source": [
    "print(x)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "id": "3a24b1f9-f7b6-48af-8998-46b667053296",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hel\n"
     ]
    }
   ],
   "source": [
    "print(x[:3])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "id": "2455f277-46b7-453c-a0e9-ad4a884c133b",
   "metadata": {},
   "outputs": [],
   "source": [
    "def myfunc():\n",
    "    print('a')\n",
    "    return\n",
    "    print('b')  # we will never get to this line!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "id": "8a45a03e-fee7-4746-b5e0-79a97eced636",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "a\n"
     ]
    }
   ],
   "source": [
    "# the right side of assignment runs before the left side\n",
    "# so myfunc runs, returns None, and then we assign None to x\n",
    "x = myfunc()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "id": "35788084-0601-4c55-8e32-8bdbfa447874",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "None\n"
     ]
    }
   ],
   "source": [
    "print(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ba5e1a35-6fda-4a6a-b1ac-b2b66e36ea91",
   "metadata": {},
   "source": [
    "# Exercise: Calculator (with return values)\n",
    "\n",
    "1. Write a new version of `calc` that takes three arguments (`n1`, `op`, and `n2`)\n",
    "2. This version should return just the numeric result from the function\n",
    "3. If the operator is unknown, the function can return None\n",
    "\n",
    "Once you have defined the function, then I want you to invoke it 5 times -- once for each integer in a list of ints that you'll create. (For example, `[10, 20, 30, 40, 50]`.)  Iterate over that list, passing the integer and 10+ that integer as arguments to `calc`, and then totalling the results you get.\n",
    "\n",
    "```python\n",
    "total = 0\n",
    "\n",
    "for one_number in [10, 20, 30, 40, 50]:\n",
    "    total += calc(one_number, '+', one_number+10)\n",
    "\n",
    "print(total)    \n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "id": "c49c6f4a-1bc5-4865-afba-5b7a43f2d45f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "4"
      ]
     },
     "execution_count": 44,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def calc(n1, op, n2):\n",
    "    if op == '+':\n",
    "        return (n1 + n2)\n",
    "    elif op == '-':\n",
    "        return (n1 - n2)\n",
    "    else:\n",
    "        return\n",
    "\n",
    "calc(2, '+', 2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "id": "073e6bdb-0012-4baf-92b6-4492983d8ec1",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "350\n"
     ]
    }
   ],
   "source": [
    "total = 0\n",
    "\n",
    "for one_number in [10, 20, 30, 40, 50]:\n",
    "    total += calc(one_number, '+', one_number+10)\n",
    "\n",
    "print(total)    \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "id": "9efbde78-5022-48f3-a27b-011d163ef02c",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "12\n",
      "42\n",
      "82\n",
      "132\n",
      "192\n"
     ]
    }
   ],
   "source": [
    "def calc(n1, op, n2):\n",
    "    if op == '+':\n",
    "        resultado = n1 + n2\n",
    "    elif op == '-':\n",
    "        resultado = n1 - n2\n",
    "    else:\n",
    "        resultado = f\"o operado {op} e invalido\"\n",
    "\n",
    "    return resultado\n",
    "\n",
    "mylist = [2, 20, 30, 40, 50]\n",
    "total = 0 \n",
    "for s in mylist:\n",
    "    total += calc(s,\"+\",10)\n",
    "    print(total)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d85f70fe-37ff-449c-b63f-93e6d068eeed",
   "metadata": {},
   "source": [
    "# What types of arguments can a function take?\n",
    "\n",
    "Anything at all. Any Python value can be passed as an argument to a function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 55,
   "id": "9012a6b4-971b-4894-b2b0-fdd3edeb753d",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "60"
      ]
     },
     "execution_count": 55,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Example: This function returns the sum of the numbers passed as an argument in a list\n",
    "# there already is a \"sum\" function in Python, but I don't want to use it\n",
    "\n",
    "def mysum(numbers):    # mysum is the function, and it takes one argument (which should be a list)\n",
    "    total = 0\n",
    "\n",
    "    for one_number in numbers:\n",
    "        total += one_number\n",
    "\n",
    "    return total\n",
    "\n",
    "mysum([10, 20, 30])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 56,
   "id": "bf3c4d2a-f574-4543-9425-43ef0124a4a0",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "30"
      ]
     },
     "execution_count": 56,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mysum([2,4,6,8,10])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "94c6eca4-a4a7-4177-8c6d-05c67deb3ddb",
   "metadata": {},
   "source": [
    "# Exercise: Largest number\n",
    "\n",
    "1. Write a function, `mymax` (because there already is a `max` function in Python, and we don't want to step on it), which takes a list of integers and returns the largest integer it can find in the list.\n",
    "2. The function should probably define a variable, `largest`, at the top, then iterate with a `for` loop over each element. If the current element is bigger than `largest`, then it should assign the current element to largest.\n",
    "3. At the end, return the largest number.\n",
    "\n",
    "Example:\n",
    "\n",
    "    mymax([10, 15, -3, 28, 17])   # returns 28"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 57,
   "id": "d4ed92b4-eb5f-4151-a5b4-dbf506c21125",
   "metadata": {},
   "outputs": [],
   "source": [
    "# don't ever use a for loop with the index! Rather, do a for loop with the elements themselves\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 58,
   "id": "6f452e72-fe81-43d2-8ec9-023834ee2083",
   "metadata": {},
   "outputs": [],
   "source": [
    "# two strategies for \"largest\" at the top of the function:\n",
    "# 1. Use numbers[0], the first number in our input list\n",
    "# 2. Use something ridiculously small, like -99999999"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 62,
   "id": "ab037a51-c86b-430e-9ceb-b41824f69d47",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "28"
      ]
     },
     "execution_count": 62,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def mymax(numbers):\n",
    "    largest = numbers[0]            # grab the first value from numbers -- assume that the first is the largest\n",
    "\n",
    "    for one_number in numbers[1:]:  # iterate over every value in numbers but the first\n",
    "        if one_number > largest:\n",
    "            largest = one_number\n",
    "\n",
    "    return largest\n",
    "\n",
    "mymax([10, 15, -3, 28, 17]) "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "75c25a90-162a-4209-9a10-299cdc74173e",
   "metadata": {},
   "source": [
    "# Complex return values\n",
    "\n",
    "A function can return anything at all. Any value that we want can be returned, including lists, tuples, etc."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 63,
   "id": "a2642742-5be6-43ee-9c52-5a4d6c73ba7b",
   "metadata": {},
   "outputs": [],
   "source": [
    "def square(n):\n",
    "    return [n, n**2]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 64,
   "id": "c3a38f6e-3b8b-4c0d-a02f-a801037f0b1a",
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[5, 25]"
      ]
     },
     "execution_count": 64,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "square(5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 66,
   "id": "18686b76-7f18-4dec-9e12-936ce85a65e1",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[5, 25]\n"
     ]
    }
   ],
   "source": [
    "print(square(5))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 65,
   "id": "25e16bca-06f0-419f-b8ce-4574d5c2272a",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "28"
      ]
     },
     "execution_count": 65,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# my goal: the function will take a list of integers, and will return the largest integer in that list\n",
    "# my plan: - grab the first integer in the list, and declare it the largest\n",
    "#          - go through each of the next integers. If any is larger than \"largest\", declare it the largest\n",
    "#          - when we're done going through the numbers, \"largest\" will indeed be the largest\n",
    "\n",
    "def mymax(numbers):\n",
    "    largest = numbers[0]            # grab the first value from numbers -- assume that the first is the largest\n",
    "\n",
    "    for one_number in numbers[ 1: ]:  # iterate over every value in numbers but the first\n",
    "        if one_number > largest:\n",
    "            largest = one_number\n",
    "\n",
    "    return largest\n",
    "\n",
    "#      [0]  [1:          ]\n",
    "mymax([10, 15, -3, 28, 17]) "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4555b075-b334-454e-8d2a-25bacff6e3e4",
   "metadata": {},
   "source": [
    "# Expression vs. statement\n",
    "\n",
    "In programming languages, we have two kinds of commands:\n",
    "\n",
    "- expressions -- which return values -- examples are len(), input(), +, -\n",
    "- statements -- which do things, but don't return values -- examples -- for, while, if\n",
    "\n",
    "Why would we want statements? Because they do things. We don't expect to put them on the right side of `=` (assignment). Not only will that not work, but there's no value there.  What would it mean to say\n",
    "\n",
    "    x = for i in range(3)\n",
    "\n",
    "That's meaningless in Python, and thus not allowed.\n",
    "\n",
    "In Python, every function call is an expression. (Some languages have \"procedures\" which don't return values. In Python, all functions return values, and thus all are expressions. However, the returned value might be useless.)\n",
    "\n",
    "`print` is a function that we don't invoke because we want to get a value back. We invoke it because we want it to do something -- namely, display something on the screen.  The actual value it returns, if it returns a value, is irrelevant.\n",
    "\n",
    "It turns out that because `print` is a function, it has to be an expression, and has to return a value. However, it returns a useless value of `None`.  We are invoking it for its *side effect*, for what it does on the screen, not for the value we'll get back."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "16fe3256-c066-413e-a89c-a9b4296bf486",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "70715617-b4ce-43e7-90b4-52fa5b74ab7e",
   "metadata": {},
   "source": [
    "# Next up\n",
    "\n",
    "1. Complex return values and unpacking\n",
    "2. Default argument values"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32b5feee-019a-4735-9d65-71bfd728af03",
   "metadata": {},
   "source": [
    "# Complex return values and unpacking\n",
    "\n",
    "We've seen two different things, this week and in previous weeks:\n",
    "\n",
    "1. A function can return any value we want, of any Python type\n",
    "2. If we have an iterable (string, list, tuple) on the right side of assignment, we can assign its elements to multiple variables with \"unpacking\"\n",
    "\n",
    "Example/reminder of unpacking:\n",
    "\n",
    "    mylist = [10, 20, 30]\n",
    "    x,y,z = mylist    # x becomes 10, y becomes 20, z becomes 30\n",
    "\n",
    "Can we combine these two ideas? Answer: Yes!\n",
    "\n",
    "If we return an iterable value, and especially a tuple, from our function, then we can grab the tuple's elements via unpacking into multiple variables."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 67,
   "id": "bae8f38b-38a0-4506-a05b-d75ffac1e0c2",
   "metadata": {},
   "outputs": [],
   "source": [
    "def square(n):\n",
    "    return [n, n**2]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 68,
   "id": "fe5b8408-629f-4192-8912-74cda18317aa",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[5, 25]"
      ]
     },
     "execution_count": 68,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "square(5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 72,
   "id": "fa1b5c62-a1f5-4152-b7b2-975447b24e31",
   "metadata": {},
   "outputs": [],
   "source": [
    "# when we call square(5), we get back the list [5, 25].  Python \n",
    "# sees that on the right, it sees two variables on the left, and\n",
    "# uses unpacking to assign to both of them\n",
    "\n",
    "n, n_squared = square(5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 70,
   "id": "ed0bb5a3-6610-4c26-900e-22451486ee69",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5"
      ]
     },
     "execution_count": 70,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 71,
   "id": "2d497de5-2b1c-46a8-b066-7a66f388fb37",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "25"
      ]
     },
     "execution_count": 71,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n_squared"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 73,
   "id": "15ade289-f268-47ee-90b8-1ec2d67fce0f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(5, 25)"
      ]
     },
     "execution_count": 73,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# what if I want to return a tuple from a function?\n",
    "\n",
    "def square(n):\n",
    "    return (n, n**2)  # here, I return a tuple\n",
    "\n",
    "square(5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 74,
   "id": "ff64c7fb-8df2-4f19-870e-95ff85eb7375",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(5, 25)"
      ]
     },
     "execution_count": 74,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# we don't actually need the parentheses for a tuple -- the comma is sufficient\n",
    "\n",
    "def square(n):\n",
    "    return n, n**2  # here, I also return a tuple\n",
    "\n",
    "square(5)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c48482a9-e337-4fae-9f21-58e7b88b94db",
   "metadata": {},
   "source": [
    "# Exercise: Vowels, digits, and others (unpacking edition)\n",
    "\n",
    "1. Write a function that takes a string as an argument\n",
    "2. The function will go through the string and count how many vowels, digits, and others are in it.\n",
    "3. Each of these counts will be tracked in a separate variable -- `vowels`, `digits`, and `others`\n",
    "4. The function will return a tuple of three values -- `vowels`, `digits`, and `others`.\n",
    "5. Invoke the function with a string, and grab (with unpacking) the three return values into three variables.\n",
    "6. Print the variables.\n",
    "\n",
    "Example:\n",
    "```python\n",
    "v,d,o = categorize_characters('hello! 123')\n",
    "print(v)  # should be 2\n",
    "print(d)  # should be 3\n",
    "print(o)  # should be 5\n",
    "\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 75,
   "id": "6b1cce30-ea32-43d8-ba77-65ee9f66f1ba",
   "metadata": {},
   "outputs": [],
   "source": [
    "def categorize_characters(s):\n",
    "    vowels = 0\n",
    "    digits = 0\n",
    "    others = 0\n",
    "\n",
    "    for one_character in s:\n",
    "        if one_character.isdigit():\n",
    "            digits += 1\n",
    "        elif one_character in 'aeiou':\n",
    "            vowels += 1\n",
    "        else:\n",
    "            others += 1\n",
    "\n",
    "    return vowels, digits, others   # returning a tuple of three elements "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 77,
   "id": "6cdea310-7a6b-4c45-8a96-49617c7953a3",
   "metadata": {},
   "outputs": [],
   "source": [
    "v,d,o = categorize_characters('hello! 123')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 78,
   "id": "2694fd4c-5a72-467f-a07b-12c345e9ed4c",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "vowels = 2\n",
      "digits = 3\n",
      "others = 5\n"
     ]
    }
   ],
   "source": [
    "print(f'vowels = {v}')\n",
    "print(f'digits = {d}')\n",
    "print(f'others = {o}')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e8f82a73-792c-4b18-bc09-5f1f3af92522",
   "metadata": {},
   "outputs": [],
   "source": [
    "# AK\n",
    "\n",
    "def categorize_characters(mystring):\n",
    "    counts = [0, 0, 0]\n",
    "    for one_character in mystring:\n",
    "        if one_character.lower() in 'aeiou':\n",
    "            counts[0] += 1\n",
    "        elif one_character.isdigit():\n",
    "            counts[1] += 1\n",
    "        else:\n",
    "            counts[2] += 1  # add 1 to the score of even numbers\n",
    "    return counts"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4f46397f-27c2-4fae-970a-f1493d638df9",
   "metadata": {},
   "source": [
    "# Documenting functions\n",
    "\n",
    "How can we know:\n",
    "\n",
    "- What a function expects when we call it? (The number and type of arguments)\n",
    "- What a function will do to our data when we call it?\n",
    "- What a function will return to us?\n",
    "\n",
    "The way that we tell others about our function, and how we learn about other people's functions, is with a \"docstring.\" When we define our function, if the first line of the function body is a string, then that string is considered a docstring -- something that documents the function, but doesn't affect its execution.\n",
    "\n",
    "We can then read that documentation in a variety of ways."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 80,
   "id": "814f1fed-d447-46b6-bab9-1dd92224d38a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# rewrite with a docstring\n",
    "\n",
    "# comments are for program maintainers\n",
    "# docstrings are for program *users*\n",
    "\n",
    "def categorize_characters(s):\n",
    "    '''categorize_characters returns a count of the vowels, digits, and others in a string.\n",
    "\n",
    "    Expects: One string argument\n",
    "    Modifies: -\n",
    "    Returns: A tuple of three integers -- the number of vowels, digits, and others in the input string\n",
    "    '''\n",
    "    vowels = 0\n",
    "    digits = 0\n",
    "    others = 0\n",
    "\n",
    "    for one_character in s:\n",
    "        if one_character.isdigit():\n",
    "            digits += 1\n",
    "        elif one_character in 'aeiou':\n",
    "            vowels += 1\n",
    "        else:\n",
    "            others += 1\n",
    "\n",
    "    return vowels, digits, others   # returning a tuple of three elements "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 81,
   "id": "14978132-6014-46ad-9e6e-fe0d9caad00e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function categorize_characters in module __main__:\n",
      "\n",
      "categorize_characters(s)\n",
      "    categorize_characters returns a count of the vowels, digits, and others in a string.\n",
      "    \n",
      "    Expects: One string argument\n",
      "    Modifies: -\n",
      "    Returns: A tuple of three integers -- the number of vowels, digits, and others in the input string\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(categorize_characters)  # call help, passing the name of a function"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3bc2d8e5-a563-4552-80ea-ec5620b04d2c",
   "metadata": {},
   "source": [
    "# Default argument values\n",
    "\n",
    "We've now seen that we can define functions with different numbers of parameters. If a function has 3 parameters, we need to call it with 3 arguments. \n",
    "\n",
    "We've also seen some examples of functions (and methods) that have optional arguments. How does that work?\n",
    "\n",
    "Example: We can call the `str.split()` method with an argument (the text that should divide our characters) or without an argument (in which case it uses any/all whitespace characters). How did they do that?\n",
    "\n",
    "The answer: You can define a function with a parameter that has a default argument value. That is, if we call the function and no argument is there to pass to the parameter, the parameter can use its default value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 82,
   "id": "c3293bb0-c451-4d53-b72b-2f43353e8676",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "7"
      ]
     },
     "execution_count": 82,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# example:\n",
    "\n",
    "def add(x, y):\n",
    "    return x + y\n",
    "\n",
    "add(2, 5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 83,
   "id": "13c1c115-09ea-4279-94d3-280acddec482",
   "metadata": {},
   "outputs": [
    {
     "ename": "TypeError",
     "evalue": "add() missing 1 required positional argument: 'y'",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mTypeError\u001b[0m                                 Traceback (most recent call last)",
      "Cell \u001b[0;32mIn[83], line 3\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[38;5;66;03m# what happens if I call\u001b[39;00m\n\u001b[0;32m----> 3\u001b[0m \u001b[43madd\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;241;43m2\u001b[39;49m\u001b[43m)\u001b[49m  \n",
      "\u001b[0;31mTypeError\u001b[0m: add() missing 1 required positional argument: 'y'"
     ]
    }
   ],
   "source": [
    "# what happens if I call\n",
    "\n",
    "add(2)  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 84,
   "id": "8838d804-ffb8-4c42-8e24-acb583412ec2",
   "metadata": {},
   "outputs": [],
   "source": [
    "# let's rewrite our function!\n",
    "\n",
    "def add(x, y=10):\n",
    "    return x + y"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 85,
   "id": "1799d6e5-63a9-432d-8014-60f04127a952",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5"
      ]
     },
     "execution_count": 85,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# parameters:   x  y\n",
    "# arguments:    2  3\n",
    "\n",
    "add(2, 3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 86,
   "id": "3f1944b5-4cfc-444d-8c73-aa69a9cee1a6",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "12"
      ]
     },
     "execution_count": 86,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# parameters: x   y\n",
    "# arguments:  2   10\n",
    "\n",
    "add(2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c887b0bd-6e65-4eee-a18e-cef1e1554882",
   "metadata": {},
   "source": [
    "# A few remarks about default argument values\n",
    "\n",
    "1. Just as when we call a function, all positional arguments must come before all keyword arguments, when we define a function, all mandatory parameters (without defaults) must come before all optional arguments (with defaults).\n",
    "2. Never, *ever* use mutable default values, such as lists or dicts. Python won't stop you, but it's a bad idea.\n",
    "3. The defaults are only used if/when too few arguments are passed to the function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 87,
   "id": "9d675fdc-5345-43e1-9730-7c1473963ab5",
   "metadata": {},
   "outputs": [],
   "source": [
    "def hello(name='you'):\n",
    "    return f'Hello, {name}!'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 88,
   "id": "aaa7bfa1-ac19-4c7d-89bc-36a16d2a21fd",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Hello, you!'"
      ]
     },
     "execution_count": 88,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hello()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 89,
   "id": "0cb976f5-0b97-4c3d-95c7-f201be4e36e4",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Hello, world!'"
      ]
     },
     "execution_count": 89,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hello('world')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 90,
   "id": "9f04381d-3357-4ffd-9b1f-38ceb7b8dedc",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Hello, Reuven!'"
      ]
     },
     "execution_count": 90,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hello('Reuven')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "57a0d381-4922-463e-b6af-d364b7a0731d",
   "metadata": {},
   "source": [
    "# Exercise: Count characters\n",
    "\n",
    "1. Define a function, `count_characters`, that takes a string as an argument and returns a dict as a return value.\n",
    "2. The return value's keys will be characters, and the values will be the number of times each character appeared in the string.\n",
    "3. By default, we'll only count vowels (a, e, i, o, and u). However, by passing a string to a second, optional argument, we can count other characters instead.\n",
    "\n",
    "Examples:\n",
    "\n",
    "    count_characters('hello out there!')         # returns {'a':0, 'e':e, 'i':0, 'o':2, 'u':1}\n",
    "    count_characters('hello out there!', 'abc')  # returns {'a':0, 'b':0, 'c':0}\n",
    "    count_characters('hello out there!', '.!?')  # returns {'.':0, '!':1, '?':0}\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 91,
   "id": "81a1e543-e53d-45fe-b360-1e8a02c8b827",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'a': 15, 'b': 6}"
      ]
     },
     "execution_count": 91,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# you don't append to a dict -- you just assign to a key-value pair\n",
    "\n",
    "d = {}\n",
    "d['a'] = 5\n",
    "d['b'] = 6\n",
    "d['a'] += 10  # add 10 to whatever was there before\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 94,
   "id": "c32fc474-c149-42cb-b672-7e5fee9bb208",
   "metadata": {},
   "outputs": [],
   "source": [
    "def count_characters(s, chars_to_count='aeiou'):\n",
    "\n",
    "    # set up a dict for counting\n",
    "    counts = {}\n",
    "    for one_character in chars_to_count:       # here, one_character goes through chars_to_count\n",
    "        counts[one_character] = 0              # use it to seed the dict\n",
    "    \n",
    "    # go through s, and count its characters\n",
    "    for one_character in s:                    # here, use it to count the characters in s\n",
    "        if one_character in counts:            # is the current character a key in counts:\n",
    "            counts[one_character] += 1         # add to the count!\n",
    "\n",
    "    return counts"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 95,
   "id": "8b7740c3-a0a0-4d00-9f9b-eb46b5ad0bbe",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'a': 0, 'e': 3, 'i': 0, 'o': 2, 'u': 1}"
      ]
     },
     "execution_count": 95,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "count_characters('hello out there!')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 96,
   "id": "1c08d498-3ad1-4a52-af63-872f5294df20",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'a': 0, 'b': 0, 'c': 0, 'd': 0, 'e': 3, 'f': 0, 'g': 0, 'h': 2}"
      ]
     },
     "execution_count": 96,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "count_characters('hello out there!', 'abcdefgh')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 97,
   "id": "ce287350-7ec1-4a87-ba93-396ebc5ef5b4",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'!': 1, '.': 0, '?': 0}"
      ]
     },
     "execution_count": 97,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "count_characters('hello out there!', '!.?')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f8605219-ab4d-497c-9132-baa02e85aca9",
   "metadata": {},
   "source": [
    "# Next up\n",
    "\n",
    "1. Locals vs. globals\n",
    "2. Special parameter: `*args`  # \"splat args\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f8c8b6ba-ab39-42ef-bcd9-b12870f11e84",
   "metadata": {},
   "source": [
    "# Local vs. global variables\n",
    "\n",
    "As a general rule, we want anything we do in a function to stay local to that function. Otherwise, things can get chaotic -- we assign to a value in our function, but it modifies a value outside of our function. And that would be very bad.\n",
    "\n",
    "A local variable only exists so long as the function is running.  When the function returns, the local variables all disappear. \n",
    "\n",
    "This means that if two different functions use the variable `x`, then there is no connection whatsoever between their two variables, and there's no chance that we can have any sort of \"namespace collision,\" as it is known.\n",
    "\n",
    "If we can stick to using only local variables, then things are great.\n",
    "\n",
    "However... we can't. We sometimes need to have global variables, which are defined outside of a function.\n",
    "\n",
    "The problems begin when we start to think about the interactions. We know that we cannot read/write local variables from outside of a function.\n",
    "\n",
    "But can we read/write global variables from within a function?\n",
    "\n",
    "The answer is \"yes\" and \"no.\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 98,
   "id": "4527bf43-8eff-4e2e-b508-c44fad78002f",
   "metadata": {},
   "outputs": [],
   "source": [
    "# First rule: When we're in a function, if we assign to a variable,\n",
    "# that variable is now local. \n",
    "\n",
    "def add(x, y):\n",
    "    result = x + y   # result is a local variable!\n",
    "    return result"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 99,
   "id": "7d720e5b-7210-43f5-b9cb-2f9cfcc3816e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "8"
      ]
     },
     "execution_count": 99,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "add(5, 3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 100,
   "id": "9aea89ea-dfd4-476e-84d3-84a43b97ef75",
   "metadata": {},
   "outputs": [
    {
     "ename": "NameError",
     "evalue": "name 'result' is not defined",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mNameError\u001b[0m                                 Traceback (most recent call last)",
      "Cell \u001b[0;32mIn[100], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m \u001b[43mresult\u001b[49m\n",
      "\u001b[0;31mNameError\u001b[0m: name 'result' is not defined"
     ]
    }
   ],
   "source": [
    "result"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 101,
   "id": "e4b0dee5-1e19-474f-a222-673864530e4b",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Second rule: Parameters are all local variables, and they have their\n",
    "# values assigned to them when the function is called"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 102,
   "id": "f9e0f0c3-28d6-4714-ae50-fb49cc919ebf",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Before, x = 100\n",
      "In myfunc, x = 100\n",
      "After, x = 100\n"
     ]
    }
   ],
   "source": [
    "# Third rule: When we ask for a variable's value in a function, Python first\n",
    "# looks for a local variable by that name. If it find it, great -- we're done.\n",
    "# If not, then it looks for a global variable of that name.\n",
    "\n",
    "# we can have two variables of the same name at the same time, one local\n",
    "# and one global. The local will always take priority.\n",
    "\n",
    "x = 100    # global variable\n",
    "\n",
    "def myfunc():\n",
    "    print(f'In myfunc, x = {x}')  # is there a local x? no... is there a global x? yes, it's 100\n",
    "\n",
    "print(f'Before, x = {x}')   # we only know about globals here, so x = 100\n",
    "myfunc()\n",
    "print(f'After, x = {x}')    # once again, x is 100\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 103,
   "id": "b501c2df-8c28-49d3-8ed6-f8ea97a58b27",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Before, x = 100\n",
      "In myfunc, x = 200\n",
      "After, x = 100\n"
     ]
    }
   ],
   "source": [
    "# slight variation...\n",
    "\n",
    "x = 100    # global variable\n",
    "\n",
    "def myfunc():\n",
    "    x = 200                      # this creates a local variable named x\n",
    "    print(f'In myfunc, x = {x}')  # is there a local x? Yes, with a value 200\n",
    "\n",
    "print(f'Before, x = {x}')   # we only know about globals here, so x = 100\n",
    "myfunc()\n",
    "print(f'After, x = {x}')    # once again, x is 100\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d8950cdd-4c40-496b-97f0-6182f00f677c",
   "metadata": {},
   "source": [
    "# `*args` - a special kind of parameter\n",
    "\n",
    "What if you want your function to take any number of positional arguments? That is, you don't want to take a list as one argument, containaing an unknown number of elements. Rather, you want to get all of those values as arguments, directly.\n",
    "\n",
    "Right now, we don't have a good way to do that. If you know how many arguments you'll get, you can define a function with that many parameters. If you don't know, but can guess close to that number, you can define parameters with default argument values for where there might not be any.\n",
    "\n",
    "But `*args` is there to solve this problem in an elegant way.\n",
    "\n",
    "`*args` is a special parameter that will always be a tuple, and will always contain the values of positional arguments that no other parameter got."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 104,
   "id": "cdc2b7ce-0fdb-4ff7-959b-cb3bfff1b043",
   "metadata": {},
   "outputs": [],
   "source": [
    "def myfunc(a, *args):             # *args is in the variable declaration, not elsewhere!\n",
    "    print(f'a={a}, args={args}')  # print values of a and args"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 105,
   "id": "e992da65-05d6-45cb-a417-753f8688760c",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "a=10, args=()\n"
     ]
    }
   ],
   "source": [
    "myfunc(10)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 106,
   "id": "d78fe0b6-a67a-494c-8eae-62c5f356e8ce",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "a=10, args=(20, 30, 40, 50)\n"
     ]
    }
   ],
   "source": [
    "myfunc(10, 20, 30, 40, 50)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 107,
   "id": "be68d660-e9e0-4dbc-bbea-79ffdc6e4af6",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "60"
      ]
     },
     "execution_count": 107,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# generally speaking, if we use *args, we should not be retrieving from its index [0], [1], etc.\n",
    "# rather, we should be iterating over it, and doing the same thing with each value.\n",
    "\n",
    "# earlier, we saw that we can write mysum:\n",
    "\n",
    "def mysum(numbers):   # takes a list of numbers\n",
    "    total = 0 \n",
    "\n",
    "    for one_number in numbers:\n",
    "        total += one_number\n",
    "\n",
    "    return total\n",
    "\n",
    "mysum([10, 20, 30])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 108,
   "id": "215d257d-b2db-4661-8b2b-8020faff0316",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "60"
      ]
     },
     "execution_count": 108,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# I can change this function to take any number of arguments, rather than a list\n",
    "\n",
    "def mysum(*numbers):   # now numbers will be a tuple, containing all arguments passed to mysum\n",
    "    total = 0 \n",
    "\n",
    "    for one_number in numbers:\n",
    "        total += one_number\n",
    "\n",
    "    return total\n",
    "\n",
    "mysum(10, 20, 30)  # now, don't pass a list -- pass integers as arguments"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 109,
   "id": "a209b67c-4d64-4e13-81c0-05cd85e456a6",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "a b c d\n"
     ]
    }
   ],
   "source": [
    "# here's an example of a function that takes *args:\n",
    "\n",
    "print('a', 'b', 'c', 'd')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 110,
   "id": "d59e5599-209e-481f-9e2f-8020d3816793",
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on built-in function print in module builtins:\n",
      "\n",
      "print(*args, sep=' ', end='\\n', file=None, flush=False)\n",
      "    Prints the values to a stream, or to sys.stdout by default.\n",
      "    \n",
      "    sep\n",
      "      string inserted between values, default a space.\n",
      "    end\n",
      "      string appended after the last value, default a newline.\n",
      "    file\n",
      "      a file-like object (stream); defaults to the current sys.stdout.\n",
      "    flush\n",
      "      whether to forcibly flush the stream.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(print)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e4b5c2bf-61c0-48b0-bcb7-f3b8d199c7a6",
   "metadata": {},
   "source": [
    "# For next time: Python function challenge\n",
    "\n",
    "Link is here: https://learning.oreilly.com/scenarios/python-skills-challenge/9781098109752"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "632dcccf-584f-48fc-b59e-67c2ab600406",
   "metadata": {},
   "source": [
    "# Look for my talk from PyCon US from 2020, \"Function dissection lab\":\n",
    "\n",
    "This is more complex than we've done here.\n",
    "\n",
    "https://www.youtube.com/watch?v=QR9W81P7yTw"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9cc80a36-48f8-452b-8a8a-fd58437b2198",
   "metadata": {},
   "source": [
    "# Next time (our last time, alas!) Modules and packages\n",
    "\n",
    "- How can we use prepackaged libraries in Python?\n",
    "- What comes with Python's standard library?\n",
    "- What is PyPI, and how do we install things from it?\n",
    "- Can we write our own modules to reuse code?\n",
    "- Where do we go next? "
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.11.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}