17-CodeProjects.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Code Projects\n",
    "\n",
    "- modular design\n",
    "- minimal viable product\n",
    "- test-driven development\n",
    "- rapid prototyping\n",
    "- project organization\n",
    "- refactoring\n",
    "- code review"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Modular Design"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "Modular design, like modular programming, is the approach of designing and building things as independent modules. \n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Minimal Viable Product"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "A 'minimal viable product' is a product that contains the minimum amount of implemented features to use the code product - no more, no less.</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Test-Driven Development"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "Writing the tests as soon as you have a plan & before you've written the code.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Rapid Prototyping"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "Rapid prototyping is an approach for developing things in which you work on minimal prototypes and iterate on them quickly. \n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "#### Some rapid prototyping examples\n",
    "\n",
    "- Chatbot: start and end a chat\n",
    "- Data Analysis: read a dataset in, make a basic plot\n",
    "- Car Inventory: object with method that adds a car to the Inventory\n",
    "- Artificial Agents: simple bot moves around randomly"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Project Organization"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "- **Notebooks**: good for interactive development\n",
    "    - For when seeing the inputs and outputs of code running needs to be seen start to finish\n",
    "    - file ends in `.ipynb`\n",
    "- **Modules**: for storing mature Python code, that you can import\n",
    "    - you don't *use* the functions in there, just define them\n",
    "    - file ends in `.py`\n",
    "- **Scripts**: a Python file for executing a particular task\n",
    "    - this takes an input and does something start to finish\n",
    "    - file ends in `.py`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Project Workflow"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "Typical project workflow:\n",
    "\n",
    "- Develop plan and write tests\n",
    "- Develop code interactively in a Jupyter notebook/text editor\n",
    "- As functions & classes become mature, move them to Python files that you then `import`\n",
    "    - As you do so, go back through them to check for code style, add documentation, and run your code tests\n",
    "- At the end of a project, (maybe) write a standalone script that runs the project"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Project Notes\n",
    "\n",
    "1. Design and write tests\n",
    "2. Write some code\n",
    "2. Test to make sure it works\n",
    "3. Check code style (naming, spacing, etc.)\n",
    "4. Add documentation\n",
    "5. Move to module (if necessary)\n",
    "6. Run all tests"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Project Design\n",
    "\n",
    "- Idea: atbash encryption: return the capitalized, reverse alphabetical letter for each character in the input string\n",
    "\n",
    "- Design:\n",
    "    - `atbash_encrypt()` : take input string and retrun atbash encrypted string\n",
    "        - inputs: `input_string` \n",
    "        - returns: `atbash_string`\n",
    "    - `atbash_decrypt()` : take encrypted string and decrypt using atbash\n",
    "        - inputs: `atbash_string`\n",
    "        - returns: `decrypted_string`\n",
    "    - `atbash_wrapper()` : does either of the above, as specified with input parameter\n",
    "        - inputs: `input_string`, `method` (either 'encrypt' or 'decrypt', default: 'encrypt')\n",
    "        - returns `output_string`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Adding Unit Tests"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "# from atbash import *\n",
    "\n",
    "# def test_atbash_encrypt():\n",
    "#     assert callable(atbash_encrypt)\n",
    "#     assert isinstance(atbash_encrypt('hello'), str)\n",
    "#     assert atbash_encrypt('HELLO') == 'SVOOL'\n",
    "#     assert atbash_encrypt('hello') == 'SVOOL'\n",
    "    \n",
    "# def test_atbash_decrypt():\n",
    "#     assert callable(atbash_decrypt)\n",
    "#     assert isinstance(atbash_decrypt('hello'), str)\n",
    "#     assert atbash_decrypt('SVOOL') == 'HELLO'\n",
    "#     assert atbash_decrypt('svool') == 'HELLO'\n",
    "\n",
    "# def test_atbash_wrapper():\n",
    "#     assert callable(atbash_wrapper)\n",
    "#     assert isinstance(atbash_wrapper('hello', method='encrypt'), str)\n",
    "#     assert atbash_wrapper('hello', method='encrypt') == 'SVOOL'\n",
    "#     assert atbash_wrapper('HELLO', method='encrypt') == 'SVOOL'\n",
    "#     assert atbash_wrapper('SVOOL', method='decrypt') == 'HELLO'\n",
    "#     assert atbash_wrapper('svool', method='decrypt') == 'HELLO'\n",
    "#     assert atbash_wrapper('svool', method='blargh') == \"method should be either 'decrypt' or 'encrypt'\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "...move to test file\n",
    "\n",
    "...will uncomment as I write the code/functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Writing Code\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "#### `atbash_encrypt`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "def atbash_encrypt(input_string):\n",
    "    alpha = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'\n",
    "    reverse_alpha = 'ZYXWVUTSRQPONMLKJIHGFEDCBA'\n",
    "\n",
    "    atbash_string = ''\n",
    "\n",
    "    for char in input_string:\n",
    "        char = char.upper()\n",
    "        if char in alpha:\n",
    "            position = alpha.find(char)\n",
    "            atbash_string += reverse_alpha[position]\n",
    "        else:\n",
    "            atbash_string = None\n",
    "            break\n",
    "        \n",
    "    return atbash_string"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# smoke test\n",
    "atbash_encrypt('Hello')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Moving to a module...\n",
    "\n",
    "Now that we have our working function, we should move it to a module file\n",
    "\n",
    "- don't forget to import your new module at the top of the test file"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "Note on `imports`: If you want to be able to use modules (imports) within a module/script, be sure to import it at the top. This applies to test files as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "!pytest test_atbash.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### `atbash_decrypt`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "# reminder: consider code style! \n",
    "def atbash_decrypt(atbash_string):    \n",
    "    ALPHA='ABCDEFGHIJKLMNOPQRSTUVWXYZ'\n",
    "    REVERSEALPHA='ZYXWVUTSRQPONMLKJIHGFEDCBA'\n",
    "    atbash_string=atbash_string.upper()\n",
    "    decrypted_string=''\n",
    "    for l in atbash_string:\n",
    "        if l in REVERSEALPHA:\n",
    "            letterindex=REVERSEALPHA.find(l)\n",
    "            decrypted_string=decrypted_string+ALPHA[letterindex]\n",
    "        else: decrypted_string=decrypted_string+l\n",
    "    return decrypted_string"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# smoke test\n",
    "atbash_decrypt('SVOOL')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pytest test_atbash.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### `atbash_wrapper`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "def atbash_wrapper(input_string, method='encrypt'):\n",
    "    \n",
    "    if method == 'encrypt':\n",
    "        output_string = atbash_encrypt(input_string)\n",
    "    elif method == 'decrypt':\n",
    "        output_string = atbash_decrypt(input_string)\n",
    "    else:\n",
    "        output_string = \"method should be either 'decrypt' or 'encrypt'\"\n",
    "    \n",
    "    return output_string"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# smoke test\n",
    "atbash_wrapper('hello', 'encrypt')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pytest test_atbash.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Documentation\n",
    "\n",
    "- Code in final project/exam requires:\n",
    "    - numpy-style docstrings\n",
    "    - code comments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Putting it all together"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from atbash import atbash_wrapper"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "atbash_wrapper('hello')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "atbash_wrapper('svool', method='decrypt')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "atbash_wrapper('hello', method='blargh')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Refactoring"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "Refactoring is the process of restructuring existing computer code, without changing its external behaviour. \n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Think of this as restructuring and final edits on your essay. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "**Nesting Functions** - If you have a whole bunch of functions, if statements, and for/while loops together within a single function, you probably want (need?) to refactor."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Clean functions accomplish a **single task**!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "**DRY**: Don't Repeat Yourself"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Refactoring Example: Chatbot"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "import random \n",
    "\n",
    "def have_a_chat():\n",
    "    \"\"\"Main function to run our chatbot.\"\"\"\n",
    "    \n",
    "    chat = True\n",
    "\n",
    "    while chat:\n",
    "\n",
    "        # Get a message from the user\n",
    "        msg = input('INPUT :\\t')\n",
    "        out_msg = None\n",
    "        \n",
    "        # Check if the input is a question\n",
    "        input_string = msg\n",
    "        if '?' in input_string:\n",
    "            question = True\n",
    "        else:\n",
    "            question = False\n",
    "\n",
    "        # Check for an end msg \n",
    "        if 'quit' in input_string:\n",
    "            out_msg = 'Bye!'\n",
    "            chat = False\n",
    "            \n",
    "        # If we don't have an output yet, but the input was a question, \n",
    "        # return msg related to it being a question\n",
    "        if not out_msg and question:\n",
    "            out_msg = \"I'm too shy to answer questions. What do you want to talk about?\"\n",
    "\n",
    "        # Catch-all to say something if msg not caught & processed so far\n",
    "        if not out_msg:\n",
    "            out_msg = random.choice(['Good.', 'Okay', 'Huh?', 'Yeah!', 'Thanks!'])\n",
    "\n",
    "        print('OUTPUT:', out_msg)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "have_a_chat()  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Refactored Example: Chatbot"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "What this function does:\n",
    "\n",
    "1. takes an input\n",
    "2. checks if input is a question\n",
    "3. checks if input is supposed to end the chat\n",
    "4. return appropriate response if question, end chat, or other\n",
    "\n",
    "That's four different things! Functions should do a single thing..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "def get_input():\n",
    "    \"\"\"ask user for an input message\"\"\"\n",
    "    \n",
    "    msg = input('INPUT :\\t')   \n",
    "    out_msg = None\n",
    "    \n",
    "    return msg, out_msg"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "def is_question(input_string):\n",
    "    \"\"\"determine if input from user is a question\"\"\"\n",
    "    \n",
    "    if '?' in input_string:\n",
    "        output = True\n",
    "    else:\n",
    "        output = False\n",
    "    \n",
    "    return output"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "def end_chat(input_list):\n",
    "    \"\"\"identify if user says 'quit' in input and end chat\"\"\"\n",
    "    \n",
    "    if 'quit' in input_list:\n",
    "        output = 'Bye'\n",
    "        chat = False\n",
    "    else:\n",
    "        output = None\n",
    "        chat = True\n",
    "        \n",
    "    return output, chat"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "def return_message(out_msg, question):\n",
    "    \"\"\"generic responses for the chatbot to return\"\"\"\n",
    "        \n",
    "    # If we don't have an output yet, but the input was a question, \n",
    "    # return msg related to it being a question\n",
    "    if not out_msg and question:\n",
    "        out_msg = \"I'm too shy to answer questions. What do you want to talk about?\"\n",
    "\n",
    "    # Catch-all to say something if msg not caught & processed so far\n",
    "    if not out_msg:\n",
    "        out_msg = random.choice(['Good.', 'Okay', 'Huh?', 'Yeah!', 'Thanks!'])\n",
    "        \n",
    "    return out_msg"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "def have_a_chat():\n",
    "    \"\"\"Main function to run our chatbot.\"\"\"\n",
    "    \n",
    "    chat = True\n",
    "\n",
    "    while chat:\n",
    "\n",
    "        # Get input message from the user\n",
    "        msg, out_msg = get_input()\n",
    "        \n",
    "        # Check if the input is a question\n",
    "        question = is_question(msg)\n",
    "         \n",
    "        # Check for an end msg \n",
    "        out_msg, chat = end_chat(msg)\n",
    "       \n",
    "        # specify what to return \n",
    "        out_msg = return_message(out_msg = out_msg, question = question)\n",
    "        \n",
    "        print('OUTPUT:', out_msg)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "have_a_chat()  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Code Review"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "Code review is a process for systematically reviewing someone else's code. \n",
    "</div>"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "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.5"
  },
  "rise": {
   "scroll": true
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}