07_functions_keyword_args.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "## Functions II: Advanced Topics\n",
    "\n",
    "In the previous lessons, we learned how to call a range of functions with simple numeric and string arguments. Now, we will learn how to call more complex functions with a wide range of arguments. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "init_cell": true
   },
   "outputs": [],
   "source": [
    "def print_message_n_times(msg, n):\n",
    "    \"\"\"This function prints a message to the screen n times \n",
    "    \n",
    "    Arguments:\n",
    "    msg -- the message to print\n",
    "    n -- the number of times to print the message\n",
    "    \n",
    "    Example - to print the message \"victory\" 5 times:\n",
    "    print_message_n_times(\"victory\", 5)\n",
    "    \"\"\"\n",
    "    for i in range(n):\n",
    "        print(msg)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "init_cell": true
   },
   "outputs": [],
   "source": [
    "def display_account_balance(customer_name, account_balance):\n",
    "    \"\"\"This function sends a customer a message containing their account balance \n",
    "    \n",
    "    Arguments:\n",
    "    customer_name -- the customer to notify\n",
    "    account_balance -- their current account balance\n",
    "    \n",
    "    Example - to display an account balance of 10.00 for the customer \"john\":\n",
    "    display_account_balance(\"john\", 10.00)\n",
    "    \"\"\"\n",
    "    print(f\"Hello {customer_name}, your account balance is: ${account_balance}\")  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "init_cell": true
   },
   "outputs": [],
   "source": [
    "def introduce_yourself(your_name, other_name):\n",
    "    \"\"\"This function prints a friendly introduction message \n",
    "    \n",
    "    Arguments:\n",
    "    your_name -- your name\n",
    "    other_name -- the name of the person to whom you are introducing yourself\n",
    "    \n",
    "    Example - to introduce yourself as \"angela\" to someone named \"elisa\":\n",
    "    introduce_yourself(\"angela\", \"elisa\")\n",
    "    \"\"\"\n",
    "\n",
    "    print(f\"Hello, {other_name}, my name is {your_name}. Nice to meet you.\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "init_cell": true
   },
   "outputs": [],
   "source": [
    "def introduce_yourself_without_mistakes(**kwargs):\n",
    "    \"\"\"This function prints a friendly introduction message without mistakes \n",
    "    \n",
    "    Keyword Arguments:\n",
    "    your_name -- your name\n",
    "    other_name -- the name of the person to whom you are introducing yourself\n",
    "    \n",
    "    Example - to introduce yourself as \"alexa\" to someone named \"georgia\":\n",
    "    introduce_yourself(your_name=\"alexa\", other_name=\"georgia\")\n",
    "    \"\"\"\n",
    "    other_name = kwargs['other_name']\n",
    "    your_name = kwargs['your_name']\n",
    "    print(f\"Hello, {other_name}, my name is {your_name}. I'm glad I didn't mix up the order of my arguments.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "### Functions with Mixed-Type Arguments\n",
    "\n",
    "As an example for you to learn from, we have created a function called `print_message_n_times`. You can see how this function is called below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "this is a message\n",
      "this is a message\n",
      "this is a message\n"
     ]
    }
   ],
   "source": [
    "print_message_n_times(\"this is a message\", 3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "As you can see, in order to call the function `print_message_n_times`, one must provide two arguments: the message to print (in this case, `\"this is a message\"`) and the number of times to print it (in this case, `3` times.)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "<span style=\"color:blue;font-weight:bold\">Exercise</span>: Call the function `print_message_n_times` with these two arguments: `\"a different message\"` and `4`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "tags": [
     "exercise"
    ]
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "a different message\n",
      "a different message\n",
      "a different message\n",
      "a different message\n"
     ]
    }
   ],
   "source": [
    "print_message_n_times(\"a different message\", 4)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "deletable": false,
    "editable": false,
    "strategicml": {
     "execution_time": 1584758649490,
     "exercise_id": "aa277bce-4ba7-4d2e-8320-2d1d9ec57ffc",
     "points": 2
    },
    "tags": [
     "test"
    ]
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"background-color:#e8fcef\n",
       ";color:#333333;padding:10px;border-style:solid;border-width:2px;border-color:#038c33\">\n",
       "<div style=\"font-weight:bold\">Correct!</div>\n",
       "</div>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "hint = \"Did you call the <code>print_message_n_times</code> function with the arguments <code>\\\"a different message\\\"</code> and <code>4</code> appropriately placed between a pair of parentheses <code>()</code>?\"\n",
    "assert get_sanitized_input() == 'print_message_n_times(\"a different message\", 4)', hint\n",
    "success()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "### What Arguments Does This Function Require?\n",
    "\n",
    "You may ask: how would I know what arguments a given function requires without an example like the one provided above? The answer is that you can view the usage information for a function by typing its name followed by a `?`, as shown below (make sure that you execute the cell with `Shift-Enter`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "print_message_n_times?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "You should see a message like the following pop up on your screen:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "![](./img/docstring.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "The first line, which begins with `Signature`, shows you how many arguments you must pass to the function. In this case, the function expects two arguments, `msg` and `n`. The second line, beginning with `Docstring:`, explains in further detail what the function does, what its arguments are, and how to call it correctly. You should get in the habit of checking this usage information for a function before using it in your code. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "To close this message, click the `X` at the top right-hand corner of the message."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "<span style=\"color:blue;font-weight:bold\">Exercise</span>: Use the `?` syntax discussed above to display the usage information for the function `display_account_balance`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "tags": [
     "exercise"
    ]
   },
   "outputs": [],
   "source": [
    "?display_account_balance"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "deletable": false,
    "editable": false,
    "strategicml": {
     "execution_time": 1584758662350,
     "exercise_id": "44514bb6-68c8-48a6-be7e-d0cd7f3dff82",
     "points": 2
    },
    "tags": [
     "test"
    ]
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"background-color:#e8fcef\n",
       ";color:#333333;padding:10px;border-style:solid;border-width:2px;border-color:#038c33\">\n",
       "<div style=\"font-weight:bold\">Correct!</div>\n",
       "</div>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "hint = \"Did you type the input <code>display_account_balance?</code> in order to view the usage information for the function <code>display_account_balance</code>?\"\n",
    "assert get_sanitized_input() == \"get_ipython().run_line_magic('pinfo', 'display_account_balance')\", hint\n",
    "success()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "### Keyword Arguments\n",
    "\n",
    "Sometimes, function calls with multiple arguments can get confusing. For example, take a look at the documentation for the function `introduce_yourself` by running the cell below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "introduce_yourself?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "This function seems quite easy to use - for example, we can introduce ourselves to `\"David\"` and let him know that our name is `\"Arthur\"`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello, Arthur, my name is David. Nice to meet you.\n"
     ]
    }
   ],
   "source": [
    "introduce_yourself(\"David\", \"Arthur\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "But what if we forget the correct order for these two arguments? In that case, we may very awkwardly introduce ourselves by the wrong name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello, David, my name is Arthur. Nice to meet you.\n"
     ]
    }
   ],
   "source": [
    "introduce_yourself(\"Arthur\", \"David\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "To avoid this and many other awkward experiences that can result from mixing up the order of arguments, Python provides a feature called *keyword arguments*. We'll show you keyword arguments work by using the new function `introduce_yourself_without_mistakes` as an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello, David, my name is Arthur. I'm glad I didn't mix up the order of my arguments.\n"
     ]
    }
   ],
   "source": [
    "introduce_yourself_without_mistakes(your_name=\"Arthur\", other_name=\"David\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "Notice that the line above uses *keyword arguments* because it specifies the *name* of each argument, rather than just its position. We can learn more about keyword arguments by looking at the documentation of this function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "introduce_yourself_without_mistakes?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "Notice the string `**kwargs` in the `Signature` of the message above:\n",
    "\n",
    "```\n",
    "Signature: introduce_yourself_without_mistakes(**kwargs)\n",
    "```\n",
    "\n",
    "This indicates that this function supports keyword arguments. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "Keyword arguments are extremely valuable because they remove the need to remember the appropriate order for our arguments - for example, even if we swap the order of our keyword arguments, the above call to `introduce_yourself_without_mistakes` will still work correctly."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "<span style=\"color:blue;font-weight:bold\">Exercise</span>: Verify for yourself that keyword arguments allow our function to still work when the order of the arguments is changed. Call the function `introduce_yourself_without_mistakes`, with the first keyword argument `other_name` set to the value `\"David\"` and the second keyword argument `your_name` set to the value `\"Arthur\"` - notice that this is the reverse order compared to the previous example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "tags": [
     "exercise"
    ]
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello, David, my name is Arthur. I'm glad I didn't mix up the order of my arguments.\n"
     ]
    }
   ],
   "source": [
    "introduce_yourself_without_mistakes(other_name=\"David\", your_name=\"Arthur\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "deletable": false,
    "editable": false,
    "strategicml": {
     "execution_time": 1584758713517,
     "exercise_id": "6f04045b-63c8-4cc2-9163-eee045065fc1",
     "points": 2
    },
    "tags": [
     "test"
    ]
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"background-color:#e8fcef\n",
       ";color:#333333;padding:10px;border-style:solid;border-width:2px;border-color:#038c33\">\n",
       "<div style=\"font-weight:bold\">Correct!</div>\n",
       "</div>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import re\n",
    "result = get_sanitized_input()\n",
    "correct_result = \"introduce_yourself_without_mistakes(other_name=\\\"David\\\",your_name=\\\"Arthur\\\")\"\n",
    "hint = \"Did you call the function <code>introduce_yourself_without_mistakes</code> with the keyword arguments <code>other_name=\\\"David\\\"</code> and <code>your_name=\\\"Arthur\\\"</code>?\"\n",
    "assert re.sub(\"\\s+\", \"\", result) == correct_result, hint\n",
    "success()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "source": [
    "We will use keyword arguments extensively later in this course as we begin to work with more complex functions."
   ]
  }
 ],
 "metadata": {
  "celltoolbar": null,
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  },
  "strategicml": {
   "lesson_id": "2fade2e8-1243-4527-9669-34ae3c451c07",
   "release": true
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}