programming_constructs/notebook.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Programming Constructs with Code Blocks"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook will look at the use of code blocks in the Python programming language. Code blocks can be used to direct code in response to a condition, repeat an operation multiple times, or to handle errors. They are also used to create custom functions. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Categorize_Identifiers Module"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook will use the following functions ```dir2```, ```variables``` and ```view``` in the custom module ```categorize_identifiers``` which is found in the same directory as this notebook file. ```dir2``` is a variant of ```dir``` that groups identifiers into a ```dict``` under categories and ```variables``` is an IPython based a variable inspector. ```view``` is used to view a ```Collection``` in more detail:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from categorize_identifiers import dir2, variables, view"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The previous tutorials covered the most commonly used classes in ```__builtins__``` in detail and this tutorial will build upon that knowledge:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['bool',\n",
       " 'bytearray',\n",
       " 'bytes',\n",
       " 'classmethod',\n",
       " 'complex',\n",
       " 'dict',\n",
       " 'enumerate',\n",
       " 'filter',\n",
       " 'float',\n",
       " 'frozenset',\n",
       " 'int',\n",
       " 'list',\n",
       " 'map',\n",
       " 'memoryview',\n",
       " 'object',\n",
       " 'property',\n",
       " 'range',\n",
       " 'reversed',\n",
       " 'set',\n",
       " 'slice',\n",
       " 'staticmethod',\n",
       " 'str',\n",
       " 'super',\n",
       " 'tuple',\n",
       " 'type',\n",
       " 'zip']"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dir2(__builtins__, print_output=False)['lower_class']"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Code Block Spacing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```python\n",
    "statement:\n",
    "    line of code\n",
    "    line of code\n",
    "    line of code\n",
    "```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that the statement ends in a colon ```:``` which is used to indicate the beginning of a code block. \n",
    "\n",
    "Each line of code belonging to the code block is indented by 4 spaces.\n",
    "\n",
    "Usually there are two blank lines left at the end of the code block to make it clear the code block has ended.\n",
    "\n",
    "```python\n",
    "statement:\n",
    "    code in block\n",
    "    code in block\n",
    "    code in block\n",
    "\n",
    "\n",
    "outside block\n",
    "outside block\n",
    "```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Code blocks can included statements with nested code blocks. Anything belonging to a nested statement is indented twice using 8 spaces (4 spaces for the outer statement and another 4 spaces for the inner statement):\n",
    "\n",
    "```python\n",
    "statement1:\n",
    "    code in outer block\n",
    "    code in outer block\n",
    "    code in outer block\n",
    "    statement2:\n",
    "        code in inner block nested in outer block\n",
    "        code in inner block nested in outer block\n",
    "        code in inner block nested in outer block\n",
    "    \n",
    "\n",
    "outside block\n",
    "outside block\n",
    "```\n",
    "\n",
    "If this markdown cell is double clicked and the indent-rainbow extension in VSCode is installed. Notice the first indentation level will be highlighted in yellow and the second will be highlighted in green."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## if, elif and else code blocks"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```if``` code block is carried out in response to a condition. Notice that the ```print``` statement is executed for a ```True``` condition:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "condition = True"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The condition was True\n"
     ]
    }
   ],
   "source": [
    "if condition:\n",
    "    print('The condition was True')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the condition is instead ```False```, the ```print``` statement is not executed and the contents of the code block are skipped:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "condition = False"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "if condition:\n",
    "    print('The condition was True')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A ```print``` statement outside the code block can be added. This is carried out after the code block when the condition is ```True```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "condition = True"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The condition was True\n",
      "Outside the Code Block\n"
     ]
    }
   ],
   "source": [
    "if condition:\n",
    "    print('The condition was True')\n",
    "\n",
    "\n",
    "print('Outside the Code Block')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the condition is ```False``` and the code block is skipped, only the ```print``` statement outside the code block is carried out:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "condition = False"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Outside the Code Block\n"
     ]
    }
   ],
   "source": [
    "if condition:\n",
    "    print('The condition was True')\n",
    "\n",
    "\n",
    "print('Outside the Code Block')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Comparison Operators"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The six comparison operators are:"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "|comparison operator|description|\n",
    "|---|---|\n",
    "|==|is equal to|\n",
    "|!=|not equal|\n",
    "|>|greater than|\n",
    "|>=|greater than or equal to|\n",
    "|<|less than|\n",
    "|<=|less than or equal to|"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The previous tutorials examined use of these comparison operators for text data types, numeric data types and collections."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A comparison operator is typically used to specify a condition:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "condition = 5 > 3\n",
    "condition"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The condition was True\n"
     ]
    }
   ],
   "source": [
    "if condition:\n",
    "    print('The condition was True')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be shortened using the comparison operator to specify the condition directly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The condition was True\n"
     ]
    }
   ],
   "source": [
    "if 5 > 3:\n",
    "    print('The condition was True')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An if statement can be configured to examine multiple conditions through the use of the and ```&``` and or ```|``` operators.\n",
    "\n",
    "The ```&``` and ```|``` operators take precedence over the comparison operators ```==```, ```!=```, ```>```, ```>=```, ```<``` and ```<=```, so conditions are normally placed in parenthesis:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The condition was True\n"
     ]
    }
   ],
   "source": [
    "if (5 > 3) & ('a' < 'b'):\n",
    "    print('The condition was True')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the parenthesis are removed, the operation ```3``` & ```'a'``` is attempted which gives a ```TypeError```:\n",
    "\n",
    "```python\n",
    "if 5 > 3 & 'a' < 'b':\n",
    "    print('The condition was True')\n",
    "```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Other conditions can be added, using parenthesis appropriately:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "if (((5 > 3) & ('a' > 'b')) | (4 == 3)):\n",
    "    print('The condition was True')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### else code block"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is common to setup a code block in response to a ```True``` condition and another code block in response to a ```False``` condition:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "condition = False"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The condition was False\n"
     ]
    }
   ],
   "source": [
    "if condition:\n",
    "    print('The condition was True')\n",
    "if not condition:\n",
    "    print('The condition was False')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is typically done shorthand using an associated else code block:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The condition was False\n"
     ]
    }
   ],
   "source": [
    "if condition:\n",
    "    print('The condition was True')\n",
    "else:\n",
    "    print('The condition was False')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### elif code block"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If multiple ```if``` code blocks are used, they are each individually assessed and the ```else``` code block is only associated with the last ```if``` code block. When both conditions are ```True```, the ```print``` statements in both ```if``` code blocks are carried out:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "10 is greater\n",
      "9 is greater\n"
     ]
    }
   ],
   "source": [
    "if 10 > 3:\n",
    "    print('10 is greater')\n",
    "if 9 > 3:\n",
    "    print('9 is greater')\n",
    "else:\n",
    "    print('These are not greater')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is common to instead setup a linked else if code block using ```elif```. When conditions are linked, only the **first** code block that has a ```True``` condition is executed. When a ```True``` condition exists in an earlier code block all subsequent code blocks are skipped and therefore not executed regardless of their individual condition. This is seen in the example below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "10 is greater\n"
     ]
    }
   ],
   "source": [
    "if 10 > 3: # True so executed\n",
    "    print('10 is greater')\n",
    "elif 9 > 3: # Previous code block condition is True so this is skipped\n",
    "    print('9 is greater')\n",
    "else: # This is also skipped\n",
    "    print('These are not greater')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```else``` code block is linked to all the subsequent code blocks and is only carried out if all conditions specified are ```False```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "These are not greater\n"
     ]
    }
   ],
   "source": [
    "if 10 > 30: # This is False, so check next condition\n",
    "    print('10 is greater')\n",
    "elif 9 > 30: # This is False, so all checks are False\n",
    "    print('9 is greater')\n",
    "else: # Therefore execute else code block\n",
    "    print('These are not greater')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There can be multiple ```elif``` code blocks:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [],
   "source": [
    "num = 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "two\n"
     ]
    }
   ],
   "source": [
    "if num == 0:\n",
    "    print('zero')\n",
    "elif num == 1:\n",
    "    print('one')\n",
    "elif num == 2:\n",
    "    print('two')\n",
    "else:\n",
    "    print('num not zero, one or two')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## match and nested case code blocks"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When a number of code blocks are used to match a variable to ordinal values, like in the case above, it is better to use a ```match``` code block. Each condition in the ```match``` code block is a ```case``` and each ```case``` has its own nested code block. Notice the double indentation of code, indicating it belongs to the corresponding ```case``` code block which in turn belongs to the ```match``` code block. ```case _``` is used to represent any other value of the variable ```num```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [],
   "source": [
    "num = 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "two\n"
     ]
    }
   ],
   "source": [
    "match num:\n",
    "    case 0:\n",
    "        print('zero')\n",
    "    case 1:\n",
    "        print('one')\n",
    "    case 2:\n",
    "        print('two')\n",
    "    case _:\n",
    "        print('num not zero, one or two')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Recall that characters are ordinal and therefore can also be used with ```match```. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [],
   "source": [
    "letter = 'c'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "c 99\n"
     ]
    }
   ],
   "source": [
    "match letter:\n",
    "    case 'a':\n",
    "        print('a', ord('a'))\n",
    "    case 'b':\n",
    "        print('b', ord('b'))\n",
    "    case 'c':\n",
    "        print('c', ord('c'))\n",
    "    case _:\n",
    "        print(\"letter not 'a', 'b' or 'c'\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With too much nesting, the ```code``` often becomes hard to read. It is generally better to try and branch out the conditions using a single level with the and ```&``` and or ```|``` operators where possible:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [],
   "source": [
    "letter = 'a'\n",
    "num = 1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "letter == 'a', num == 0\n"
     ]
    }
   ],
   "source": [
    "if (letter == 'a') & (num == 0):\n",
    "    print(\"letter == 'a', num == 0\")\n",
    "elif (letter == 'a') & (num == 1):\n",
    "    print(\"letter == 'a', num == 0\")\n",
    "else:\n",
    "    print(\"letter != 'a'\")  "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## with code block"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the following text file is created. And stored in the same folder as the interactive Python notebook file (or Python script file) as ```text.txt```:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```ps\n",
    "Baa, baa, black sheep,\n",
    "Have you any wool?\n",
    "Yes, sir, yes, sir,\n",
    "Three bags full;\n",
    "One for my master,\n",
    "One for my dame,\n",
    "And one for the little boy\n",
    "Who lives down the lane.\n",
    "```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```open``` function can be used to open the file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mSignature:\u001b[0m\n",
       "\u001b[0mopen\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m\n",
       "\u001b[0m    \u001b[0mfile\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;33m\n",
       "\u001b[0m    \u001b[0mmode\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;34m'r'\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;33m\n",
       "\u001b[0m    \u001b[0mbuffering\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;33m-\u001b[0m\u001b[1;36m1\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;33m\n",
       "\u001b[0m    \u001b[0mencoding\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;32mNone\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;33m\n",
       "\u001b[0m    \u001b[0merrors\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;32mNone\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;33m\n",
       "\u001b[0m    \u001b[0mnewline\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;32mNone\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;33m\n",
       "\u001b[0m    \u001b[0mclosefd\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;32mTrue\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;33m\n",
       "\u001b[0m    \u001b[0mopener\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;32mNone\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;33m\n",
       "\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m\n",
       "Open file and return a stream.  Raise OSError upon failure.\n",
       "\n",
       "file is either a text or byte string giving the name (and the path\n",
       "if the file isn't in the current working directory) of the file to\n",
       "be opened or an integer file descriptor of the file to be\n",
       "wrapped. (If a file descriptor is given, it is closed when the\n",
       "returned I/O object is closed, unless closefd is set to False.)\n",
       "\n",
       "mode is an optional string that specifies the mode in which the file\n",
       "is opened. It defaults to 'r' which means open for reading in text\n",
       "mode.  Other common values are 'w' for writing (truncating the file if\n",
       "it already exists), 'x' for creating and writing to a new file, and\n",
       "'a' for appending (which on some Unix systems, means that all writes\n",
       "append to the end of the file regardless of the current seek position).\n",
       "In text mode, if encoding is not specified the encoding used is platform\n",
       "dependent: locale.getencoding() is called to get the current locale encoding.\n",
       "(For reading and writing raw bytes use binary mode and leave encoding\n",
       "unspecified.) The available modes are:\n",
       "\n",
       "========= ===============================================================\n",
       "Character Meaning\n",
       "--------- ---------------------------------------------------------------\n",
       "'r'       open for reading (default)\n",
       "'w'       open for writing, truncating the file first\n",
       "'x'       create a new file and open it for writing\n",
       "'a'       open for writing, appending to the end of the file if it exists\n",
       "'b'       binary mode\n",
       "'t'       text mode (default)\n",
       "'+'       open a disk file for updating (reading and writing)\n",
       "========= ===============================================================\n",
       "\n",
       "The default mode is 'rt' (open for reading text). For binary random\n",
       "access, the mode 'w+b' opens and truncates the file to 0 bytes, while\n",
       "'r+b' opens the file without truncation. The 'x' mode implies 'w' and\n",
       "raises an `FileExistsError` if the file already exists.\n",
       "\n",
       "Python distinguishes between files opened in binary and text modes,\n",
       "even when the underlying operating system doesn't. Files opened in\n",
       "binary mode (appending 'b' to the mode argument) return contents as\n",
       "bytes objects without any decoding. In text mode (the default, or when\n",
       "'t' is appended to the mode argument), the contents of the file are\n",
       "returned as strings, the bytes having been first decoded using a\n",
       "platform-dependent encoding or using the specified encoding if given.\n",
       "\n",
       "buffering is an optional integer used to set the buffering policy.\n",
       "Pass 0 to switch buffering off (only allowed in binary mode), 1 to select\n",
       "line buffering (only usable in text mode), and an integer > 1 to indicate\n",
       "the size of a fixed-size chunk buffer.  When no buffering argument is\n",
       "given, the default buffering policy works as follows:\n",
       "\n",
       "* Binary files are buffered in fixed-size chunks; the size of the buffer\n",
       "  is chosen using a heuristic trying to determine the underlying device's\n",
       "  \"block size\" and falling back on `io.DEFAULT_BUFFER_SIZE`.\n",
       "  On many systems, the buffer will typically be 4096 or 8192 bytes long.\n",
       "\n",
       "* \"Interactive\" text files (files for which isatty() returns True)\n",
       "  use line buffering.  Other text files use the policy described above\n",
       "  for binary files.\n",
       "\n",
       "encoding is the name of the encoding used to decode or encode the\n",
       "file. This should only be used in text mode. The default encoding is\n",
       "platform dependent, but any encoding supported by Python can be\n",
       "passed.  See the codecs module for the list of supported encodings.\n",
       "\n",
       "errors is an optional string that specifies how encoding errors are to\n",
       "be handled---this argument should not be used in binary mode. Pass\n",
       "'strict' to raise a ValueError exception if there is an encoding error\n",
       "(the default of None has the same effect), or pass 'ignore' to ignore\n",
       "errors. (Note that ignoring encoding errors can lead to data loss.)\n",
       "See the documentation for codecs.register or run 'help(codecs.Codec)'\n",
       "for a list of the permitted encoding error strings.\n",
       "\n",
       "newline controls how universal newlines works (it only applies to text\n",
       "mode). It can be None, '', '\\n', '\\r', and '\\r\\n'.  It works as\n",
       "follows:\n",
       "\n",
       "* On input, if newline is None, universal newlines mode is\n",
       "  enabled. Lines in the input can end in '\\n', '\\r', or '\\r\\n', and\n",
       "  these are translated into '\\n' before being returned to the\n",
       "  caller. If it is '', universal newline mode is enabled, but line\n",
       "  endings are returned to the caller untranslated. If it has any of\n",
       "  the other legal values, input lines are only terminated by the given\n",
       "  string, and the line ending is returned to the caller untranslated.\n",
       "\n",
       "* On output, if newline is None, any '\\n' characters written are\n",
       "  translated to the system default line separator, os.linesep. If\n",
       "  newline is '' or '\\n', no translation takes place. If newline is any\n",
       "  of the other legal values, any '\\n' characters written are translated\n",
       "  to the given string.\n",
       "\n",
       "If closefd is False, the underlying file descriptor will be kept open\n",
       "when the file is closed. This does not work when a file name is given\n",
       "and must be True in that case.\n",
       "\n",
       "A custom opener can be used by passing a callable as *opener*. The\n",
       "underlying file descriptor for the file object is then obtained by\n",
       "calling *opener* with (*file*, *flags*). *opener* must return an open\n",
       "file descriptor (passing os.open as *opener* results in functionality\n",
       "similar to passing None).\n",
       "\n",
       "open() returns a file object whose type depends on the mode, and\n",
       "through which the standard file operations such as reading and writing\n",
       "are performed. When open() is used to open a file in a text mode ('w',\n",
       "'r', 'wt', 'rt', etc.), it returns a TextIOWrapper. When used to open\n",
       "a file in a binary mode, the returned class varies: in read binary\n",
       "mode, it returns a BufferedReader; in write binary and append binary\n",
       "modes, it returns a BufferedWriter, and in read/write mode, it returns\n",
       "a BufferedRandom.\n",
       "\n",
       "It is also possible to use a string or bytearray as a file for both\n",
       "reading and writing. For strings StringIO can be used like a file\n",
       "opened in a text mode, and for bytes a BytesIO can be used like a file\n",
       "opened in a binary mode.\n",
       "\u001b[1;31mType:\u001b[0m      function"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "open?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```mode``` keyword input argument can be specified using a single letter:"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "|mode|definition|\n",
    "|---|---|\n",
    "|```'r'```|open an existing file and read existing content|\n",
    "|```'w'```|open an existing file and write over existing content|\n",
    "|```'a'```|open an existing file and append new content|\n",
    "|```'x'```|create a new file and write new content|"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A second letter can also be used for the encoding. The encoding can be ```'t'``` text (default) which is also known as ```'utf-8'``` or ```'b'``` binary which is known as ```'ascii'```. "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```mode=rt``` for example is the default which reads a text file encoded as text (```'ascii'```). "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For other encoding schemes, the encoding keyword argument is seperately used. For a CSV file created in Microsoft Excel, the ```'utf-8-sig'``` encoding needs to be used to properly handle the BOM. The other encoding schemes were discussed in detail in the previous ```bytes``` notebook. "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "encoding|bit|bytes|byte order|BOM|\n",
    "|---|---|---|---|---|\n",
    "|```'ascii'```|1|8| |---|\n",
    "|```'latin1'```|1|8| | |\n",
    "|```'utf-16-le'```|2|16|little endian| |\n",
    "|```'utf-16-be'```|2|16|big endian| |\n",
    "|```'utf-16'```|2|16| |BOM|\n",
    "|```'utf-32-le'```|4|32|little endian| |\n",
    "|```'utf-32-be'```|4|32|big endian| |\n",
    "|```'utf-32'```|4|32| |BOM|\n",
    "|```'utf-8'```|1-4|adaptive|1-4 adaptive| |\n",
    "|```'utf-8-sig'```|1-4|adaptive|1-4 adaptive|BOM|"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```newline``` keyword input argument can be used to specify the character that is used to represent a new line. in the example above a carriage return and line feed are used. In Python this is the escape characters ```'\\r\\n'``` which is the default option on Windows but is ```'\\n'``` on Linux or Mac:"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The file can be opened using:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<_io.TextIOWrapper name='text.txt' mode='rt' encoding='cp1252'>"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "file_object = open('text.txt', mode='rt')\n",
    "file_object"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The identifiers for the ```file_object``` can be viewed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'attribute': ['buffer',\n",
      "               'closed',\n",
      "               'encoding',\n",
      "               'errors',\n",
      "               'line_buffering',\n",
      "               'mode',\n",
      "               'name',\n",
      "               'newlines',\n",
      "               'write_through'],\n",
      " 'method': ['close',\n",
      "            'detach',\n",
      "            'fileno',\n",
      "            'flush',\n",
      "            'isatty',\n",
      "            'read',\n",
      "            'readable',\n",
      "            'readline',\n",
      "            'readlines',\n",
      "            'reconfigure',\n",
      "            'seek',\n",
      "            'seekable',\n",
      "            'tell',\n",
      "            'truncate',\n",
      "            'writable',\n",
      "            'write',\n",
      "            'writelines'],\n",
      " 'datamodel_attribute': ['__dict__', '__module__'],\n",
      " 'datamodel_method': ['__del__',\n",
      "                      '__enter__',\n",
      "                      '__exit__',\n",
      "                      '__iter__',\n",
      "                      '__next__'],\n",
      " 'internal_attribute': ['_CHUNK_SIZE', '_finalizing'],\n",
      " 'internal_method': ['_checkClosed',\n",
      "                     '_checkReadable',\n",
      "                     '_checkSeekable',\n",
      "                     '_checkWritable']}\n"
     ]
    }
   ],
   "source": [
    "dir2(file_object, object, unique_only=True)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the example above the mode is set for reading, so the ```readline``` method can be used to read an individual line and ```return``` it as a ```str```. Alternatively the ```readlines``` method can be used to read all lines and return a ```list``` of lines where each line is a ```str```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'hello world\\n'"
      ]
     },
     "execution_count": 33,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "file_object.readline()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[]"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "file_object.readlines()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once a file has been worked ```with```, the ```close``` method should be used to close the file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [],
   "source": [
    "file_object.close()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This will release the physical file from Python, allowing it to be used by other programs in Windows. The ```file_object``` will still present as an instance in the Python namespace but will no longer be associated to the physical file."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```file_object``` has two datamodel identifiers of particular interest ```__enter__``` (*dunder enter*) and ```__exit__``` (*dunder exit*) which means the ```file_object``` can be entered and exited using a context manager. The context manager is essentially a code block, ```with``` is used to create the code block and has an associated colon ```:```. Instead of assignment to a variable using the assignment operator ```=```, the ```as``` keyword is used. The operations above with a context manager are:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [],
   "source": [
    "with open('text.txt', mode='rt') as file_object:\n",
    "    first_line = file_object.readline()\n",
    "    remaining_lines = file_object.readlines()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'hello world\\n'"
      ]
     },
     "execution_count": 37,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "first_line"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[]"
      ]
     },
     "execution_count": 38,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "remaining_lines    "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The use of the with context manager opens, the physical file within the code block using the datamodel method ```__enter__``` (*dunder enter*) and when the code block ends uses the datamodel method ```__exit__``` (*dunder exit*) to release the physical file. This prevents a file from being opened in Python and not properly closed and the code is a bit cleaner to read grouping all the operations with that file together."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The for loop"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```for``` loop can be used to carry out operations within a code block *for* a specified number of times."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### iterator"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```for``` loop requires an iterator which comes from a ```Collection```. The following ```str``` can be used to examine the mechanics behind a ```for``` loop:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [],
   "source": [
    "word = 'hello'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 40,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "'h' in 'hello'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Recall that use of ```in``` in the context above, uses the datamodel identifier ```__contains__``` (*dunder contains*). There is also the ```__iter__``` datamodel method which can be used to create an iterator and the ```__len__``` datamodel method which specifies the number of Unicode characters in the ```str```. An iterator can be created using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<str_ascii_iterator at 0x250a4244340>"
      ]
     },
     "execution_count": 41,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "letter = iter(word)\n",
    "letter"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```next``` keyword can be used on the iterator until the iterator is exhausted:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'h'"
      ]
     },
     "execution_count": 42,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(letter)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'e'"
      ]
     },
     "execution_count": 43,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(letter)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'l'"
      ]
     },
     "execution_count": 44,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(letter)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'l'"
      ]
     },
     "execution_count": 45,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(letter)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'o'"
      ]
     },
     "execution_count": 46,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(letter)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If ```next``` is used again, a ```StopIteration``` error will display because the iterator is exhausted:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To exhaust the iterator, ```next``` is called ```5``` times, which matches the length of the ```word```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5"
      ]
     },
     "execution_count": 47,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "len(word)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```word``` can also be cast into a ```tuple```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {},
   "outputs": [],
   "source": [
    "word_t = tuple(word)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because a ```tuple``` is also a ```Collection``` the methods ```__contains__``` (*dunder contains*), ```__iter__``` (*dunder iter*) and ```__len__``` (*dunder len*) are defined. This means an iterator can be created. This iterator is a ```tuple``` iterator, where each item is the reference to the Python ```object``` at the specific index of the ```tuple``` being examined. Since this ```tuple``` was cast from a ```str``` each Python object is a one character ```str```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<tuple_iterator at 0x250a1df2fb0>"
      ]
     },
     "execution_count": 49,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "letter_t = iter(word_t)\n",
    "letter_t"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Therefore the following behaves similarly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'h'"
      ]
     },
     "execution_count": 50,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(letter_t)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 51,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'e'"
      ]
     },
     "execution_count": 51,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(letter_t)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'l'"
      ]
     },
     "execution_count": 52,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(letter_t)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 53,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'l'"
      ]
     },
     "execution_count": 53,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(letter_t)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'o'"
      ]
     },
     "execution_count": 54,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(letter_t)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A ```list``` which is the mutable counterpart to the immutable ```tuple``` behaves similarly.\n",
    "\n",
    "A ```set``` only contains unique values and is not ordered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 55,
   "metadata": {},
   "outputs": [],
   "source": [
    "word_s = set(word)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In a ```set``` the datamodel methods ```__contains__``` (*dunder contains*), ```__iter__``` (*dunder iter*) and ```__len__``` (*dunder len*) are still available. An iterator can be created:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 56,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<set_iterator at 0x250a42a0180>"
      ]
     },
     "execution_count": 56,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "letter_s = iter(word_s)\n",
    "letter_s"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The lack of order is seen when using next on the ```set_iterator```, notice that the letter ```'l'``` only shows once as each letter has to be unique in the ```set```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 57,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'l'"
      ]
     },
     "execution_count": 57,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(letter_s)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 58,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'e'"
      ]
     },
     "execution_count": 58,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(letter_s)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 59,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'h'"
      ]
     },
     "execution_count": 59,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(letter_s)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 60,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'o'"
      ]
     },
     "execution_count": 60,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(letter_s)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Iterating using a for loop"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A ```for``` loop can be used to loop over each letter in each of the ```Collections``` above. Returning to the ```str``` for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 61,
   "metadata": {},
   "outputs": [],
   "source": [
    "word = 'hello'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 62,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "h\n",
      "e\n",
      "l\n",
      "l\n",
      "o\n"
     ]
    }
   ],
   "source": [
    "for letter in word:\n",
    "    print(letter)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Under the hood, the ```for``` loop uses the ```__contains__``` (*dunder contains*), ```__iter__``` (*dunder iter*) and ```__len__``` (*dunder len*) datamodel methods to loop over each Unicode character in the ```str``` instance ```word```. "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```letter``` is a loop variable which can be accessed in the loop and at the end of the loops execution is assigned to the last value:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 63,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'o'"
      ]
     },
     "execution_count": 63,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "letter"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It can be renamed using any variable name. When the variable is not referenced in the ```for``` loop, it is called ```_```. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 64,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello\n",
      "hello\n",
      "hello\n",
      "hello\n",
      "hello\n"
     ]
    }
   ],
   "source": [
    "for _ in word:\n",
    "    print(word)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that ```hello``` is printed out ```5``` times, because it has a length of ```5```."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 65,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5"
      ]
     },
     "execution_count": 65,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "len('hello')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another example can be given using a ```tuple``` which recall can be conceptualised as an ```archive``` of records:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 66,
   "metadata": {},
   "outputs": [],
   "source": [
    "archive = (0, True, 3.14, 'hello')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 67,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0\n",
      "True\n",
      "3.14\n",
      "hello\n"
     ]
    }
   ],
   "source": [
    "for record in archive:\n",
    "    print(record)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is somewhat common to use a plural term for the collection being looped over and a singular term for the loop variable:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 68,
   "metadata": {},
   "outputs": [],
   "source": [
    "records = (0, True, 3.14, 'hello')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 69,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0\n",
      "True\n",
      "3.14\n",
      "hello\n"
     ]
    }
   ],
   "source": [
    "for record in records:\n",
    "    print(record)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Mutability Issues"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Mutable methods such as the ```list``` method ```append``` are commonly used within for loops. "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Care should be taken not to use a ```for``` loop to iterate over the mutable sequence itself, while mutating the same sequence, as an infinite loop can occur. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 70,
   "metadata": {},
   "outputs": [],
   "source": [
    "active = [0, True, 3.14, 'hello']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```python\n",
    "for record in active:\n",
    "    active.append('bye')\n",
    "```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the code is copied into a Python cell below and run, there will be an infinite loop. To exit the infinite loop, press the stop button beside the cell. You may need to restart the kernel if it doesn't stop execution properly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Instead a ```copy``` of the mutable sequence can be made to loop over, for example: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 71,
   "metadata": {},
   "outputs": [],
   "source": [
    "active = [0, True, 3.14, 'hello']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 72,
   "metadata": {},
   "outputs": [],
   "source": [
    "for record in active.copy():\n",
    "    active.append('bye')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 73,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[0, True, 3.14, 'hello', 'bye', 'bye', 'bye', 'bye']"
      ]
     },
     "execution_count": 73,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "active"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The range class"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A ```range``` instance is commonly used to construct a ```for``` loop. Let's examine a ```range``` instance in detail:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 74,
   "metadata": {},
   "outputs": [],
   "source": [
    "numbers = range(0, 5, 1)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A ```range``` instance has an ```int``` instance for a ```start```, ```stop``` and ```step``` value. It can be cast into an iterator:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 75,
   "metadata": {},
   "outputs": [],
   "source": [
    "number_iter = iter(numbers)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And ```next``` can be used to have a look at it element by element. Notice it uses zero-order indexing so is inclusive of the lower bound:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 76,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 76,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(number_iter)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 77,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 77,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(number_iter)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 78,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 78,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(number_iter)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 79,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 79,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(number_iter)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 80,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "4"
      ]
     },
     "execution_count": 80,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(number_iter)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The iterator displays single values up to but not including the upper bound. All the elements in the ```range``` instance can be seen by casting it to a ```tuple```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 81,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(0, 1, 2, 3, 4)"
      ]
     },
     "execution_count": 81,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(range(0, 5, 1))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 82,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(0, 1, 2, 3, 4)"
      ]
     },
     "execution_count": 82,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(range(0, 5)) # step takes default of 1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 83,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(0, 1, 2, 3, 4)"
      ]
     },
     "execution_count": 83,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(range(5)) # start takes the default of 0 and step takes the default of 1"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```range``` initialisation signature can be used with the length of a ```Collection``` to get the ```int``` indexes of the ```Collection```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 84,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(0, 1, 2, 3)"
      ]
     },
     "execution_count": 84,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "active = [0, True, 3.14, 'hello']\n",
    "tuple(range(len(active)))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is commonly used in a ```for``` loop:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 85,
   "metadata": {},
   "outputs": [],
   "source": [
    "active = [0, True, 3.14, 'hello']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 86,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0 [0, True, 3.14, 'hello', 'bye']\n",
      "1 [0, True, 3.14, 'hello', 'bye', 'bye']\n",
      "2 [0, True, 3.14, 'hello', 'bye', 'bye', 'bye']\n",
      "3 [0, True, 3.14, 'hello', 'bye', 'bye', 'bye', 'bye']\n"
     ]
    }
   ],
   "source": [
    "for num in range(len(active)):\n",
    "    active.append('bye')\n",
    "    print(num, active)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And can be used for the purposes of indexing:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 87,
   "metadata": {},
   "outputs": [],
   "source": [
    "word = 'hello'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 88,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "h\n",
      "e\n",
      "l\n",
      "l\n",
      "o\n"
     ]
    }
   ],
   "source": [
    "for num in range(len(word)):\n",
    "    print(word[num])"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the above is not as readable as:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 89,
   "metadata": {},
   "outputs": [],
   "source": [
    "word = 'hello'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 90,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "h\n",
      "e\n",
      "l\n",
      "l\n",
      "o\n"
     ]
    }
   ],
   "source": [
    "for letter in word:\n",
    "    print(letter)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However having access to the index is sometimes useful for other purposes. For example string replication can be carried out using multiplication of the index:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 91,
   "metadata": {},
   "outputs": [],
   "source": [
    "word = 'hello'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 92,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "e\n",
      "ll\n",
      "lll\n",
      "oooo\n"
     ]
    }
   ],
   "source": [
    "for num in range(len(word)):\n",
    "    print(num * word[num])"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or alternatively the index can be printed alongside the character:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 93,
   "metadata": {},
   "outputs": [],
   "source": [
    "word = 'hello'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 94,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0 h\n",
      "1 e\n",
      "2 l\n",
      "3 l\n",
      "4 o\n"
     ]
    }
   ],
   "source": [
    "for num in range(len(word)):\n",
    "    print(num, word[num])"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```range``` instances with different ```start``` values can be created: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 95,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(0, 1, 2, 3, 4)"
      ]
     },
     "execution_count": 95,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(range(5))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that the ```range``` instance is always inclusive of the ```start``` bound and exclusive of the ```stop``` bound:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 96,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(1, 2, 3, 4)"
      ]
     },
     "execution_count": 96,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(range(1, 5))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "the effect of a non-unit ```step``` can be examined:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 97,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(0, 2, 4)"
      ]
     },
     "execution_count": 97,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(range(0, 6, 2))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 98,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(1, 3, 5)"
      ]
     },
     "execution_count": 98,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(range(1, 6, 2))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 99,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1 hello\n",
      "3 hellohellohello\n",
      "5 hellohellohellohellohello\n"
     ]
    }
   ],
   "source": [
    "for num in tuple(range(1, 6, 2)):\n",
    "    print(num, num * 'hello')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Zero-order indexing needs to be addressed when using negative values. For example beginning at a negative value and counting up until ```0``` requires a ```stop``` value ```1``` past ```0``` which is ```1```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 100,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(-5, -4, -3, -2, -1, 0)"
      ]
     },
     "execution_count": 100,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(range(-5, 1, 1))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or using a negative step of ```-1``` to count down from a positive integer value to ```0```, requires a ```stop``` value ```-1``` past ```0``` which is ```-1```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 101,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(5, 4, 3, 2, 1, 0)"
      ]
     },
     "execution_count": 101,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(range(5, -1, -1))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The enumerate class"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Previously the ```range``` of the ```len``` of the ```Collection``` was used:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 102,
   "metadata": {},
   "outputs": [],
   "source": [
    "word = 'hello'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 103,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0 h\n",
      "1 e\n",
      "2 l\n",
      "3 l\n",
      "4 o\n"
     ]
    }
   ],
   "source": [
    "for num in range(len(word)):\n",
    "    print(num, word[num])"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This syntax is pretty cumbersome. A ```Collection``` can be enumerated by supplying the ```Collection``` to the initialisation signature of the ```enumerate``` class. This is essentially an iterator of two element ```tuples``` where the first element corresponds to the numeric index and the second element corresponds to the value:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 104,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<enumerate at 0x250a4330860>"
      ]
     },
     "execution_count": 104,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "enumerate(word)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It can be cast to a ```Collection``` such as a ```tuple```. In this case a ```list``` will be used so the ```Collection``` brackets can be distinguished:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 105,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(0, 'h'), (1, 'e'), (2, 'l'), (3, 'l'), (4, 'o')]"
      ]
     },
     "execution_count": 105,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(enumerate(word))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be used in a ```for``` loop:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 106,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(0, 'h')\n",
      "(1, 'e')\n",
      "(2, 'l')\n",
      "(3, 'l')\n",
      "(4, 'o')\n"
     ]
    }
   ],
   "source": [
    "for archive in enumerate(word):\n",
    "    print(archive)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Typically the ```tuple``` is unpacked:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 107,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0 h\n",
      "1 e\n",
      "2 l\n",
      "3 l\n",
      "4 o\n"
     ]
    }
   ],
   "source": [
    "for (index, value) in enumerate(word):\n",
    "    print(index, value)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And the parenthesis are not required when using ```tuple``` unpacking:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 108,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0 h\n",
      "1 e\n",
      "2 l\n",
      "3 l\n",
      "4 o\n"
     ]
    }
   ],
   "source": [
    "for index, value in enumerate(word):\n",
    "    print(index, value)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Dictionary Keys"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Recall that a ```dict``` has the form:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 109,
   "metadata": {},
   "outputs": [],
   "source": [
    "mapping = dict(red='#ff0000', green='#00b050', blue='#0070c0')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 110,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'red': '#ff0000', 'green': '#00b050', 'blue': '#0070c0'}"
      ]
     },
     "execution_count": 110,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mapping"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```dict``` is also a ```Collection``` and has the datamodel identifiers ```__contains__``` (*dunder contains*), ```__iter__``` (*dunder iter*) and ```__len__``` (*dunder len*). When an iterator is created from a ```dict```, it iterates over the ```keys```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 111,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<dict_keyiterator at 0x250a4332b10>"
      ]
     },
     "execution_count": 111,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "keys = iter(mapping)\n",
    "keys"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 112,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'red'"
      ]
     },
     "execution_count": 112,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(keys)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 113,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'green'"
      ]
     },
     "execution_count": 113,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(keys)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 114,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'blue'"
      ]
     },
     "execution_count": 114,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(keys)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This means that using a ```for``` loop on a ```dict``` iterates over the ```keys```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 115,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "red\n",
      "green\n",
      "blue\n"
     ]
    }
   ],
   "source": [
    "for key in mapping:\n",
    "    print(key)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Recall that a ```value``` can be retrieved by indexing into the ```dict``` using the ```key```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 116,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "#ff0000\n",
      "#00b050\n",
      "#0070c0\n"
     ]
    }
   ],
   "source": [
    "for key in mapping:\n",
    "    print(mapping[key])"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```dict``` has the three methods ```keys```, ```values``` and ```items```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 117,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict_keys(['red', 'green', 'blue'])"
      ]
     },
     "execution_count": 117,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mapping.keys()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 118,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict_values(['#ff0000', '#00b050', '#0070c0'])"
      ]
     },
     "execution_count": 118,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mapping.values()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 119,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict_items([('red', '#ff0000'), ('green', '#00b050'), ('blue', '#0070c0')])"
      ]
     },
     "execution_count": 119,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mapping.items()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These are all iterable. ```keys``` are not normally explicitly used as iterating over the ```keys``` instance is equivalent to iterating over the ```dict``` instance directly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 120,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "red\n",
      "green\n",
      "blue\n"
     ]
    }
   ],
   "source": [
    "for key in mapping.keys():\n",
    "    print(key)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```values``` are also not normally explicitly used as it is relatively easy to index into the ```dict``` instance using a ```key``` as seen before:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 121,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "#ff0000\n",
      "#00b050\n",
      "#0070c0\n"
     ]
    }
   ],
   "source": [
    "for value in mapping.values():\n",
    "    print(value)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Each ```item``` in ```items``` is a ```tuple``` of the form ```(key, value)```. Notice the similarity between this and the ```(index, value)``` seen when a ```Collection``` was enumerated. This ```tuple``` can be accessed in a loop using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 122,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "('red', '#ff0000')\n",
      "('green', '#00b050')\n",
      "('blue', '#0070c0')\n"
     ]
    }
   ],
   "source": [
    "for archive in mapping.items():\n",
    "    print(archive)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is normally simplified using ```tuple``` unpacking:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 123,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "red #ff0000\n",
      "green #00b050\n",
      "blue #0070c0\n"
     ]
    }
   ],
   "source": [
    "for (key, value) in mapping.items():\n",
    "    print(key, value)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And once again the parenthesis are not required when using ```tuple``` unpacking:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 124,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "red #ff0000\n",
      "green #00b050\n",
      "blue #0070c0\n"
     ]
    }
   ],
   "source": [
    "for key, value in mapping.items():\n",
    "    print(key, value)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This syntax is sometimes used instead fo a looping over a ```dict``` directly for improved readibility."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The while Loop"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```while``` loop can be conceptualised as an ```if``` code block that is continually repeated *while* a condition is ```True```. Note when the condition is never updated in the code block, the ```while``` loop will never exit resulting in an infinite loop. \n",
    "\n",
    "```python\n",
    "while True:\n",
    "    print('no changes')\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The cell above is a raw cell. If the code is copied into a Python cell and run, there will be an infinite loop. To exit the infinite loop, press the stop button beside the cell. You may need to restart the kernel if it doesn't stop execution properly."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A variable can be initialised before entering a ```while``` loop. This variable is examined in the ```while``` loops condition and code within the while loop updates the value of this variable. Eventually the value of the variable will be updated to a value which makes the condition of the ```while``` loop ```False``` and therefore leads to an exit of the ```while``` loop."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The initial unindented ```print``` statement shows the initial value of ```loop_var``` before the ```while``` loop. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 125,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "loop_var = 0\n"
     ]
    }
   ],
   "source": [
    "# Before while loop\n",
    "loop_var = 0\n",
    "print(f'loop_var = {loop_var}')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The indented ```print``` statements shows the value of ```loop_var``` when the ```while``` condition is checked. For each of these values, the condition ```loop_var < 5``` is ```True``` and the value ```loop_var``` is incremented."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 126,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\tloop_var = 0\n",
      "\tloop_var = 1\n",
      "\tloop_var = 2\n",
      "\tloop_var = 3\n",
      "\tloop_var = 4\n"
     ]
    }
   ],
   "source": [
    "# During while loop\n",
    "while loop_var < 5:\n",
    "    print(f'\\tloop_var = {loop_var}')\n",
    "    loop_var += 1"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The final unindented ```print``` statement shows the final value of ```5```. This value was incremented from ```4``` in the last iteration of the ```while``` loop. For this value of ```5```, the condition of the ```while``` loop ```loop_var < 5``` was ```False``` and therefore the ```while``` loop exited:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 127,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "loop_var = 5\n"
     ]
    }
   ],
   "source": [
    "# After while loop\n",
    "print(f'loop_var = {loop_var}')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```while``` loops are often used when interacting with hardware. An example is using the input function which waits for a response from a user and only ends after the user has pressed ```↵``` on the keyboard:\n",
    "\n",
    "```python\n",
    "user_message = input('Input some text: ')\n",
    "```\n",
    "\n",
    "```python\n",
    "user_message\n",
    "```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the code from the top cell is copied into a Python cell and run, there will be an infinite loop until the user provides input and hits ```↵```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A ```while``` loop can be used in place of any ```for``` loop although the syntax may not be as elegant. Compare the following for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 128,
   "metadata": {},
   "outputs": [],
   "source": [
    "index = 0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 129,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "h\n",
      "e\n",
      "l\n",
      "l\n",
      "o\n"
     ]
    }
   ],
   "source": [
    "while index < len('hello'):\n",
    "    print('hello'[index])\n",
    "    index += 1"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "with:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 130,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "h\n",
      "e\n",
      "l\n",
      "l\n",
      "o\n"
     ]
    }
   ],
   "source": [
    "for letter in 'hello':\n",
    "    print(letter)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A ```for``` loop cannot replace, all occurances of a ```while``` loop. In the above scenario for example, *while* waiting for user input there is no specified duration to wait for the user to input text. The user can input text quickly, slowly or not at all (resulting in an infinite loop). "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```while``` loops are often employed in sensor feedback mechanisms. A central heating system may use a ```while``` loop to turn on a heater *while* the temperature is below a set point measured by a temperature sensor. It may also use a ```while``` loop to turn on air conditioning *while* the temperature is above the same set point. Both of these while loops may be contained within an infinite ```while``` loop which runs continuously to maintain the temperature *while* the central heating is turned on."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## List, Generator and Dictionary Comprehensions"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Supposing the following ```tuple``` is created:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 131,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = (0, 1, 2, 3, 4)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Supposing each number is to be doubled. Recall that multiplication of a ```Collection``` by a scalar replicates the ```Collection``` and therefore a ```for``` loop has to be made, so each number in ```num``` can be doubled. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 132,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0\n",
      "2\n",
      "4\n",
      "6\n",
      "8\n"
     ]
    }
   ],
   "source": [
    "for num in nums:\n",
    "    print(2 * num)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Instead of a ```print``` out of the doubled values, each value can be appended to a mutable ```Collection``` such as a ```list```. The ```list``` identifier ```append``` can be used within the ```for``` loop to ```append``` each doubled ```num```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 133,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = (0, 1, 2, 3, 4)\n",
    "doubled_nums = []"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 134,
   "metadata": {},
   "outputs": [],
   "source": [
    "for num in nums:\n",
    "    doubled_nums.append(2 * num)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 135,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[0, 2, 4, 6, 8]"
      ]
     },
     "execution_count": 135,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "doubled_nums"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And for clarity, a ```print``` statement can be added to the ```for``` loops code block to view ```doubled_nums``` during each iteration of the ```for``` loop:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 136,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = (0, 1, 2, 3, 4)\n",
    "doubled_nums = []"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 137,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[0]\n",
      "[0, 2]\n",
      "[0, 2, 4]\n",
      "[0, 2, 4, 6]\n",
      "[0, 2, 4, 6, 8]\n"
     ]
    }
   ],
   "source": [
    "for num in nums:\n",
    "    doubled_nums.append(2 * num)\n",
    "    print(doubled_nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 138,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[0, 2, 4, 6, 8]"
      ]
     },
     "execution_count": 138,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "doubled_nums"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following lines of code and the code block can be collapsed down into a single line using a ```list``` comprehension: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 139,
   "metadata": {},
   "outputs": [],
   "source": [
    "doubled_nums = []"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 140,
   "metadata": {},
   "outputs": [],
   "source": [
    "for num in nums:\n",
    "    doubled_nums.append(2 * num)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this case:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 141,
   "metadata": {},
   "outputs": [],
   "source": [
    "doubled_nums = [2 * num for num in nums]"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A ```list``` comprehension is typically used to create an output ```list``` from interaction with a collection via a ```for``` loop. The square brackets ```[]``` enclose the ```list```. The ```list``` is assigned to an instance name ```doubled_nums``` using the assignment operator ```=```:\n",
    "\n",
    "```python\n",
    "doubled_nums = []\n",
    "```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To the left hand side, the expression supplied to the ```list``` identifier ```append``` is used:\n",
    "\n",
    "```python\n",
    "doubled_nums.append(2 * num)\n",
    "```\n",
    "\n",
    "```python\n",
    "doubled_nums = [2 * num]\n",
    "```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To the right hand side the ```for``` loop is added. Note as the ```list``` comprehension has no code block there is no colon:\n",
    "\n",
    "```python\n",
    "for num in nums:\n",
    "    #\n",
    "```\n",
    "\n",
    "```python\n",
    "doubled_nums = [2 * num for num in nums]\n",
    "```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "list comprehension can also include a condition."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 142,
   "metadata": {},
   "outputs": [],
   "source": [
    "doubled_even_nums = [2 * num for num in nums if num % 2 == 0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 143,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[0, 4, 8]"
      ]
     },
     "execution_count": 143,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "doubled_even_nums"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the condition has an associated ```else``` statement, the expression when the condition is ```True``` is specified, followed by the expression when the condition is ```False```. ```elif``` is not supported for ```list``` comprehension and code blocks should be used when the code gets more complicated:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 144,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = (0, 1, 2, 3, 4)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 145,
   "metadata": {},
   "outputs": [],
   "source": [
    "parity = ['even' if num % 2 == 0 else 'odd' for num in nums] "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 146,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['even', 'odd', 'even', 'odd', 'even']"
      ]
     },
     "execution_count": 146,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "parity"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the square brackets ```[ ]``` are replaced by parenthesis ```( )```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 147,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = (0, 1, 2, 3, 4)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 148,
   "metadata": {},
   "outputs": [],
   "source": [
    "double_nums = (num * 2 for num in nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 149,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<generator object <genexpr> at 0x00000250A424F370>"
      ]
     },
     "execution_count": 149,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "double_nums"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A generator is essentially an iterator that carries out an expression. In this case the expression ```2 * num``` for each ```num in nums``` when ```next``` is used:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 150,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 150,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(double_nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 151,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 151,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(double_nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 152,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "4"
      ]
     },
     "execution_count": 152,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(double_nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 153,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "6"
      ]
     },
     "execution_count": 153,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(double_nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 154,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "8"
      ]
     },
     "execution_count": 154,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(double_nums)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Exhausting the generator gives a ```StopIteration``` error."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note: the ```( )``` enclosing a generator expression are used for parenthesis. In this use case notice that there is no , and therefore they do not represent a tuple. Think of it being analogous to the difference between ```(4)``` and ```(4,)``` which give a scalar versus with order or precedence indicated using the brackets and a single element ```tuple``` where the brackets are used to enclose the tuple."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the square brackets ```[ ]``` are replaced by braces ```{ }```, a ```dict``` comprehension is used. Recall a ```dict``` has ```key: value``` pairs. The expression for the ```keys``` and the expression for the ```values``` is separated out. "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example if the following list of colors is created: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 155,
   "metadata": {},
   "outputs": [],
   "source": [
    "colors = ['red', 'green', 'blue']"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A mapping which takes the first letter in the colour as the ```key``` and the full color as the ```value``` can be created using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 156,
   "metadata": {},
   "outputs": [],
   "source": [
    "mapping = {color[0]: color for color in colors}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 157,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'r': 'red', 'g': 'green', 'b': 'blue'}"
      ]
     },
     "execution_count": 157,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mapping"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The key expression is:\n",
    "\n",
    "```python\n",
    "color[0]\n",
    "```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The value expression is:\n",
    "\n",
    "```python\n",
    "color\n",
    "```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This key expression can be used in a list comprehension to get the keys:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 158,
   "metadata": {},
   "outputs": [],
   "source": [
    "keys = [color[0] for color in colors]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 159,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['r', 'g', 'b']"
      ]
     },
     "execution_count": 159,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "keys"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Likewise the value expression can be used to get the values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 160,
   "metadata": {},
   "outputs": [],
   "source": [
    "values = [color for color in colors]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 161,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['red', 'green', 'blue']"
      ]
     },
     "execution_count": 161,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "values"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The colon in the ```dict``` comprehension carries out the same purpose as the colon in a dictionary and separates, the key expression from the value expression."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```dict``` comprehensions can also have a condition. If the one letter keys are looped through, the ordinal value of the key can be examined:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 162,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "114\n",
      "103\n",
      "98\n"
     ]
    }
   ],
   "source": [
    "for key in keys:\n",
    "    print(ord(key))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be used to produce a ```dict``` of only the keys that have a positive ordinal value:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 163,
   "metadata": {},
   "outputs": [],
   "source": [
    "mapping = {color[0]: color for color in colors if ord(color[0]) % 2 == 0}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 164,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'r': 'red', 'b': 'blue'}"
      ]
     },
     "execution_count": 164,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mapping"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As the dictionary comprehension is quite long, it is easier to read if it is split over multiple lines. The first line is the ```key```. The second line is the ```value```. The third line is the iterable being looped over and the fourth line is the expression:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 165,
   "metadata": {},
   "outputs": [],
   "source": [
    "mapping = {color[0]: \n",
    "           color \n",
    "           for color in colors\n",
    "           if ord(color[0]) % 2 == 0}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 166,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'r': 'red', 'b': 'blue'}"
      ]
     },
     "execution_count": 166,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mapping"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```dict``` comprehension can also use an ```if``` and ```else``` expression. These statements can be set for both the ```keys``` and the ```values``` as shown in the example below. The ```if``` condition takes the first letter of the ```color``` for the ```key``` and the ```color``` for the ```value``` when the ordinal ```value``` of the first letter is even. The ```else``` condition takes the last letter of the ```color``` for the ```key``` and reverses the ```color``` for the ```value```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 167,
   "metadata": {},
   "outputs": [],
   "source": [
    "mapping = {color[0] if ord(color[0]) % 2 == 0 else color[-1]: \n",
    "           color if ord(color[0]) % 2 == 0 else color[::-1]\n",
    "           for color in colors}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 168,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'r': 'red', 'n': 'neerg', 'b': 'blue'}"
      ]
     },
     "execution_count": 168,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mapping"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is quite common to keep all ```keys``` and use only a condition for the ```values```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 169,
   "metadata": {},
   "outputs": [],
   "source": [
    "mapping = {color[0]: \n",
    "           color if ord(color[0]) % 2 == 0 else color[::-1]\n",
    "           for color in colors}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 170,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'r': 'red', 'g': 'neerg', 'b': 'blue'}"
      ]
     },
     "execution_count": 170,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mapping"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A ```dict``` comprehension can use the ```items``` identifier of an existing ```dict``` giving access to the original ```dict``` ```keys``` and ```values``` using ```tuple``` unpacking. For example, supposing the following ```dict``` of ```fruits``` is made:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 171,
   "metadata": {},
   "outputs": [],
   "source": [
    "fruits = {'apples': 2, 'bananas': 3, 'carrots': 5}"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A ```dict``` instance ```fruits2``` which has the same ```keys``` and doubles the numeric ```values``` can be created using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 172,
   "metadata": {},
   "outputs": [],
   "source": [
    "fruits2 = {key: \n",
    "           2 * value \n",
    "           for key, value in fruits.items()}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 173,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'apples': 4, 'bananas': 6, 'carrots': 10}"
      ]
     },
     "execution_count": 173,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fruits2"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And in such a scenario it is common to include all ```keys``` and update the ```value``` in response to a condition. For example, the ```value``` can be doubled if it is odd and left alone if it is even. This creates a ```dict``` instance of even values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 174,
   "metadata": {},
   "outputs": [],
   "source": [
    "fruits3 = {key: \n",
    "           2 * value if value % 2 == 1 else value \n",
    "           for key, value in fruits.items()}"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Functions"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using Inbuilt Functions Recap"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Many inbuilt functions have already been used. However before looking at creating a custom function, the ```ord``` function will be examined. Recall if the function ```ord``` is input without parenthesis that it is referenced:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 175,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function ord(c, /)>"
      ]
     },
     "execution_count": 175,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ord"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Its docstring can be viewed using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 176,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mSignature:\u001b[0m \u001b[0mord\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mc\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m Return the Unicode code point for a one-character string.\n",
       "\u001b[1;31mType:\u001b[0m      builtin_function_or_method"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "ord?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "From the docstring, it can be seen that the function has a single input argument denoted ```c``` that is positional. Recall all input arguments before an ```/``` are to be specified positionally:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 177,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "97"
      ]
     },
     "execution_count": 177,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ord('a')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The docstring also mentions a ```return``` value. When the function call is not assigned to a variable, it is returned to the cell output."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the function call is instead assigned to a variable, it is returned to the variable name. Notice that the value no longer displays in the cell output:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 178,
   "metadata": {},
   "outputs": [],
   "source": [
    "value = ord('a')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It can be seen using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 179,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "97"
      ]
     },
     "execution_count": 179,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```value``` is assigned to an instance of the ```int``` class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 180,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "int"
      ]
     },
     "execution_count": 180,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "type(value)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```ord``` function has one positional input argument and 1 ```return``` value."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```print``` function can likewise be referenced:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 181,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function print(*args, sep=' ', end='\\n', file=None, flush=False)>"
      ]
     },
     "execution_count": 181,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "print"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If its docstring is examined, it can be seen that the ```print``` function has ```*args``` which means that it can take a variable number of input arguments. It also has the keyword input arguments ```sep```, ```end```, ```file``` and ```flush``` which all have default values. When these keyword input arguments are not specified the default values will be used. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 182,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mSignature:\u001b[0m \u001b[0mprint\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m*\u001b[0m\u001b[0margs\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0msep\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;34m' '\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mend\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;34m'\\n'\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mfile\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;32mNone\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mflush\u001b[0m\u001b[1;33m=\u001b[0m\u001b[1;32mFalse\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m\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",
       "\u001b[1;31mType:\u001b[0m      builtin_function_or_method"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "print?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that there is no mention of a return statement in the ```print``` function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 183,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello world\n"
     ]
    }
   ],
   "source": [
    "empty = print('hello', 'world')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 184,
   "metadata": {},
   "outputs": [],
   "source": [
    "empty"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 185,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 185,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "empty == None"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that the ```print``` function always prints. When it is assigned to a variable, text is printed to the cell output. Notice this text uses a space as a separator ```sep=' '``` and ends on a new line ```end='\\n'```. The variable empty has the value ```NoneType``` as the ```print``` function has no ```return``` statement."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The effect of multiple input arguments can be seen:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 186,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    }
   ],
   "source": [
    "print()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 187,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello\n"
     ]
    }
   ],
   "source": [
    "print('hello')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 188,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello world\n"
     ]
    }
   ],
   "source": [
    "print('hello', 'world')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 189,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "good morning world\n"
     ]
    }
   ],
   "source": [
    "print('good', 'morning', 'world')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once again notice this text uses a space as a separator ```sep=' '``` and ends on a new line ```end='\\n'```."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The effect of modifying the ```sep``` and ```end``` input arguments can be seen using multiple ```print``` statements:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 190,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello world\n",
      "hello world\n",
      "hello\tworld\n",
      "hello worldhello world\n",
      "bye worldld\n"
     ]
    }
   ],
   "source": [
    "print('hello', 'world')\n",
    "print('hello', 'world', sep=' ', end='\\n')\n",
    "print('hello', 'world', sep='\\t')\n",
    "print('hello', 'world', end='')\n",
    "print('hello', 'world')\n",
    "print('hello', 'world', end='\\r')\n",
    "print('bye', 'world')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The file keyword input argument has a default value of ```None``` which means the output is printed to the cell output. A file can be opened and data can be saved to the file using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 191,
   "metadata": {},
   "outputs": [],
   "source": [
    "textfile = open('text.txt', 'w')\n",
    "print('hello', 'world', file=textfile)\n",
    "textfile.close()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The text file created can be examined: [textfile.txt](text.txt)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The effect of the keyword input argument ```flush``` can be seen when a small time delay is introduced:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 192,
   "metadata": {},
   "outputs": [],
   "source": [
    "from time import sleep"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the following, the printed ```0``` will appear to change to ```1``` once as the text isn't flushed and is more slowly updated:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 193,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1\r"
     ]
    }
   ],
   "source": [
    "for index in range(10):\n",
    "    print(0, end='', flush=False)\n",
    "    print('\\r', end='', flush=False)\n",
    "    sleep(0.1)\n",
    "    print(1, end='', flush=False)\n",
    "    print('\\r', end='', flush=False)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the following, the printed ```0``` and ```1``` will be observed to quickly toggle as the text has been flushed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 194,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1\r"
     ]
    }
   ],
   "source": [
    "for index in range(10):\n",
    "    print(0, end='', flush=True)\n",
    "    print('\\r', end='', flush=True)\n",
    "    sleep(0.1)\n",
    "    print(1, end='', flush=True)\n",
    "    print('\\r', end='', flush=True)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Integer division and the associated modulus can be carried out using the ```//``` and ```%``` operators respectively:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 195,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 195,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "3 // 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 196,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 196,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "3 % 2"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Both these operations are carried out in the ```divmod``` function. The ```divmod``` function can be referenced:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 197,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function divmod(x, y, /)>"
      ]
     },
     "execution_count": 197,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "divmod"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Its docstring can be examined:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 198,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mSignature:\u001b[0m \u001b[0mdivmod\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mx\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0my\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m Return the tuple (x//y, x%y).  Invariant: div*y + mod == x.\n",
       "\u001b[1;31mType:\u001b[0m      builtin_function_or_method"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "divmod?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice it has the two positional input arguments ```x``` and ```y```. The ```return``` value is a ```tuple``` which has the form ```(x//y, x%y)```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 199,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(1, 1)"
      ]
     },
     "execution_count": 199,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "divmod(3, 2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function call can be assigned to a ```tuple``` of variables:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 200,
   "metadata": {},
   "outputs": [],
   "source": [
    "(quotient, remainder) = divmod(3, 2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is normally done shorthand using ```tuple``` unpacking:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 201,
   "metadata": {},
   "outputs": [],
   "source": [
    "quotient, remainder = divmod(3, 2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The license function can be referenced using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 202,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "See https://www.python.org/psf/license/"
      ]
     },
     "execution_count": 202,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "license"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Its docstring can be examined:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 203,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mSignature:\u001b[0m   \u001b[0mlicense\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mType:\u001b[0m        _Printer\n",
       "\u001b[1;31mString form:\u001b[0m See https://www.python.org/psf/license/\n",
       "\u001b[1;31mNamespace:\u001b[0m   Python builtin\n",
       "\u001b[1;31mFile:\u001b[0m        c:\\users\\phili\\anaconda3\\envs\\vscode-env\\lib\\_sitebuiltins.py\n",
       "\u001b[1;31mDocstring:\u001b[0m  \n",
       "interactive prompt objects for printing the license text, a list of\n",
       "contributors and the copyright notice."
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "license?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It has no input arguments or ```return``` value. It can be called using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 204,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "See https://www.python.org/psf/license/\n"
     ]
    }
   ],
   "source": [
    "license()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the function is called and assigned to a variable, the variable has the value ```NoneType``` because this function has no ```return``` statement:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 205,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "See https://www.python.org/psf/license/\n"
     ]
    }
   ],
   "source": [
    "eula = license()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 206,
   "metadata": {},
   "outputs": [],
   "source": [
    "eula"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 207,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 207,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "eula == None"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Under the hood, this function effectively uses the ```print``` function to ```print``` a ```str```."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Defining a custom function"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that the features of ```builtins``` functions have been examined, a custom function can be explored. Instead of assignment, the ```def``` keyword is used followed by the functions name, in this case nothing. The functions name is followed by parenthesis, and these parenthesis contain input arguments, when the function has input arguments. After the parenthesis is a colon ```:``` which is used to indicate the beginning of a code block. The functions code block usually ends in a ```return``` statement. The following function has no input arguments and no ```return``` statement:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 208,
   "metadata": {},
   "outputs": [],
   "source": [
    "def nothing():\n",
    "   return"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It can be referenced using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 209,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function __main__.nothing()>"
      ]
     },
     "execution_count": 209,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nothing"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "No docstring was supplied in the function, so none is shown. However the details show there is no input argument and no ```return``` statement:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 210,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mSignature:\u001b[0m \u001b[0mnothing\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m <no docstring>\n",
       "\u001b[1;31mFile:\u001b[0m      c:\\users\\phili\\appdata\\local\\temp\\ipykernel_6104\\1240757116.py\n",
       "\u001b[1;31mType:\u001b[0m      function"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "nothing?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function can be called using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 211,
   "metadata": {},
   "outputs": [],
   "source": [
    "nothing()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice there is no cell output as there is no ```return``` statement. When the function call is assigned to a variable, its value will be ```NoneType```:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 212,
   "metadata": {},
   "outputs": [],
   "source": [
    "empty = nothing()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 213,
   "metadata": {},
   "outputs": [],
   "source": [
    "empty"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 214,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 214,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "empty == None"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Input Argument and Return Value"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another function can be created, that takes in a singular word, and returns the plural of it: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 215,
   "metadata": {},
   "outputs": [],
   "source": [
    "def plural(word):\n",
    "   return word + 's'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This function can be referenced:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 216,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function __main__.plural(word)>"
      ]
     },
     "execution_count": 216,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plural"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And its docstring can be examined:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 217,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mSignature:\u001b[0m \u001b[0mplural\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mword\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m <no docstring>\n",
       "\u001b[1;31mFile:\u001b[0m      c:\\users\\phili\\appdata\\local\\temp\\ipykernel_6104\\2502655467.py\n",
       "\u001b[1;31mType:\u001b[0m      function"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "plural?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This shows the expected input arguments. Once again, there is no docstring. "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Function docstring"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A docstring is included in triple double quotes. Triple double quotes are used even if it is a single line comment as docstrings are often written briefly during development and padded out later. Having the triple quotations makes it easier to expand to a multi-line string and having triple double quotations makes it easier to include a string literal:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 218,
   "metadata": {},
   "outputs": [],
   "source": [
    "def plural(word):\n",
    "    \"\"\"Takes a singular str word and returns its plural.\"\"\"\n",
    "    return word + 's'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If triple double quotes are input, below a functions definition the VSCode IDE for example will display a list of identifiers and that include Generate Docstring. Convert the raw cell into a Python cell. Delete the quotations and select Generate Docstring:\n",
    "\n",
    "```python\n",
    "def plural(word):\n",
    "    \"\"\"\n",
    "    return word + 's'\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This gives:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 219,
   "metadata": {},
   "outputs": [],
   "source": [
    "def plural(word):\n",
    "    \"\"\"_summary_\n",
    "\n",
    "    Args:\n",
    "        word (_type_): _description_\n",
    "\n",
    "    Returns:\n",
    "        _type_: _description_\n",
    "    \"\"\"\n",
    "    return word + 's'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be filled in using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 220,
   "metadata": {},
   "outputs": [],
   "source": [
    "def plural(word):\n",
    "    \"\"\"Takes a singular str word and returns its plural. \n",
    "    e.g. 'apple' becomes 'apples'\n",
    "\n",
    "    Args:\n",
    "        word (str): singular str\n",
    "\n",
    "    Returns:\n",
    "        str: plural str\n",
    "    \"\"\"\n",
    "    return word + 's'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now its docstring can be examined:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 221,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mSignature:\u001b[0m \u001b[0mplural\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mword\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m\n",
       "Takes a singular str word and returns its plural. \n",
       "e.g. 'apple' becomes 'apples'\n",
       "\n",
       "Args:\n",
       "    word (str): singular str\n",
       "\n",
       "Returns:\n",
       "    str: plural str\n",
       "\u001b[1;31mFile:\u001b[0m      c:\\users\\phili\\appdata\\local\\temp\\ipykernel_6104\\3050588541.py\n",
       "\u001b[1;31mType:\u001b[0m      function"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "plural?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function can be run using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 222,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'apples'"
      ]
     },
     "execution_count": 222,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plural('apple')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 223,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'bananas'"
      ]
     },
     "execution_count": 223,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plural('banana')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 224,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'apples'"
      ]
     },
     "execution_count": 224,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plural(word='apple')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 225,
   "metadata": {},
   "outputs": [],
   "source": [
    "fruits = plural('apple')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If no input arguments are supplied or too many, a TypeError will display:\n",
    "\n",
    "```python\n",
    "plural()\n",
    "```\n",
    "\n",
    "```python\n",
    "plural('apple', 'banana')\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another TypeError will display if the input argument is the wrong data type:\n",
    "\n",
    "```python\n",
    "plural(2)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Positional Only Input Arguments"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Input arguments have a named parameter by default. During a function call input arguments can be specified positionally or they can be specified by assigning the named parameter to a default value. Adding a ```/``` to a functions input arguments mandates that the input arguments that come the / can only be specified positionally during a function call i.e. the named parameter cannot be used during the function call. This syntax is typically used for the functions in builtins including the methods defined in builtins classes as seen in the previous tutorials. In this use case, the name of the function makes it pretty obvious what a positional input argument is used for and enforcing this syntax makes the code easier to read and faster to write. In other use cases the use of named parameters may be preferable for functions where it is not obvious from the function name what the named parameter does. Having an appropriate named parameter therefore can make the code more readable:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 226,
   "metadata": {},
   "outputs": [],
   "source": [
    "def plural(word, /):\n",
    "    \"\"\"Takes a singular str word and returns its plural. \n",
    "    e.g. 'apple' becomes 'apples'\n",
    "\n",
    "    Args:\n",
    "        word (str): singular str\n",
    "\n",
    "    Returns:\n",
    "        str: plural str\n",
    "    \"\"\"\n",
    "    return word + 's'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 227,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'apples'"
      ]
     },
     "execution_count": 227,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plural('apple')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following will show a ```TypeError```:\n",
    "\n",
    "```python\n",
    "plural(word='apple')\n",
    "```\n",
    "\n",
    "```plural()``` got some positional-only arguments passed as keyword arguments: ```'word'```."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Default Keyword Input Arguments"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An input argument can be supplied a default value:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 228,
   "metadata": {},
   "outputs": [],
   "source": [
    "def plural(word='apple'):\n",
    "    \"\"\"Takes a singular str word and returns its plural. \n",
    "    e.g. 'apple' becomes 'apples'\n",
    "\n",
    "    Args:\n",
    "        word (str): singular str\n",
    "\n",
    "    Returns:\n",
    "        str: plural str\n",
    "    \"\"\"\n",
    "    return word + 's'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The keyword can be supplied when the funciton is called and works similar to before:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 229,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'bananas'"
      ]
     },
     "execution_count": 229,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plural(word='banana')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If it is not supplied it takes on its default value:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 230,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'apples'"
      ]
     },
     "execution_count": 230,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plural()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once again if the / is added after the input argument it can only be provided positionally:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 231,
   "metadata": {},
   "outputs": [],
   "source": [
    "def plural(word='apple', /):\n",
    "    \"\"\"Takes a singular str word and returns its plural. \n",
    "    e.g. 'apple' becomes 'apples'\n",
    "\n",
    "    Args:\n",
    "        word (str): singular str\n",
    "\n",
    "    Returns:\n",
    "        str: plural str\n",
    "    \"\"\"\n",
    "    return word + 's'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The input argument word can be provided positionally:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 232,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'bananas'"
      ]
     },
     "execution_count": 232,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plural('banana')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When not provided positionally, it takes on its default value:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 233,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'apples'"
      ]
     },
     "execution_count": 233,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plural()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Asserting Input Argument Data Types"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In some cases using the wrong data type for a function will result in an error, in other cases, the wrong data types for input arguments may run but give an unexpected result. For this reason it is usually recommended to assert the data type of an input argument."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The assert statement is normally used with the isinstance function which returns a bool:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 234,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 234,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "isinstance('hello', str)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 235,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": 235,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "isinstance(2, str)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the assert statement is used with a value that is ```True```, the code runs as normal:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 236,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert isinstance('hello', str)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When it is used with a value that is ```False``` it raises an ```AssertionError```:\n",
    "\n",
    "```python\n",
    "assert isinstance(2, str)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": 237,
   "metadata": {},
   "outputs": [],
   "source": [
    "def plural(word='apple'):\n",
    "    \"\"\"Takes a singular str word and returns its plural. \n",
    "    e.g. 'apple' becomes 'apples'\n",
    "\n",
    "    Args:\n",
    "        word (str): singular str\n",
    "\n",
    "    Returns:\n",
    "        str: plural str\n",
    "    \"\"\"\n",
    "    assert isinstance(word, str)\n",
    "    return word + 's'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now the function works as normal when the data type is as expected:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 238,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'bananas'"
      ]
     },
     "execution_count": 238,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plural('banana')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And raises an ```AssertionError``` when the datatype is wrong:\n",
    "\n",
    "```python\n",
    "plural(2)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The Return Value Continued"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another function can be made that takes two numbers as input arguments and returns the highest number. This can have the form:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 239,
   "metadata": {},
   "outputs": [],
   "source": [
    "def higher(num1, num2):\n",
    "    if num1 > num2:\n",
    "        return num1\n",
    "    else:\n",
    "        return num2"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because a function does not continue after a return statement has been implemented. This is notmally simplified down to:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 240,
   "metadata": {},
   "outputs": [],
   "source": [
    "def higher(num1, num2):\n",
    "    if num1 > num2:\n",
    "        return num1\n",
    "    return num2"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Both input arguments should be asserted as numeric, this can be done by supplying a tuple of numeric datatypes to the isinstance function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 241,
   "metadata": {},
   "outputs": [],
   "source": [
    "def higher(num1, num2):\n",
    "    assert isinstance(num1, (int, float, bool))\n",
    "    assert isinstance(num2, (int, float, bool))\n",
    "    if num1 > num2:\n",
    "        return num1\n",
    "    return num2"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A docstring template can be inserted:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 242,
   "metadata": {},
   "outputs": [],
   "source": [
    "def higher(num1, num2):\n",
    "    \"\"\"_summary_\n",
    "\n",
    "    Args:\n",
    "        num1 (_type_): _description_\n",
    "        num2 (_type_): _description_\n",
    "\n",
    "    Returns:\n",
    "        _type_: _description_\n",
    "    \"\"\"\n",
    "    assert isinstance(num1, (int, float, bool))\n",
    "    assert isinstance(num2, (int, float, bool))\n",
    "    if num1 > num2:\n",
    "        return num1\n",
    "    return num2"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And filled in:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 243,
   "metadata": {},
   "outputs": [],
   "source": [
    "def higher(num1, num2, /):\n",
    "    \"\"\"Returns the highest numeric value from num1 and num2.\n",
    "\n",
    "    Args:\n",
    "        num1 (int, float or bool): numeric value.\n",
    "        num2 (int, float or bool): numeric value.\n",
    "\n",
    "    Returns:\n",
    "        int, float or bool: numeric value\n",
    "    \"\"\"\n",
    "    assert isinstance(num1, (int, float, bool))\n",
    "    assert isinstance(num2, (int, float, bool))\n",
    "    if num1 > num2:\n",
    "        return num1\n",
    "    return num2"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function can be referenced using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 244,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function __main__.higher(num1, num2, /)>"
      ]
     },
     "execution_count": 244,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "higher"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Its docstring can be examined:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 245,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mSignature:\u001b[0m \u001b[0mhigher\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mnum1\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mnum2\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m/\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m\n",
       "Returns the highest numeric value from num1 and num2.\n",
       "\n",
       "Args:\n",
       "    num1 (int, float or bool): numeric value.\n",
       "    num2 (int, float or bool): numeric value.\n",
       "\n",
       "Returns:\n",
       "    int, float or bool: numeric value\n",
       "\u001b[1;31mFile:\u001b[0m      c:\\users\\phili\\appdata\\local\\temp\\ipykernel_6104\\1591613221.py\n",
       "\u001b[1;31mType:\u001b[0m      function"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "higher?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It can be called with the following numeric values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 246,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 246,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "higher(1, 2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 247,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3.14"
      ]
     },
     "execution_count": 247,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "higher(3.14, 2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If an incorrect datatype is supplied, there will be an ```AssertionError```. If the incorrect number of input arguments are supplied, there will be a ```TypeError```. This function can take in ```num1``` and ```num2``` as positional input arguments or keyword arguments.\n",
    "\n",
    "If ```num1``` and ```num2``` are provided as named keyword input arguments there will be a TypeError because ```/``` is placed after the input arguments."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A function terminates at its return statement. For example. Anything past the first executed return statement is ignored:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 248,
   "metadata": {},
   "outputs": [],
   "source": [
    "def one():\n",
    "    return 1\n",
    "    return 2\n",
    "    return 3"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 249,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 249,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "one()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If no ```return``` statement is added, there is no ```return``` value:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 250,
   "metadata": {},
   "outputs": [],
   "source": [
    "def calc_something():\n",
    "    1 + 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 251,
   "metadata": {},
   "outputs": [],
   "source": [
    "calc_something()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In other words, the following are equivalent:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 252,
   "metadata": {},
   "outputs": [],
   "source": [
    "def calc_something():\n",
    "    1 + 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 253,
   "metadata": {},
   "outputs": [],
   "source": [
    "def calc_something():\n",
    "    1 + 2\n",
    "    return"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 254,
   "metadata": {},
   "outputs": [],
   "source": [
    "def calc_something():\n",
    "    1 + 2\n",
    "    return None"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A function can ```return``` a ```Collection```. The most common ```Collection``` to ```return``` is a ```tuple``` because it is immutable:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 255,
   "metadata": {},
   "outputs": [],
   "source": [
    "def singular(word='apples', /):\n",
    "    \"\"\"Takes a plural word and returns its singular value. \n",
    "    e.g. 'apple' becomes ('apple', 's').\n",
    "\n",
    "    Args:\n",
    "        word (str, optional): Plural str. Defaults to 'apples'.\n",
    "\n",
    "    Returns:\n",
    "        tuple: tuple of singular str and value.\n",
    "    \"\"\"\n",
    "    assert isinstance(word, str)\n",
    "    return word[:-1], word[-1]"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A tuple is normally returned using ```tuple``` unpacking. This means the ```return``` statement ```return word[:-1], word[-1]``` is simplified and the ```tuple``` is not explicitly specified ```return (word[:-1], word[-1])```."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 256,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('apple', 's')"
      ]
     },
     "execution_count": 256,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "singular()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 257,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('banana', 's')"
      ]
     },
     "execution_count": 257,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "singular('bananas')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These can be assigned to variables using ```tuple``` unpacking:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 258,
   "metadata": {},
   "outputs": [],
   "source": [
    "(word, letter_s) = singular('bananas')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 259,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'banana'"
      ]
     },
     "execution_count": 259,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "word"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 260,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'s'"
      ]
     },
     "execution_count": 260,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "letter_s"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Which is more commonly done without the parenthesis:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 261,
   "metadata": {},
   "outputs": [],
   "source": [
    "word, letter_s = singular('bananas')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 262,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'banana'"
      ]
     },
     "execution_count": 262,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "word"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 263,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'s'"
      ]
     },
     "execution_count": 263,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "letter_s"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Function Local Scope and Mutability"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Functions have their own local scope. This can be examined with the following. The local variable ```x``` assigned in the function does not alter the global variable ```x``` (seen on the Variable Inspector, after the function call):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 264,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = 2\n",
    "\n",
    "def local_variable():\n",
    "    x = 4\n",
    "    return x\n",
    "\n",
    "\n",
    "y = local_variable()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Although a function has its own local variables, it can access global variables:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 265,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = 2\n",
    "\n",
    "def read_global_variable():\n",
    "    return x\n",
    "\n",
    "\n",
    "y = read_global_variable()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If an immutable variable is accessed from the global namespace and reassignment is attempted in the functions local namespace, an ```UnboundLocalError``` will display:\n",
    "\n",
    "```python\n",
    "x = 2\n",
    "\n",
    "def unbound_local():\n",
    "    x += 2\n",
    "\n",
    "\n",
    "unbound_local()\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The global variable can be modified in the function by use of the global statement:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 266,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = 2\n",
    "\n",
    "def updateglobalvariable():\n",
    "    global x\n",
    "    x += 2\n",
    "\n",
    "\n",
    "updateglobalvariable()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 267,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "4"
      ]
     },
     "execution_count": 267,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "x"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Care should be taken when the variable is mutable. If a mutable method is used, it will modify the global mutable variable. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 268,
   "metadata": {},
   "outputs": [],
   "source": [
    "active = [1, 2, 3, 4]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 269,
   "metadata": {},
   "outputs": [],
   "source": [
    "def updateactive():\n",
    "    active.append(5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 270,
   "metadata": {},
   "outputs": [],
   "source": [
    "updateactive() "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 271,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, 2, 3, 4, 5]"
      ]
     },
     "execution_count": 271,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "active"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that when a mutable variable is returned to a new value using a function, that an alias of it is made:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 272,
   "metadata": {},
   "outputs": [],
   "source": [
    "active = [1, 2, 3, 4]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 273,
   "metadata": {},
   "outputs": [],
   "source": [
    "def returnactive(data):\n",
    "    return data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 274,
   "metadata": {},
   "outputs": [],
   "source": [
    "active2 = returnactive(active)  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 275,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 275,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "active2 is active"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 276,
   "metadata": {},
   "outputs": [],
   "source": [
    "active2.append(5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 277,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, 2, 3, 4, 5]"
      ]
     },
     "execution_count": 277,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "active2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 278,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, 2, 3, 4, 5]"
      ]
     },
     "execution_count": 278,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "active"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be prevented by creating a copy or deepcopy as appropriate:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 279,
   "metadata": {},
   "outputs": [],
   "source": [
    "active = [1, 2, 3, 4]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 280,
   "metadata": {},
   "outputs": [],
   "source": [
    "def returnactive(data):\n",
    "    return data.copy()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 281,
   "metadata": {},
   "outputs": [],
   "source": [
    "active2 = returnactive(active) "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 282,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": 282,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "active2 is active"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 283,
   "metadata": {},
   "outputs": [],
   "source": [
    "active2.append(5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 284,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, 2, 3, 4, 5]"
      ]
     },
     "execution_count": 284,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "active2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 285,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, 2, 3, 4]"
      ]
     },
     "execution_count": 285,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "active"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### *args and **kwargs"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Returning to the function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 286,
   "metadata": {},
   "outputs": [],
   "source": [
    "def higher(num1, num2, /):\n",
    "    assert isinstance(num1, (int, float, bool))\n",
    "    assert isinstance(num2, (int, float, bool))\n",
    "    if num1 > num2:\n",
    "        return num1\n",
    "    return num2"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that there are two positional input arguments. These can be provided from a tuple of two numbers:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 287,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = (3, 2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To unpack the tuple during the function call, it can be prefixed with a *:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 288,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 288,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "higher(*nums)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function can be modified to take in keyword input arguments instead that have default values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 289,
   "metadata": {},
   "outputs": [],
   "source": [
    "def higher(num1=1, num2=2):\n",
    "    assert isinstance(num1, (int, float, bool))\n",
    "    assert isinstance(num2, (int, float, bool))\n",
    "    if num1 > num2:\n",
    "        return num1\n",
    "    return num2"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A dictionary with keys that match the keyword input arguments of the function can be used:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 290,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = {'num1': 3, 'num2': 1}"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To unpack the dict during the function call, it can be prefixed with a **:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 291,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 291,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "higher(**nums)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This syntax can be used to create a function that has a variable number of input arguments. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 292,
   "metadata": {},
   "outputs": [],
   "source": [
    "def customsum(*args):\n",
    "    \"\"\"returns the sum of a variable number of \n",
    "    numeric input arguments.\n",
    "\n",
    "    Returns:\n",
    "        numeric: numeric sum\n",
    "    \"\"\"\n",
    "    total = 0\n",
    "    for num in args:\n",
    "        assert isinstance(num, (int, float, bool))\n",
    "        total += num\n",
    "    return total"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be called with a variable number of input arguments:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 293,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 293,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "customsum()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 294,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 294,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "customsum(1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 295,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "10"
      ]
     },
     "execution_count": 295,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "customsum(1, 2, 3, 4)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A similar implementation can be carried out using **kwargs:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 296,
   "metadata": {},
   "outputs": [],
   "source": [
    "def customsum(**kwargs):\n",
    "    \"\"\"returns the sum of a variable number of numeric\n",
    "    keyword input arguments.\n",
    "\n",
    "    Returns:\n",
    "        numeric: numeric sum\n",
    "    \"\"\"\n",
    "    total = 0\n",
    "    for key in kwargs:\n",
    "        assert isinstance(kwargs[key], (int, float, bool))\n",
    "        total += kwargs[key]\n",
    "    return total"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 297,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "10"
      ]
     },
     "execution_count": 297,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "customsum(one=1, two=2, three=3, four=4)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Yield and Generators"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Recall that a function can only use one return statement:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 298,
   "metadata": {},
   "outputs": [],
   "source": [
    "def fun():\n",
    "    return 'hello1'\n",
    "    return 'hello2'\n",
    "    return 'hello3'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function can be referenced:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 299,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function __main__.fun()>"
      ]
     },
     "execution_count": 299,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fun"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And called:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 300,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'hello1'"
      ]
     },
     "execution_count": 300,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fun()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If called again, the execution in the function starts from the top and first return statement is returned again:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 301,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'hello1'"
      ]
     },
     "execution_count": 301,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fun()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A yield statement can be used instead of a return statement resulting in a generator opposed to a function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 302,
   "metadata": {},
   "outputs": [],
   "source": [
    "def gen():\n",
    "    yield 'hello1'\n",
    "    yield 'hello2'\n",
    "    yield 'hello3'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be referenced as normal:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 303,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function __main__.gen()>"
      ]
     },
     "execution_count": 303,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "gen"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And when it is called, a generator object is instantiated from the generator:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 304,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<generator object gen at 0x00000250A43BB690>"
      ]
     },
     "execution_count": 304,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "gen()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A generator object is an iterator and yields the value at each yield statement when next is called:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 305,
   "metadata": {},
   "outputs": [],
   "source": [
    "go = gen()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 306,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'hello1'"
      ]
     },
     "execution_count": 306,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 307,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'hello2'"
      ]
     },
     "execution_count": 307,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 308,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'hello3'"
      ]
     },
     "execution_count": 308,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This happens until all yield statements have been exhausted at which point the generator is exhausted."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is common to use a yield statement in a loop:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 309,
   "metadata": {},
   "outputs": [],
   "source": [
    "def incrementer(num=0):\n",
    "    \"\"\"Increments integer values from num (inclusive) to num + 5 (exclusive)\n",
    "\n",
    "    Args:\n",
    "        num (int, optional): Start value. Defaults to 0.\n",
    "\n",
    "    Yields:\n",
    "        num: number yielded at each iteration.\n",
    "    \"\"\"\n",
    "    for index in range(5):\n",
    "        yield num\n",
    "        num += 1"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A generator object can be instantiated with a start num of 0:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 310,
   "metadata": {},
   "outputs": [],
   "source": [
    "go = incrementer()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 311,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 311,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 312,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 312,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 313,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 313,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 314,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 314,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 315,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "4"
      ]
     },
     "execution_count": 315,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It can also be instantiated with a start num of 3:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 316,
   "metadata": {},
   "outputs": [],
   "source": [
    "go = incrementer(num=3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 317,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 317,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 318,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "4"
      ]
     },
     "execution_count": 318,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 319,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5"
      ]
     },
     "execution_count": 319,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 320,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "6"
      ]
     },
     "execution_count": 320,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 321,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "7"
      ]
     },
     "execution_count": 321,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Both of these are finite and can be cast into a tuple:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 322,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(0, 1, 2, 3, 4)"
      ]
     },
     "execution_count": 322,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(incrementer())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 323,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(3, 4, 5, 6, 7)"
      ]
     },
     "execution_count": 323,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(incrementer(num=3))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If a while loop is however used:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 324,
   "metadata": {},
   "outputs": [],
   "source": [
    "def infincrementer(num=0):\n",
    "    \"\"\"Increments integer values from num (inclusive) to infinity.\n",
    "\n",
    "    Args:\n",
    "        num (int, optional): Start value. Defaults to 0.\n",
    "\n",
    "    Yields:\n",
    "        num: number yielded at each iteration.\n",
    "    \"\"\"\n",
    "    while True:\n",
    "        yield num\n",
    "        num += 1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 325,
   "metadata": {},
   "outputs": [],
   "source": [
    "go = infincrementer()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 326,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 326,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 327,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 327,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 328,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 328,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 329,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 329,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 330,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "4"
      ]
     },
     "execution_count": 330,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 331,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5"
      ]
     },
     "execution_count": 331,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 332,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "6"
      ]
     },
     "execution_count": 332,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because this is infinite it cannot be case into a tuple, as that would require infinite memory! The generator object itself does not require infinite memory as it only yields one value at a time. "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The code in the generator is executed by the generator object until the next yield statement when next is used on the generator object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 333,
   "metadata": {},
   "outputs": [],
   "source": [
    "def gen(num=0):\n",
    "    print(num)\n",
    "    yield 'hello1'\n",
    "\n",
    "    num += 1\n",
    "    print(num)    \n",
    "    yield 'hello2'\n",
    "    \n",
    "    num += 2\n",
    "    print(num)\n",
    "    yield 'hello3'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the generator expression is instantiated:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 334,
   "metadata": {},
   "outputs": [],
   "source": [
    "go = gen()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The variable num and the print statement involving num are execured above each yield statement. Notice the previous value of num was remembered and is incremented:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 335,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "'hello1'"
      ]
     },
     "execution_count": 335,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 336,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "'hello2'"
      ]
     },
     "execution_count": 336,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 337,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "'hello3'"
      ]
     },
     "execution_count": 337,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(go)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### First Order Function"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following function, takes a name as an input argument and returns a formatted string including."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 338,
   "metadata": {},
   "outputs": [],
   "source": [
    "def greeting(name):\n",
    "    \"\"\"prints greeting for supplied name\n",
    "\n",
    "    Args:\n",
    "        name (str): name\n",
    "\n",
    "    Returns:\n",
    "        str: customised greeting for name\n",
    "    \"\"\"\n",
    "    assert isinstance(name, str)\n",
    "    return f'Hello {name}'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Recall that a function can be referenced using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 339,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function __main__.greeting(name)>"
      ]
     },
     "execution_count": 339,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "greeting"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A function is a first order object. This means the function can be treated as a variable and assigned to another variable name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 340,
   "metadata": {},
   "outputs": [],
   "source": [
    "f = greeting"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This means f is an alias for greeting:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 341,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 341,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "f is greeting"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "f can now be referenced, and the same object as before displays because f is an alias for greeting:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 342,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function __main__.greeting(name)>"
      ]
     },
     "execution_count": 342,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "f"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And the docstring can be accessed using the alias f:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 343,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mSignature:\u001b[0m \u001b[0mf\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mname\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m\n",
       "prints greeting for supplied name\n",
       "\n",
       "Args:\n",
       "    name (str): name\n",
       "\n",
       "Returns:\n",
       "    str: customised greeting for name\n",
       "\u001b[1;31mFile:\u001b[0m      c:\\users\\phili\\appdata\\local\\temp\\ipykernel_6104\\3500371954.py\n",
       "\u001b[1;31mType:\u001b[0m      function"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "f?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function can also be called using the alias f:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 344,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Hello world'"
      ]
     },
     "execution_count": 344,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "f('world')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 345,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Hello earth'"
      ]
     },
     "execution_count": 345,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "f('earth')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Recall that f and greeting are 2 references to the same object. These references or variable names can be conceptualised as labels affixed to the object. Using del on a variable name can be conceptualised as deleting the label and does not change the object. Deleting the variable name greeting for example will delete the label greeting however the object can still be accessed using f:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 346,
   "metadata": {},
   "outputs": [],
   "source": [
    "del greeting"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 347,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function __main__.greeting(name)>"
      ]
     },
     "execution_count": 347,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "f"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Second-Order Function"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The first-order function greeting can be defined as before:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 348,
   "metadata": {},
   "outputs": [],
   "source": [
    "def greeting(name):\n",
    "    \"\"\"prints greeting for supplied name\n",
    "\n",
    "    Args:\n",
    "        name (str): name\n",
    "\n",
    "    Returns:\n",
    "        str: customised greeting for name\n",
    "    \"\"\"\n",
    "    assert isinstance(name, str)\n",
    "    return f'Hello {name}'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A second order function either takes in a function as an input argument or returns a function. The second order function second_input can be designed which takes in a function fun as an input argument."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 349,
   "metadata": {},
   "outputs": [],
   "source": [
    "def second_order(fun):\n",
    "    \"\"\"Takes in a function as an input argument\n",
    "    and does nothing with it.\n",
    "    \n",
    "    Args:\n",
    "        fun (function): input function\n",
    "    \"\"\"\n",
    "    assert callable(fun)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If this second_order function is called and provided a function as an input argument, the code will run, doing nothing. If another data type is supplied, an AssertionError will display:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 350,
   "metadata": {},
   "outputs": [],
   "source": [
    "second_order(greeting)"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "second_order(1)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice the function greeting is supplied as an input argument as a reference and is not called."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The second_order function can be modified to return the function being supplied:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 351,
   "metadata": {},
   "outputs": [],
   "source": [
    "def second_order(fun):\n",
    "    \"\"\"Takes in a function as an input argument\n",
    "    and does nothing with it.\n",
    "\n",
    "    Args:\n",
    "        fun (function): input function\n",
    "\n",
    "    Returns:\n",
    "        function: output function unmodified from input\n",
    "    \"\"\"\n",
    "    assert callable(fun)\n",
    "    return fun"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If this second_order function is called and provided a function as an input argument, the code will run, returning the function as a reference:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 352,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function __main__.greeting(name)>"
      ]
     },
     "execution_count": 352,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "second_order(greeting)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To call the returned function greeting, a second set of parenthesis enclosing an input argument can be supplied:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 353,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Hello world'"
      ]
     },
     "execution_count": 353,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "second_order(greeting)('world')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Closures"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the above section it was seen that a function can be used as an input argument for another function. It is also possible to define a function wthin a function."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An inner function can be defined within an outer function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 354,
   "metadata": {},
   "outputs": [],
   "source": [
    "def outer():\n",
    "    def inner():\n",
    "        return\n",
    "    return"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The return statement of the outer function can be used to return the function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 355,
   "metadata": {},
   "outputs": [],
   "source": [
    "def outer():\n",
    "    def inner():\n",
    "        return\n",
    "    return inner"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because the inner function is defined within the local scope of the outer function it can access variables within the outer functions scope:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 356,
   "metadata": {},
   "outputs": [],
   "source": [
    "def outer():\n",
    "    name = 'world'\n",
    "    def inner():\n",
    "        return f'hello {name}'\n",
    "    return inner"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "outer can be referenced:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 357,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function __main__.outer()>"
      ]
     },
     "execution_count": 357,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "outer"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "outer can be called to return inner:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 358,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function __main__.outer.<locals>.inner()>"
      ]
     },
     "execution_count": 358,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "outer()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And inner can be called:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 359,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'hello world'"
      ]
     },
     "execution_count": 359,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "outer()()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More generally, outer would be called and assigned to a variable name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 360,
   "metadata": {},
   "outputs": [],
   "source": [
    "fun_in = outer()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then this variable name which is assigned to a function would be called:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 361,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'hello world'"
      ]
     },
     "execution_count": 361,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fun_in()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's modify the above code so an input argument name is requested by the outer function. This input argument is accessible by the inner function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 362,
   "metadata": {},
   "outputs": [],
   "source": [
    "def outer(name):\n",
    "    def inner():\n",
    "        return f'hello {name}'\n",
    "    return inner"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The outer function can be called and assigned to a variable name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 363,
   "metadata": {},
   "outputs": [],
   "source": [
    "fun_in = outer('world')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The variable 'world' was provided by the outer function which has finished executing but is now **enclosed** within the inner function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 364,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'hello world'"
      ]
     },
     "execution_count": 364,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fun_in()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 365,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'hello world'"
      ]
     },
     "execution_count": 365,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fun_in()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For this reason, the configuration above is known as a **closure** as variables provided from the outer function can be enclosed within the inner function."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In HTML the following tags \\<p\\> and \\<\\\\p\\> are used to enclose a paragraph and \\<h1\\> and \\<\\\\h1\\> are used to enclose a heading of level 1."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A closure can be defined using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 366,
   "metadata": {},
   "outputs": [],
   "source": [
    "def html_tag(tag):\n",
    "    def html_text(text):\n",
    "        return f'<{tag}>{text}</{tag}>'\n",
    "    return html_text"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The outer html_tag function can be called using a provided tag."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 367,
   "metadata": {},
   "outputs": [],
   "source": [
    "para = html_tag('p')\n",
    "h1 = html_tag('h1')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This creates the inner function with an enclosed tag, which can be called providing text to format it using the enclosed tag:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 368,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'<h1>Twinkle, Twinkle, Little Star</h1>'"
      ]
     },
     "execution_count": 368,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "h1('Twinkle, Twinkle, Little Star')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 369,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'<p>Twinkle, twinkle, little star,</p>'"
      ]
     },
     "execution_count": 369,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "para('Twinkle, twinkle, little star,')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 370,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'<p>How I wonder what you are!</p>'"
      ]
     },
     "execution_count": 370,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "para('How I wonder what you are!')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 371,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'<p>Up above the world so high,</p>'"
      ]
     },
     "execution_count": 371,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "para('Up above the world so high,')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Decorators"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A decorator uses an outer function which contains an inner function. The outer function takes in an external function as its input argument. This external function is returned by the inner function which also contains additional code. The outer function returns the inner function. This configuration extends the behavior of the external function without explicitly modifying it and the additional code in the inner function decorates the external function: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 372,
   "metadata": {},
   "outputs": [],
   "source": [
    "def outer(external_function):\n",
    "    def inner():\n",
    "        print(f'calling the {external_function}')\n",
    "        return external_function\n",
    "    return inner"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A simple greeting function can be decorated:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 373,
   "metadata": {},
   "outputs": [],
   "source": [
    "def greeting():\n",
    "    \"\"\"generic greeting\n",
    "\n",
    "    Returns:\n",
    "        str: greeting hello\n",
    "    \"\"\"\n",
    "    return 'hello'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The decorator function can be called and assigned to an object name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 374,
   "metadata": {},
   "outputs": [],
   "source": [
    "greeting_decorated = outer(greeting)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "greeting_decorated which returns the inner function can be referenced using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 375,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function __main__.outer.<locals>.inner()>"
      ]
     },
     "execution_count": 375,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "greeting_decorated"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This inner function can be called using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 376,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "calling the <function greeting at 0x00000250A447AFC0>\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "<function __main__.greeting()>"
      ]
     },
     "execution_count": 376,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "greeting_decorated()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The inner function returns the external function which can be called:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 377,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "calling the <function greeting at 0x00000250A447AFC0>\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "'hello'"
      ]
     },
     "execution_count": 377,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "greeting_decorated()()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now if instead of referencing the external function within the inner function return statement, it is called:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 378,
   "metadata": {},
   "outputs": [],
   "source": [
    "def outer(external_function):\n",
    "    def inner():\n",
    "        print(f'calling the {external_function}')\n",
    "        return external_function()\n",
    "    return inner"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The external function, greeting is unchanged. Once again the outer function can be called and assigned to a variable name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 379,
   "metadata": {},
   "outputs": [],
   "source": [
    "greeting_decorated = outer(greeting)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It can be referenced:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 380,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function __main__.outer.<locals>.inner()>"
      ]
     },
     "execution_count": 380,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "greeting_decorated"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And called:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 381,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "calling the <function greeting at 0x00000250A447AFC0>\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "'hello'"
      ]
     },
     "execution_count": 381,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "greeting_decorated()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the above case, the external function greeting being decorated had no input arguments. In this example, an input argument name will be added:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 382,
   "metadata": {},
   "outputs": [],
   "source": [
    "def greeting(name):\n",
    "    \"\"\"custom greeting\n",
    "\n",
    "    Args:\n",
    "        name (str): name\n",
    "\n",
    "    Returns:\n",
    "        str: custom greeting\n",
    "    \"\"\"\n",
    "    assert isinstance(name, str)\n",
    "    return f'hello {name}'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To accommodate the input argument name, the return statement of the inner must provide the input argument when calling the external_function (line 4).In order to do so, the inner function itself must also be supplied the input argument name (line 2):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 383,
   "metadata": {},
   "outputs": [],
   "source": [
    "def outer(external_function):\n",
    "    def inner(name):\n",
    "        print(f'calling the {external_function}')\n",
    "        return external_function(name)\n",
    "    return inner"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More generally *args and **kwargs will be used to allow a generic number of positional and keyword input arguments into the inner function so that they can be supplied when calling the external_function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 384,
   "metadata": {},
   "outputs": [],
   "source": [
    "def outer(external_function):\n",
    "    def inner(*args, **kwargs):\n",
    "        print(f'calling the {external_function}')\n",
    "        return external_function(*args, **kwargs)\n",
    "    return inner"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The outer function can be called, supplying the external function greeting as an input argument and its function call assigned to a variable name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 385,
   "metadata": {},
   "outputs": [],
   "source": [
    "greeting_decorated = outer(greeting)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It can be referenced:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 386,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function __main__.outer.<locals>.inner(*args, **kwargs)>"
      ]
     },
     "execution_count": 386,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "greeting_decorated"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And called using an input argument name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 387,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "calling the <function greeting at 0x00000250A4498400>\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "'hello world'"
      ]
     },
     "execution_count": 387,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "greeting_decorated('world')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A new object name was created for the decorated function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 388,
   "metadata": {},
   "outputs": [],
   "source": [
    "greeting_decorated = outer(greeting)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Sometimes the name of the original function being decorated is reassigned:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 389,
   "metadata": {},
   "outputs": [],
   "source": [
    "greeting = outer(greeting)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Prefixing @outer above the function definition will also decorate it. With this syntax, the decorated function name will use the same name as the original function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 390,
   "metadata": {},
   "outputs": [],
   "source": [
    "@outer\n",
    "def greeting(name):\n",
    "    \"\"\"custom greeting\n",
    "\n",
    "    Args:\n",
    "        name (str): name\n",
    "\n",
    "    Returns:\n",
    "        str: custom greeting\n",
    "    \"\"\"\n",
    "    assert isinstance(name, str)\n",
    "    return f'hello {name}'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, when the function is called, it is decorated, which can be seen from the additional print statement:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 391,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "calling the <function greeting at 0x00000250A4499C60>\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "'hello world'"
      ]
     },
     "execution_count": 391,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "greeting('world')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Although the input arguments are passed through, the docstring is not:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 392,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mSignature:\u001b[0m \u001b[0mgreeting\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m*\u001b[0m\u001b[0margs\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m <no docstring>\n",
       "\u001b[1;31mFile:\u001b[0m      c:\\users\\phili\\appdata\\local\\temp\\ipykernel_6104\\126210478.py\n",
       "\u001b[1;31mType:\u001b[0m      function"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "greeting?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ```functools``` module groups together function tools. One of the tools is the wraps function which can be used as a decorator:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 393,
   "metadata": {},
   "outputs": [],
   "source": [
    "from functools import wraps"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 394,
   "metadata": {},
   "outputs": [],
   "source": [
    "def outer(external_function):\n",
    "    @wraps(external_function)\n",
    "    def inner(*args, **kwargs):\n",
    "        print(f'calling the {external_function}')\n",
    "        return external_function(*args, **kwargs)\n",
    "    return inner"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And rerunning:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 395,
   "metadata": {},
   "outputs": [],
   "source": [
    "@outer\n",
    "def greeting(name):\n",
    "    \"\"\"custom greeting\n",
    "\n",
    "    Args:\n",
    "        name (str): name\n",
    "\n",
    "    Returns:\n",
    "        str: custom greeting\n",
    "    \"\"\"\n",
    "    assert isinstance(name, str)\n",
    "    return f'hello {name}'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now shows the docstring of the function being decorated:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 396,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[1;31mSignature:\u001b[0m \u001b[0mgreeting\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mname\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
       "\u001b[1;31mDocstring:\u001b[0m\n",
       "custom greeting\n",
       "\n",
       "Args:\n",
       "    name (str): name\n",
       "\n",
       "Returns:\n",
       "    str: custom greeting\n",
       "\u001b[1;31mFile:\u001b[0m      c:\\users\\phili\\appdata\\local\\temp\\ipykernel_6104\\3555892485.py\n",
       "\u001b[1;31mType:\u001b[0m      function"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "greeting?"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the decorated function is called and supplied an input argument, the additional print statement that decorates the function shows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 397,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "calling the <function greeting at 0x00000250A449A840>\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "'hello world'"
      ]
     },
     "execution_count": 397,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "greeting('world')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The inner function is only used internally within the outer function. As a consequence both the outer and inner functions take on the same function name, with the inner prefixed with an underscore, recalling that a prefix with an underscore designates internal use. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 398,
   "metadata": {},
   "outputs": [],
   "source": [
    "def wrapper(external_function):\n",
    "    @wraps(external_function)\n",
    "    def _wrapper(*args, **kwargs):\n",
    "        print(f'calling the {external_function}')\n",
    "        return external_function(*args, **kwargs)\n",
    "    return _wrapper"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be used to wrap the external function as before:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 399,
   "metadata": {},
   "outputs": [],
   "source": [
    "@outer\n",
    "def greeting(name):\n",
    "    \"\"\"custom greeting\n",
    "\n",
    "    Args:\n",
    "        name (str): name\n",
    "\n",
    "    Returns:\n",
    "        str: custom greeting\n",
    "    \"\"\"\n",
    "    assert isinstance(name, str)\n",
    "    return f'hello {name}'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Calling the function and supplying an input argument, or examining the docstring works in the same manner as earlier:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 400,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "calling the <function greeting at 0x00000250A449B560>\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "'hello world'"
      ]
     },
     "execution_count": 400,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "greeting('world')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The lambda Expression"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The keyword lambda is taken from the Greek alphabet and lacks description for its use case in Python. lambda should be conceptualised as meaning *make anonymous function* as it is used to create a simple anonymous function over a single line. Because it is anonymous and expressed over a single line, it does not have a docstring."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's return to the basic implementation of the function plural without any assertions or docstring:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 401,
   "metadata": {},
   "outputs": [],
   "source": [
    "def plural(word):\n",
    "   return word + 's'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be re-expressed as a lambda expression:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 402,
   "metadata": {},
   "outputs": [],
   "source": [
    "plural = lambda word: word + 's'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The commonalities can be examined:\n",
    "\n",
    "* first of all is the function name plural\n",
    "* then the assignment operator = which can be thought of as being equivalent to the def keyword.\n",
    "* Next is the input arguments. In this example only 1 input argument is used. If more are used, they are seperated by using a , as a delimiter. Alternatively some functions do not have input arguments.\n",
    "* Next is the colon :. In the function it begins a code block. In the lambda expression, there is no code block and the code continues on the same line. In the lambda expression the colon : can also in some case be conceptualised as the seperation of the input arguments from the return statement, carrying out a similar purpose to splitting a key from a value in a Python dictionary.\n",
    "* Finally there is the return value. Not all functions have a return value, some functions call other functions such as print, which always prints and has no return value."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The lambda expression can be called in the same way as the equivalent function before:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 403,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'apples'"
      ]
     },
     "execution_count": 403,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plural('apple')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some lambda expressions are totally anonymous and aren't even assigned to a name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 404,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function __main__.<lambda>(word)>"
      ]
     },
     "execution_count": 404,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "lambda word: word + 's'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "They can be called without assignment on a single line:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 405,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'apples'"
      ]
     },
     "execution_count": 405,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(lambda word: word + 's')('apple')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Map"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A lambda expression is designed to take a scalar input argument and return a value which is calculated using that input argument:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 406,
   "metadata": {},
   "outputs": [],
   "source": [
    "square = lambda x: x ** 2"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Sometimes it is desired for a function to be invoked for every value in an iterable: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 407,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = (1, 2, 3, 4, 5)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The map function can be used to map a function to an iterable:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 408,
   "metadata": {},
   "outputs": [],
   "source": [
    "map_square_to_nums = map(square, nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 409,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<map at 0x250a4468df0>"
      ]
     },
     "execution_count": 409,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "map_square_to_nums"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This mapped object is essentially a generator and evaluates the value for each item in the sequence when next is invoked. More commonly it is cast into a sequence such as a tuple:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 410,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 410,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(map_square_to_nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 411,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "4"
      ]
     },
     "execution_count": 411,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(map_square_to_nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 412,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "9"
      ]
     },
     "execution_count": 412,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(map_square_to_nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 413,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "16"
      ]
     },
     "execution_count": 413,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(map_square_to_nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 414,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "25"
      ]
     },
     "execution_count": 414,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "next(map_square_to_nums)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This mapped object is essentially a generator and evaluates the value for each item in the sequence when next is invoked. More commonly it is cast into a sequence such as a tuple:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 415,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(1, 4, 9, 16, 25)"
      ]
     },
     "execution_count": 415,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(map(square, nums))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Putting this together in a single line using lists instead of tuples:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 416,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, 4, 9, 16, 25]"
      ]
     },
     "execution_count": 416,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(map(lambda x: x ** 2, [1, 2, 3, 4, 5]))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Many of the use cases for map are superseded by comprehensions which are cleaner and simpler. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 417,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, 4, 9, 16, 25]"
      ]
     },
     "execution_count": 417,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "[num ** 2 for num in [1, 2, 3, 4, 5]]"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However the principle behind using the map function is still applicable for other data structures particularly mapping a function to a Series within a pandas DataFrame."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Filter "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A lambda expression can be used to create a scalar filter function, that for example only returns a positive number:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 418,
   "metadata": {},
   "outputs": [],
   "source": [
    "positive = lambda x: x >= 0"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now supposing the following nums are created:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 419,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5)"
      ]
     },
     "execution_count": 419,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nums = tuple(range(-5, 6))\n",
    "nums"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And from this iterable, only the numbers greater or equal to 0 are desired."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The filter function can be used to map the scalar filter function to a sequence:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 420,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<filter at 0x250a44bb580>"
      ]
     },
     "execution_count": 420,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "filter(positive, nums)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This filter object is essentially a generator and evaluates the value for each item in the sequence when next is invoked. More commonly it is cast into a sequence such as a tuple:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 421,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(0, 1, 2, 3, 4, 5)"
      ]
     },
     "execution_count": 421,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tuple(filter(positive, nums))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Putting this together in a single line using lists instead of tuples:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 422,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[0, 1, 2, 3, 4, 5]"
      ]
     },
     "execution_count": 422,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(filter(lambda x: x >= 0, list(range(-5, 6))))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be compared to a list comprehension:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 423,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[0, 1, 2, 3, 4, 5]"
      ]
     },
     "execution_count": 423,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "[num for num in list(range(-5, 6)) if num >= 0]"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "The following list comprehension can also be used to see how the mapping works using boolean values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 424,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[False, False, False, False, False, True, True, True, True, True, True]"
      ]
     },
     "execution_count": 424,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "[num >= 0 for num in list(range(-5, 6))]"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Reduce"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Sometimes it is desirable to reduce an iterable into a single value:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 425,
   "metadata": {},
   "outputs": [],
   "source": [
    "nums = (1, 2, 3, 4)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following lambda expression will reduce two variables to a singular variable:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 426,
   "metadata": {},
   "outputs": [],
   "source": [
    "summation = lambda x, y: x + y"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be done using the reduce function found in the functools module:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 427,
   "metadata": {},
   "outputs": [],
   "source": [
    "from functools import reduce"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 428,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "10"
      ]
     },
     "execution_count": 428,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "reduce(summation, nums)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Under the hood, conceptualise this as a for loop. In the first iteration. x is initially 1 the value at the 0th index and y is initially 2 the value of the 1st index. The result x + y is therefore 3. In the second iteration x is now taken to be the value of 3 calculated from the previous iteration and y is taken to be the value at the 2nd index, which is also 3. x + y is therefore calculated to be 6. In the third iteration, x is taken to be the value of the previous iteration 6 and y is taken to be the value at the last index. The final x + y calculation is therefore 10 which is returned.\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## try, except, else, finally"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Earlier if, elif and else were examined to direct code in response to a condition. In Python there are four code blocks used for error handling:"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "|Code Block|Purpose|\n",
    "|---|---|\n",
    "|try|The try code block contains the code to be tested. It can run without any errors or execute can halt when an error is found.|\n",
    "|except|This code block uses an error class as a condition. It will be used to handle this error type if this error occurs. Multiple except blocks can be configured for various error types.|\n",
    "|else|This else code block will be ran, if none of the previous except blocks have been executed.|\n",
    "|finally|This code block is carried out regardless if there is an error or not.|"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These are normally used within a function and are best understood using an example. For example after asserting the data type of an input argument:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 429,
   "metadata": {},
   "outputs": [],
   "source": [
    "def plural(word):\n",
    "    try:\n",
    "        assert isinstance(word, str)\n",
    "    except AssertionError:\n",
    "        word = f'num: {str(word)}'\n",
    "    else:\n",
    "        word = f'word: {word}'\n",
    "    finally:\n",
    "        return word + 's'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, if the following is used, the try block does not encounter any error. Therefore the except code blocks are skipped and the else and finally code blocks are executed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 430,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'word: Apples'"
      ]
     },
     "execution_count": 430,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plural('Apple')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, if the following is used, the try block encounters an AssertionError. Therefore the except code block configured for an AssertionError is executed and the else block is skipped. The finally code block is also executed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 431,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'num: 2s'"
      ]
     },
     "execution_count": 431,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plural(2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another example can be given. In this scenario, the try code block is configured to look for two errors, an AssertionError and a TypeError:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 432,
   "metadata": {},
   "outputs": [],
   "source": [
    "def compare(num1, num2):\n",
    "    try:\n",
    "        assert isinstance(num1, (int, float, bool))\n",
    "        num1 > num2\n",
    "    except AssertionError:\n",
    "        print('num1 not numeric')\n",
    "    except TypeError:\n",
    "        print('num2 not numeric')\n",
    "    else:\n",
    "        print('num1 and num2 are numeric')\n",
    "    finally:\n",
    "        print('num1 has been examined')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "No errors are encountered in the try code block. The else code block is executed and the finally code block is executed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 433,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "num1 and num2 are numeric\n",
      "num1 has been examined\n"
     ]
    }
   ],
   "source": [
    "compare(1, 2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An AssertionError is encountered in the try code block. The except TypeError code block is executed and the finally code block is executed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 434,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "num1 not numeric\n",
      "num1 has been examined\n"
     ]
    }
   ],
   "source": [
    "compare('a', 2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A TypeError is encountered in the try code block. The except TypeError code block is executed and the finally code block is executed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 435,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "num2 not numeric\n",
      "num1 has been examined\n"
     ]
    }
   ],
   "source": [
    "compare(1, 'b')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An AssertionError is encountered in the try code block. This raises the AssertionError on the first line of code and all subsequent code is skipped. The except TypeError code block is executed and the finally code block is executed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 436,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "num1 not numeric\n",
      "num1 has been examined\n"
     ]
    }
   ],
   "source": [
    "compare('a', 'b')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above demonstrated the capabilities of error handling using code blocks. The else and finally code blocks are optional. "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Normally try and except are configured for each input argument. The except can also include a nested try and except:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 437,
   "metadata": {},
   "outputs": [],
   "source": [
    "def higher(num1, num2):\n",
    "    try:\n",
    "        assert isinstance(num1, (int, float, bool))\n",
    "    except AssertionError:\n",
    "        try:\n",
    "            num1 = float(num1)\n",
    "        except ValueError:\n",
    "            num1 = 1\n",
    "            print('num1 given a default value of 1')\n",
    "    try:\n",
    "        assert isinstance(num2, (int, float, bool))\n",
    "    except AssertionError:\n",
    "        try:\n",
    "            num2 = float(num2)\n",
    "        except ValueError:\n",
    "            num2 = 2\n",
    "            print('num2 given a default value of 2')\n",
    "    finally:\n",
    "        if num1 > num2:\n",
    "            return num1\n",
    "        else:\n",
    "            return num2"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The effect of error handling can be seen with the following examples. "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This first case has no errors:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 438,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "4"
      ]
     },
     "execution_count": 438,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "higher(3, 4)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The second case raises an AssertionError which is handled in the except ValueError via the nested try code block:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 439,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3.14"
      ]
     },
     "execution_count": 439,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "higher(3, '3.14')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The third case once again raises an AssertionError. An attempt to handle it is carried out in the except ValueError code block via the nested try code block, this in turn raises a ValueError, so the nested except ValueError code block handles it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 440,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "num2 given a default value of 2\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 440,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "higher(3, 'three')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that in all cases once the input arguments are handled, the finally code block is executed."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Recursion"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A factorial is a sequence of integer multiplications. For example:"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$5! = 5 * 4 * 3 * 2 * 1$$"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are two base cases:"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$1! = 1$$\n",
    "$$0! = 1$$"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the value above is examined:"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$5! = 5 * 4 * 3 * 2 * 1$$"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It can be expressed as:"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$5! = 5 * ( 4 * 3 * 2 * 1 ) = 5 * 4!$$"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Which can be expressed as a multiplication of a smaller factorial. Likewise:"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$4! = 4 * ( 3 * 2 * 1 ) = 4 * 3!$$\n",
    "$$3! = 3 * ( 2 * 1 ) = 3 * 2!$$\n",
    "$$3! = 2 * ( 1 ) = 2 * 1!$$"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Therefore a general recursive expression outlining the above is:"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$n! = (n - 1)!$$"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And the following is a base case:"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$1! = 1$$"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be expressed in a recursive function. A recursive function is a function that recursively calls itself. The recursive function has an if code block which executes for a base case and the base case ultimately returns a numeric value. "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The else code block on the other hand looks at the recursive case and returns a simplified function call, in this case reduction of the factorial by 1:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 441,
   "metadata": {},
   "outputs": [],
   "source": [
    "def factorial(num):\n",
    "    if (num == 0) | (num == 1):\n",
    "        # base cases\n",
    "        return 1\n",
    "    else:\n",
    "        # recursive case\n",
    "        return num * factorial(num - 1)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Any factorial can be expressed as a number of recursive calls which eventually leads to multiplication of a number by a base case, returning a value."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 442,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "120"
      ]
     },
     "execution_count": 442,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "factorial(5)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Under the hood, for this example the else block will recursively call the function using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 443,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "120"
      ]
     },
     "execution_count": 443,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "5 * factorial(4)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 444,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "24"
      ]
     },
     "execution_count": 444,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "4 * factorial(3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 445,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "6"
      ]
     },
     "execution_count": 445,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "3 * factorial(2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It will finally call the function using:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 446,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 446,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "2 * factorial(1)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "which is a base case that returns a value."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[Return to Python Tutorials](../readme.md)"
   ]
  }
 ],
 "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.12.1"
  },
  "vscode": {
   "interpreter": {
    "hash": "4648373dafda34926c036cc9e466ef2f8d360789320441bb704a9be21d427d2a"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}