chapter04_functions/sec01_functions_basics.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Functions\n",
    "\n",
    "We have already encountered a variety of functions.\n",
    "These include both stand-alone functions such as `print`\n",
    "`len`, `sorted`, `ceil`, `floor`, and `round`,\n",
    "and methods (functions associated with specific objects)\n",
    "such as the `.upper()` and `.lower()` methods \n",
    "that we invoked when manipulating strings.\n",
    "\n",
    "In fact, it's hard to imagine doing anything \n",
    "useful in Python without invoking at least one function.\n",
    "For the majority of people, their very first program \n",
    "consists of the one line `print(\"Hello world!\")`. \n",
    "\n",
    "Until now we've been using functions \n",
    "without concerning ourselves with what precisely they *are*.\n",
    "In this notebook, we'll finally get into the nuts and bolts\n",
    "but defining our own functions. \n",
    "\n",
    "Each function is introduced using the word `def <function_name>():`\n",
    "followed by a code block (indented just as \n",
    "with the bodies of loops and conditionals).\n",
    "To start, we'll introduce a function \n",
    "that takes no inputs and returns no outputs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def greet():\n",
    "    print(\"Hello world\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Invoking a function\n",
    "Now that we have defined the function, \n",
    "we can invoke it from anywhere in our code.\n",
    "Note that the function must be defined (as above)\n",
    "before the line of code that invokes it.\n",
    "The function name itself is now a variable\n",
    "that lives in the name space."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "greet"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And we can invoke the function by using the same \n",
    "parentheses syntax that we have used to invoke \n",
    "other functions that we did not define ourselves:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "greet()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Functions that return values\n",
    "Note that while the greet function takes an action \n",
    "(sending data to be printed to standard out),\n",
    "it does not actually return any value. \n",
    "In other words the expressions `greet()`\n",
    "returns only the default value `None` as seen below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = greet()\n",
    "print(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we want to return a value such that the function call \n",
    "can function syntactically as an expression we can use the return statement."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def greet2():\n",
    "    return \"Hello\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "statement = greet2() + \" friend!\"\n",
    "print(statement)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Making functions useful\n",
    "To make functions actually useful, \n",
    "you will typically want to the body \n",
    "of the function to actually do something.\n",
    "For example, below, we can use conditionals \n",
    "and the time package to write a function \n",
    "that checks the time of day and returns \n",
    "a greeting appropriate to the hour."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import time \n",
    "def timely_greet():\n",
    "    hour = time.localtime()[3]\n",
    "    if (hour > 12) and (hour < 18):\n",
    "        return(\"Good afternoon\")\n",
    "    elif hour >= 18:\n",
    "        return(\"Good evening\")\n",
    "    else:\n",
    "        return \"Good morning\"\n",
    "        \n",
    "    \n",
    "    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Function that take arguments\n",
    "\n",
    "While we can write some useful functions \n",
    "that don't require input from the user,\n",
    "more often we want functions that act \n",
    "in a context-dependent fashion. \n",
    "\n",
    "We accomplish this by passing arguments to the function.\n",
    "To write a function that takes an argument as input,\n",
    "we just put the argument inside the parenthesis\n",
    "when declaring the function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def greet3(name):\n",
    "    print(\"Hello %s!\" % name)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "greet3(\"Caroline\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the argument `name` could have been any variable name. \n",
    "The chocie `name` was appropriate because of the function \n",
    "that it serves in our program, but we could have called it `pickle_rick`\n",
    "and our function would function in the exact same way."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def greet4(pickle_rick):\n",
    "    print(\"Hello %s!\" % pickle_rick)\n",
    "greet4(\"Caroline\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Inside the fuction body, all arguments that were supplied\n",
    "when the functino was invoked are available and accessed \n",
    "by the name that we gave to the function when writing its signature."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Multiple arguments\n",
    "\n",
    "Often we will want functions that act upon \n",
    "multiple inputs to produce some desired output.\n",
    "For example, to calculate the amount of money\n",
    "we expect to have when an investment matures\n",
    "might depend on the principal, the interest rate,\n",
    "and the duration of the investment. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def final_amount(principal, interest, years):\n",
    "    return principal * (1 + interest/100) ** years\n",
    "final_amount(100000, 6, 10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Multiple return values \n",
    "\n",
    "We also often want functions to return multiple values.\n",
    "For example, we can do this by either returning \n",
    "a collection containing or the values, \n",
    "or by invoking `return x, y` which will return them as a tuple."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Default values for arguments\n",
    "Sometimes, especially in machine learning,\n",
    "we will want to have arguments that default\n",
    "to some reasonable value but which can optionally be set.\n",
    "In these cases we can use a signature\n",
    "that looks like `def func(argname=value):`.\n",
    "Say for example that most investments lasted 10 years,\n",
    "and that we wanted our code to assume this unless otherewise stated.\n",
    "Note that default arguments must follow the non-default arguments."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def final_amount2(principal, interest = 0., years=10):\n",
    "    return principal * (1 + interest/100) ** years\n",
    "print(final_amount2(100000, 6))\n",
    "print(final_amount2(100000, 6, 10))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also access a subset of default arguments by name,\n",
    "and you can even access the arguments in a different order."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "final_amount2(100000, years=5, interest=10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that you can access any argument by its name, \n",
    "not just those that have a default value."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Flexible Function Signatures\n",
    "\n",
    "Sometimes we do not know a priori how many arguments \n",
    "our function will be receiving at deployment time.\n",
    "If our function is such that it can handle some \n",
    "arbitrary set of specified arguments (like `print`),\n",
    "we can let this be known by using `*args` and `**kwargs`\n",
    "in the function signature to receive regular arguments\n",
    "and named *keyword arguments*, respectively.\n",
    " * `*args`\n",
    " * `**kwargs`\n",
    " * Nice simple reference: http://book.pythontips.com/en/latest/args_and_kwargs.html"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Example of *args\n",
    "def fn1(*args):\n",
    "    print(\"\\nfn1 output:\")\n",
    "    print(args)\n",
    "\n",
    "def fn2(**kwargs):\n",
    "    print(\"\\nfn2 output:\")\n",
    "    print(kwargs)\n",
    "\n",
    "def fn3(*args, **kwargs):\n",
    "    print(\"\\nfn3 output:\")\n",
    "    print(\"these are the args\", args)\n",
    "    print(\"these are the kwargs\", kwargs)\n",
    "\n",
    "fn1(1,2,3,4,5)    \n",
    "fn2(a=1,b=2,c=3)\n",
    "fn3(1, \"a\", 2, \"b\", 3, \"c\", name1=\"Bob\", name2=\"Margaret\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Anomymous functions\n",
    "One more exotic behavior that you might \n",
    "want to know about at some point \n",
    "is the anonymous functions, which are introduced\n",
    "with `lambda` statements with syntax like \n",
    "`lambda x: statement`.\n",
    "If we just run such an expression we see that \n",
    "it ***is*** a function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lambda x: x ** 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can invoke that function just as we would any function,\n",
    "using the parenthesis syntax."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "(lambda x: x ** 2)(9)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also assign a `lambda` function to a variable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sq = lambda x: x ** 2\n",
    "sq(9)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Python generators\n",
    "Sometimes we want to write a function that can be invoked like a list\n",
    "where it can be called as the argument to a for loop\n",
    "and pass back a value to the caller without losing its state\n",
    "and then pass the next value when the caller asks for it. \n",
    "In these contexts we can use  `yield` (vs `return`)\n",
    "to pass values back ot the caller.\n",
    "\n",
    "In short:\n",
    " * `return` sends a complete value back to caller\n",
    " * `yield` returns an iterable, passes each value back to the caller in sequence, saving enough state to complete the subsequent values when asked for them\n",
    " \n",
    "Here's a simple example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def all_the_numbers():\n",
    "    i = 1\n",
    "    while True:\n",
    "        yield i\n",
    "        i += 1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you uncomment and run the code below, you will find that it will start printing values to screen even though the function itself is an infinite loop and thus would never return!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for ind in all_the_numbers():\n",
    "    print(ind)\n",
    "    if ind > 10:\n",
    "        break"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Docstrings\n",
    "As a final note, you might recall that for most objects \n",
    "and methods that we introspect in Jupyter, we can \n",
    "get a bunch of information about them by \n",
    "checking the data in their `__doc__` attribute. \n",
    "We can populate a function's `__doc__` attribute\n",
    "by placing a docstring directly below the signature.\n",
    "\n",
    "Docstrings are an important because they\n",
    " * Describes behavior of the function so people using your function know what it does.\n",
    " * Can be accessed via __doc__ when introspecting a program\n",
    " * Can be used to programatically generate HTML documentation for your code/library.\n",
    "\n",
    "A simple example of a docstring:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def cels_to_fahr(cels):\n",
    "    \"This function takes in a parameter @cels and converts it to Fahrenheit.\"\n",
    "    return cels * 9/5 + 32\n",
    "\n",
    "cels_to_fahr.__doc__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A more complicated docstring like you might see \n",
    "in a real library might look more as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def check_length(length: int, string: str) -> bool:\n",
    "    \"\"\"Example function with PEP 484 type annotations.\n",
    "\n",
    "    Args:\n",
    "        length: The desired length against which the string's actual length will be checked.\n",
    "        string: The string whose length we are checking. \n",
    "\n",
    "    Returns:\n",
    "        True if the length of the `string` is `length`, False otherwise. \n",
    "    \"\"\"\n",
    "    \n",
    "    return(len(string) == length)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "check_length.__doc__"
   ]
  }
 ],
 "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.7.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}