Week_2/Python_Basics_14_-_Functions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a href='https://www.learntocodeonline.com/'><img src=\"../IMGs/learn-to-code-online.png\"></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# What Is A Function?\n",
    "\n",
    "Functions are a block of organized, **reusable** code used to perform a single, related action. It provides for better modularity & a higher degree of code reuse.\n",
    "\n",
    "I touch more on this in my presentation \"[How To Think Like A Programmer](https://www.linkedin.com/feed/update/urn:li:activity:6475399796298444800)\" (Dec 2018).\n",
    "\n",
    "Some functions are built into python and it's data objects, while others are user-defined.\n",
    "\n",
    "They are always called by something, for example but not limited to:\n",
    "- another method or function\n",
    "- variable"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# How Do You [Define A Function](https://docs.python.org/3/tutorial/controlflow.html#defining-functions)?\n",
    "\n",
    "Here is an example (pseudo-code):\n",
    "\n",
    "```python\n",
    "def function_name():\n",
    "    \"\"\"function docstring\"\"\"\n",
    "    # function suite\n",
    "    return [expression, ...]\n",
    "```\n",
    "\n",
    "Each function is made up of 5 parts."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "1. **The _def_ line**\n",
    "\n",
    "This line starts with the **def** or define keyword followed by the name of the function and a set of parenthesis.\n",
    "\n",
    "2. **Optional Input Parameters**\n",
    "\n",
    "Depending on the requirements of your function, you may have input parameters with which may be needed to complete the function's design. There may be 0 or more input parameters that you can force or make optional."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "3. **Docstring**\n",
    "\n",
    "There are many suggested ways to do documentation ...\n",
    "\n",
    "- [PEP 257](https://www.python.org/dev/peps/pep-0257/) from Python Developer's Guide\n",
    "\n",
    "- Geeks For Geeks on [docstring](https://www.geeksforgeeks.org/python-docstrings/)\n",
    "\n",
    "- Python For Beginners on [docstring](https://www.pythonforbeginners.com/basics/python-docstrings)\n",
    "\n",
    "- Hitchhiker's Guide to Python on [docstring](https://docs.python-guide.org/writing/documentation/)\n",
    "\n",
    "- RealPython's [Complete Guide To Python Documentation](https://realpython.com/documenting-python-code/)\n",
    "\n",
    "... and some work well with modules that created an outprint of said documentation!\n",
    "\n",
    "But at the bare minimum, at least explain:\n",
    "- what the function does\n",
    "- how the input variables are used\n",
    "- if it returns something, what?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "4. **The Suite**\n",
    "\n",
    "**Suites** are a group of individual statements that make up code blocks. \n",
    "(Blocks of code that do something - which do not have to be a function.)\n",
    "\n",
    "This starts after the `:` and (unless it's a single line function) is indented on a new line by 4 spaces. This is the piece of code that actually does the computations/changes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "5. **The Return**\n",
    "\n",
    "If you never utilize the `return` statement to send data back, then if you attempt to call the function and store it in a variable? You would get back `None` as the data.\n",
    "\n",
    "<div class=\"alert alert-success\">\n",
    "<b>Try this!</b>\n",
    "\n",
    "```python\n",
    "def temp_func():\n",
    "    \"\"\"\n",
    "    This function prints a statement explanation.\n",
    "    \n",
    "    \"\"\"\n",
    "    \n",
    "    print('This \"returns\" None. Even if you used \"return\" or \"return None\"')\n",
    "\n",
    "temp_data = temp_func()\n",
    "print('temp_data (type: {}):  {}'.format(type(temp_data), temp_data))\n",
    "```\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The **return** statement exits the function & can optionally pass back data.\n",
    "\n",
    "`return` (without anything after it) is the same as `return None`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Arguments:  Pass By Reference vs Value\n",
    "\n",
    "When defining a function, all parameters (aka arguments) are passed by reference. Meaning the function has a local scope variable that refers to that piece of data. But this can be very dangerous, if not also confusing.\n",
    "\n",
    "_**REMEMBER:**  a variable is simply a label that points to a particular piece in your computer's memory that holds some data set._\n",
    "\n",
    "That's why I really like the explanation given [here](https://jeffknupp.com/blog/2012/11/13/is-python-callbyvalue-or-callbyreference-neither/) from Jeff Knup.\n",
    "\n",
    "Python is really more **pass by object**.\n",
    "\n",
    "Running code like this for example:\n",
    "\n",
    "<div class=\"alert alert-success\">\n",
    "\n",
    "```python\n",
    "def foo(bar):\n",
    "    \"\"\"Appends 42 to list\"\"\"\n",
    "    bar.append(42)\n",
    "    print(bar)\n",
    "    # >> [42]\n",
    "\n",
    "numr_list = []\n",
    "foo(numr_list)\n",
    "print(numr_list)\n",
    "# >> [42]\n",
    "```\n",
    "</div>\n",
    "\n",
    "... you would have a change to the original piece of data. And this generally causes unintended and unanticipated (potentially disastrous) results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Whereas running code like this for example:\n",
    "\n",
    "```python\n",
    "def foo(bar):\n",
    "    \"\"\"Appends 42 to local list\"\"\"\n",
    "    bar = bar[:] # makes a copy of incoming data\n",
    "    bar.append(42)\n",
    "    print(bar)\n",
    "    # >> [42]\n",
    "\n",
    "numr_list = []\n",
    "foo(numr_list)\n",
    "print(numr_list)\n",
    "# >> []\n",
    "\n",
    "```\n",
    "\n",
    "... the original data would be in tact."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is **highly recommended** that you do not modiy the input objects. If you must:\n",
    "\n",
    "1. Create a new variable that calls the function using input data\n",
    "2. Have function make a local variable with a copy of the original information\n",
    "3. Perform calculations and return to calling variable\n",
    "4. Confirm after conclusion the anticipated results and reassign as needed"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Arguments:  Required Arguments\n",
    "\n",
    "These are the arguments passed to a function that do not have a default value assigned to them.\n",
    "\n",
    "When a function is called, these are the minimum number of inputs that must be included in a particular order.\n",
    "\n",
    "In the following example, would this work?\n",
    "Why or why not?\n",
    "\n",
    "<div class=\"alert alert-success\">\n",
    "\n",
    "```python\n",
    "# function definition\n",
    "def printme(input_value):\n",
    "    \"\"\"Prints a passed string.\"\"\"\n",
    "    print(input_value)\n",
    "\n",
    "# call the function\n",
    "printme()\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Arguments:  Default Arguments\n",
    "\n",
    "If you wish to have a default value (in case it is not included when the function is called) you must specify it within the function definition.\n",
    "\n",
    "<div class=\"alert alert-success\">\n",
    "<b>Try this!</b>\n",
    "\n",
    "```python\n",
    "# function definition\n",
    "def printinfo(name, age=35):\n",
    "    \"\"\"Prints the info passed into the function.\"\"\"\n",
    "    print('Name:  {}'.format(name))\n",
    "    print('Age:  {}'.format(age))\n",
    "\n",
    "# call the function\n",
    "printinfo(age=50, name='Miki')\n",
    "printinfo(name='Minni')\n",
    "```\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Arguments:  Keyword Arguments\n",
    "\n",
    "Similar to required arguments, these arguments are included within the function's definition. The difference is in how the function is called.\n",
    "\n",
    "By using *keywoprd arguments* the order no longer matters. The only thing that matters is that the keywords match the variables in the function definition.\n",
    "\n",
    "<div class=\"alert alert-success\">\n",
    "<b>Try this!</b>\n",
    "\n",
    "```python\n",
    "# function definition\n",
    "def printinfo(name, age):\n",
    "    \"\"\"Prints the info passed into the function.\"\"\"\n",
    "    print('Name:  {}'.format(name))\n",
    "    print('Age:  {}'.format(age))\n",
    "\n",
    "# call the function\n",
    "printinfo(age=50, name='Miki')\n",
    "```\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Arguments:  Variable-Length Args\n",
    "\n",
    "This is not something suggested to use, as there is no way to confirm correct code with tools. It is, however, an option.\n",
    "\n",
    "Here is the pseudo code for structure:\n",
    "\n",
    "```python\n",
    "def functionname([formal_args,], *args):\n",
    "    \"\"\"function docstring\"\"\"\n",
    "    funciton_suite\n",
    "    return [expression, ...]\n",
    "```\n",
    "\n",
    "This is used when you need to process a function for more arguments than specified while defining the function.\n",
    "\n",
    "You may also want to consider downloading the Jupyter Notebook page shown [here](https://github.com/ProsperousHeart/TrainingUsingJupyter/blob/master/Python/Recipes/Data%20Structures%20And%20Algorithms%2000%20-%20Unpacking%20And%20Deque.ipynb) as well to understand a little bit about star unpacking...\n",
    "\n",
    "Or even [this](https://www.geeksforgeeks.org/args-kwargs-python/) well structured explanation from [Geeks For Geeks](https://www.geeksforgeeks.org).\n",
    "\n",
    "<div class=\"alert alert-success\">\n",
    "<b>Try this!</b>\n",
    "\n",
    "```python\n",
    "def printinfo(arg1, *var_tuple):\n",
    "    \"\"\"this prints a variable passed arguments\"\"\"\n",
    "    print('Output is: ')\n",
    "    print(arg1)\n",
    "    for var in var_tuple:\n",
    "        print(var)\n",
    "\n",
    "printinfo(10)\n",
    "printinfo(70, 60, 50)\n",
    "```\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Anonymous Functions\n",
    "\n",
    "These are usually called `lambda` functions - they're not declared like \"normal\" functions.\n",
    "\n",
    "Here's is the pseudo-code structure:\n",
    "```python\n",
    "lambda [arg1 [, arg2, ...]]: expression\n",
    "```\n",
    "\n",
    "- *lambda* keyword is used to distinguish this \"anonymous\" function\n",
    "- takes any number of arguments but only returns 1 response\n",
    "- can be a direct call to print\n",
    "- cannot access variables other than those in parameter list and global namespace\n",
    "\n",
    "You generally only use this when utilizing an in-line parameter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-success\">\n",
    "<b>Try this!</b>\n",
    "\n",
    "```python\n",
    "# \"Define\" your anonymous function\n",
    "# without the () it is waiting to be called\n",
    "sum = lambda arg1, arg2: arg1 + arg2\n",
    "\n",
    "# call your function\n",
    "print(\"Value of total: {}\".format(sum(10, 20)))\n",
    "print(\"Value of total: {}\".format(sum(20, 20)))\n",
    "```\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Return Statement\n",
    "\n",
    "The __return__ statement at the end of a function for all intents and purposes exits a function and returns some kind of data. If nothing is specified, it returns:  `None`\n",
    "\n",
    "<div class=\"alert alert-success\">\n",
    "<b>Try this!</b>\n",
    "\n",
    "```python\n",
    "def sum(arg1, arg2):\n",
    "    \"\"\"Add 2 parameters and return the calculation.\"\"\"\n",
    "    total = arg1 + arg2\n",
    "    print('Inside the function:  {}'.format(total))\n",
    "    return total\n",
    "\n",
    "total = sum(10, 20)\n",
    "print('Outside the function:  {}'.format(total))\n",
    "```\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Additional Resources\n",
    "\n",
    "Here are some additional links for your benefit:\n",
    "- Geeks For Geeks:  [lambda, filter, map, reduce](https://www.geeksforgeeks.org/python-lambda-anonymous-functions-filter-map-reduce/)\n",
    "- Dan Bader's [\"What Are Lambda Functions Good For?\"](https://dbader.org/blog/python-lambda-functions)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}