clean-code-present.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "4ecc0e78-e920-468c-b259-98c0fca0ce2e",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "# Clean, Modular Code"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a574ddee-801e-4331-a2cd-d91b8b9dee77",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "source": [
    "## Part 1: 3 strategies\n",
    "\n",
    "* Use [consistent code format](pep8-code-format)\n",
    "* Use [expressive object names](python-expressive-code)\n",
    "* [Make your code DRY](dry-code)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "719d9c11-c248-4724-8b68-7e259a63311e",
   "metadata": {
    "editable": true,
    "jp-MarkdownHeadingCollapsed": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "### PEP 8 & consistent code format\n",
    "\n",
    "* Generally accepted rules for code format: PEP 8\n",
    "* Set of rules around white space, naming conventions, import orders and more.\n",
    "* Code Formatters: Tools to apply PEP 8 as you work!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ef0d2740-7c9c-44f5-9a45-4950457443bf",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "skip"
    },
    "tags": []
   },
   "source": [
    "## Notes \n",
    "."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "id": "c8019d36-e143-425e-a891-badd822483b0",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Messy code.\n",
      "Oops!\n"
     ]
    }
   ],
   "source": [
    "# this code is not PEP8 compliant -- why?\n",
    "def doStuff(a ,b):print (\"Result:\",a+b) ; return a+b\n",
    "x=True\n",
    "if x: print ( \"Messy code.\") ; print(\"Oops!\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "96c26cf3-7a4a-4b5e-a55f-8bc20f888876",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This is nicer code.\n",
      "Yay!\n"
     ]
    }
   ],
   "source": [
    "# This code is PEP8 compliant -- why?\n",
    "def do_stuff(number1, number2):\n",
    "    print(\"Result:\", number1 + number2)\n",
    "    return number1 + number2\n",
    "\n",
    "\n",
    "x = True\n",
    "if x:\n",
    "    print(\"This is nicer code.\")\n",
    "    print(\"Yay!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0391b9bc-9f80-4e6a-b085-1a7ccc1812ff",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "### (A few) Code format tools\n",
    "\n",
    "* Jupyter code formatter (installed in this binder).\n",
    "* Black\n",
    "* Ruff"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "42c8f536-c291-43bc-9601-4b0ec4bd0dc6",
   "metadata": {
    "editable": true,
    "jp-MarkdownHeadingCollapsed": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "#### [Other tools to consider](tools-code-style)\n",
    "\n",
    "* `pre-commit` hooks: use with .git; apply every time you commit changes\n",
    "* Setup VSCode (and other IDE's) to format on save"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a4294a55-b1cf-4e43-ab75-1a1a54cde516",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Expressive code\n",
    "\n",
    "* Code can become documentation when written well.\n",
    "* Use variable, function & class names that tell a user what each thing does"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a78e9fbc-0d0f-41b6-a098-a324f2a95f0d",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "<center><img src=\"../images/clean-code/clean-code-expressive-variable-names-basmati-rice.png\" alt=\"Image showing a large see-through Tupperware container with cookies in it but a label that says Basmati Rice.\"></center>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "2af65bf3-472e-4905-a855-103e6f59c442",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This is less nice code.\n"
     ]
    }
   ],
   "source": [
    "# Could this code be more clear?\n",
    "def do_stuff(a, b):\n",
    "    print(\"Result:\", a + b)\n",
    "    return a + b\n",
    "\n",
    "\n",
    "x = True\n",
    "if x:\n",
    "    print(\"This is less nice code.\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "ecdcf16e-e0ab-46aa-87ad-9528f3365f66",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This is nicer code.\n",
      "Yay!\n"
     ]
    }
   ],
   "source": [
    "def calculate_sum(number1, number2):\n",
    "    print(\"Result:\", number1 + number2)\n",
    "    return number1 + number2\n",
    "\n",
    "\n",
    "is_valid = True\n",
    "if is_valid:\n",
    "    print(\"This is nicer code.\")\n",
    "    print(\"Yay!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2f564e39-a366-4e44-a3c6-e8ce12c09c82",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## DRY code\n",
    "\n",
    "* Don't Repeat Yourself\n",
    "* Use functions, loops and conditionals instead"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b3cfa5e8-c764-447c-8fd6-8a5b84050fed",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "<center><img src=\"../images/clean-code/copy-pasta-code-dry.png\" alt=\"Image of copy pasta - ctrl v.\"></center>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "55fdc5a9-6012-4b89-914f-b8c7320cb1fa",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "7\n",
      "12\n",
      "10\n",
      "20\n"
     ]
    }
   ],
   "source": [
    "# Not DRY\n",
    "a = 5\n",
    "b = 10\n",
    "print(a + 2)\n",
    "print(b + 2)\n",
    "print(a * 2)\n",
    "print(b * 2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "71895994-c13c-4bdf-8386-69c03aa9b9a6",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "7\n",
      "10\n",
      "12\n",
      "20\n"
     ]
    }
   ],
   "source": [
    "# DRY\n",
    "def process_number(x):\n",
    "    print(x + 2)\n",
    "    print(x * 2)\n",
    "\n",
    "\n",
    "numbers = [5, 10]\n",
    "for num in numbers:\n",
    "    process_number(num)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "480a07e8-2ba4-4f22-acac-38d094a4f765",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Begin Activity One!\n",
    "\n",
    "You are now familiar with 3 strategies for writing better, cleaner code. You will apply these principles to example code in the [first activity](clean-code-activity-1).\n",
    "\n",
    "Remember that this is not a test! \n",
    "It's a chance to think about how you write code and how others may receive it!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "16560e60-c567-4518-bc6b-21e75964321e",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Part 2: Refactor your code\n",
    "Three strategies:\n",
    "\n",
    "* **Document** \n",
    "* **Modularize**\n",
    "* **Ensure reproducibility: (dynamic paths)**"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "14fad31b-de31-4d28-939b-65b0de9f0b15",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Document as you go\n",
    "\n",
    "* Make it a habit\n",
    "* It's easier to do it as you work!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "beec44ad-9f69-4386-9ae7-f472eabc801e",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Document your code\n",
    "\n",
    "Add a docstring to the top of any script or module that explains the intent of the code.\n",
    "\n",
    "A module or function docstring will appear in API documentation if you use tools like autodoc."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "81afd400-8008-4149-af47-be25ff6dd227",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "\"\"\"What this module does\"\"\"\n",
    "\n",
    "import pandas as pd\n",
    "\n",
    "# Code starts here..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "6cc48161-7ee0-4b8b-9b3a-4f14c6370f66",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function add_numbers in module __main__:\n",
      "\n",
      "add_numbers(x, y)\n",
      "    # A sad, lonely, undocumented function\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# A sad, lonely, undocumented function\n",
    "def add_numbers(x, y):\n",
    "    return x + y\n",
    "\n",
    "\n",
    "help(add_numbers)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "5620e1b0-e928-4e37-a08a-a500335570f6",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Better: Add a docstring!\n",
    "def add_numbers(x, y):\n",
    "    \"\"\"\n",
    "    Add two numbers.\n",
    "\n",
    "    Parameters\n",
    "    ----------\n",
    "    x : int or float\n",
    "        The first number.\n",
    "    y : int or float\n",
    "        The second number.\n",
    "\n",
    "    Returns\n",
    "    -------\n",
    "    int or float\n",
    "        The sum of `x` and `y`.\n",
    "    \"\"\"\n",
    "    return x + y"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "0839be11-d6fd-47cc-b3e1-dea1390cca5a",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function add_numbers in module __main__:\n",
      "\n",
      "add_numbers(x, y)\n",
      "    Add two numbers.\n",
      "    \n",
      "    Parameters\n",
      "    ----------\n",
      "    x : int or float\n",
      "        The first number.\n",
      "    y : int or float\n",
      "        The second number.\n",
      "    \n",
      "    Returns\n",
      "    -------\n",
      "    int or float\n",
      "        The sum of `x` and `y`.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(add_numbers)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "fe92e14c-312f-47f4-a485-2fc70b6cecfa",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Best add docstring with examples of running the function\n",
    "def add_num(x, y):\n",
    "    \"\"\"\n",
    "    Add two numbers.\n",
    "\n",
    "    Parameters\n",
    "    ----------\n",
    "    x : int or float\n",
    "        The first number.\n",
    "    y : int or float\n",
    "        The second number.\n",
    "\n",
    "    Returns\n",
    "    -------\n",
    "    int or float\n",
    "        The sum of `x` and `y`.\n",
    "\n",
    "    Examples\n",
    "    --------\n",
    "    >>> add_num(2, 3)\n",
    "    5\n",
    "    >>> add_num(4.5, 5.5)\n",
    "    10.0\n",
    "    \"\"\"\n",
    "    return x + y"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "272c5cc6-76f5-45e9-b699-abd58ac3d69b",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function add_num in module __main__:\n",
      "\n",
      "add_num(x, y)\n",
      "    Add two numbers.\n",
      "    \n",
      "    Parameters\n",
      "    ----------\n",
      "    x : int or float\n",
      "        The first number.\n",
      "    y : int or float\n",
      "        The second number.\n",
      "    \n",
      "    Returns\n",
      "    -------\n",
      "    int or float\n",
      "        The sum of `x` and `y`.\n",
      "    \n",
      "    Examples\n",
      "    --------\n",
      "    >>> add_num(2, 3)\n",
      "    5\n",
      "    >>> add_num(4.5, 5.5)\n",
      "    10.0\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(add_num)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7d171ff8-3978-4f36-b393-85794d79697d",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Modularize your code\n",
    "\n",
    "Functions make code easier to read, test, and maintain."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "9828c8d0-8a1e-4875-b4b8-177b3105794b",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "7\n",
      "12\n",
      "10\n",
      "20\n"
     ]
    }
   ],
   "source": [
    "# Not DRY, not modular\n",
    "a = 5\n",
    "b = 10\n",
    "print(a + 2)\n",
    "print(b + 2)\n",
    "print(a * 2)\n",
    "print(b * 2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "969c81b3-549f-437b-9bd1-a6094ec165c6",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "7\n",
      "10\n",
      "12\n",
      "20\n"
     ]
    }
   ],
   "source": [
    "# DRY & modular\n",
    "def process_number(x):\n",
    "    print(x + 2)\n",
    "    print(x * 2)\n",
    "\n",
    "\n",
    "numbers = [5, 10]\n",
    "for num in numbers:\n",
    "    process_number(num)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "371750c7-c349-45bd-bc5d-48e56c460a0b",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Reproducibility: Create dynamic paths\n",
    "\n",
    "* Paths on Windows are different than MAC/Linux\n",
    "* Using `Path` (or `os`)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "61c8130e-de3c-4d05-aea0-08f1ad4d918a",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'data/data.json'"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Less good\n",
    "path = \"data/data.json\"\n",
    "path"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "f693c9da-b9ed-4bb7-9866-af32b6a157b2",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "data/data.json\n"
     ]
    }
   ],
   "source": [
    "import pathlib\n",
    "\n",
    "# Dynamically generate paths so they will run on diff operating systems\n",
    "path = pathlib.Path(\"\") / \"data\" / \"data.json\"\n",
    "print(path)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d0f57f78-bacf-468d-81bb-d68f271b8077",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Tests & checks\n",
    "\n",
    "* Usability sometimes means failing (gracefully and with intention)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4f9d4e44-9bf8-4bf7-acc7-54b72a433e47",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "### Strategies \n",
    "* Fail fast (with useful error messages)\n",
    "* try/except blocks: handle errors (exceptions)\n",
    "* Conditionals to optimize and redirect workflows"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "35a82cb3-8ed8-4b32-9973-4a3418d92320",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Fail fast"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "7fd1f23b-0c1b-48da-bc89-734453cad899",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": [
     "raises-exception"
    ]
   },
   "outputs": [
    {
     "ename": "FileNotFoundError",
     "evalue": "[Errno 2] No such file or directory: 'your_file.json'",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mFileNotFoundError\u001b[0m                         Traceback (most recent call last)",
      "Cell \u001b[0;32mIn[17], line 11\u001b[0m\n\u001b[1;32m      8\u001b[0m file_path \u001b[38;5;241m=\u001b[39m Path(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124myour_file.json\u001b[39m\u001b[38;5;124m\"\u001b[39m)\n\u001b[1;32m     10\u001b[0m \u001b[38;5;66;03m# Open the JSON file and read the data\u001b[39;00m\n\u001b[0;32m---> 11\u001b[0m \u001b[38;5;28;01mwith\u001b[39;00m \u001b[43mfile_path\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mopen\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[38;5;124;43mr\u001b[39;49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[43m)\u001b[49m \u001b[38;5;28;01mas\u001b[39;00m json_file:\n\u001b[1;32m     12\u001b[0m     json_data \u001b[38;5;241m=\u001b[39m json\u001b[38;5;241m.\u001b[39mload(json_file)\n\u001b[1;32m     14\u001b[0m \u001b[38;5;66;03m# Normalize the JSON data into a Pandas DataFrame\u001b[39;00m\n",
      "File \u001b[0;32m~/mambaforge/envs/lessons/lib/python3.11/pathlib.py:1044\u001b[0m, in \u001b[0;36mPath.open\u001b[0;34m(self, mode, buffering, encoding, errors, newline)\u001b[0m\n\u001b[1;32m   1042\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mb\u001b[39m\u001b[38;5;124m\"\u001b[39m \u001b[38;5;129;01mnot\u001b[39;00m \u001b[38;5;129;01min\u001b[39;00m mode:\n\u001b[1;32m   1043\u001b[0m     encoding \u001b[38;5;241m=\u001b[39m io\u001b[38;5;241m.\u001b[39mtext_encoding(encoding)\n\u001b[0;32m-> 1044\u001b[0m \u001b[38;5;28;01mreturn\u001b[39;00m \u001b[43mio\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mopen\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;28;43mself\u001b[39;49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mmode\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mbuffering\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mencoding\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43merrors\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mnewline\u001b[49m\u001b[43m)\u001b[49m\n",
      "\u001b[0;31mFileNotFoundError\u001b[0m: [Errno 2] No such file or directory: 'your_file.json'"
     ]
    }
   ],
   "source": [
    "# This code fails with a useful message\n",
    "import json\n",
    "from pathlib import Path\n",
    "\n",
    "import pandas as pd\n",
    "\n",
    "# Define the file path\n",
    "file_path = Path(\"your_file.json\")\n",
    "\n",
    "# Open the JSON file and read the data\n",
    "with file_path.open(\"r\") as json_file:\n",
    "    json_data = json.load(json_file)\n",
    "\n",
    "# Normalize the JSON data into a Pandas DataFrame\n",
    "df = pd.json_normalize(json_data)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "b9f1d723-efb7-46a6-84fb-0263b0965917",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": [
     "raises-exception"
    ]
   },
   "outputs": [
    {
     "ename": "TypeError",
     "evalue": "'PosixPath' object is not subscriptable",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mTypeError\u001b[0m                                 Traceback (most recent call last)",
      "Cell \u001b[0;32mIn[18], line 10\u001b[0m\n\u001b[1;32m      8\u001b[0m file_paths \u001b[38;5;241m=\u001b[39m \u001b[38;5;28mlist\u001b[39m(Path(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124m.\u001b[39m\u001b[38;5;124m\"\u001b[39m)\u001b[38;5;241m.\u001b[39mglob(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124m*.json\u001b[39m\u001b[38;5;124m\"\u001b[39m))\n\u001b[1;32m      9\u001b[0m \u001b[38;5;66;03m# Open the first file\u001b[39;00m\n\u001b[0;32m---> 10\u001b[0m \u001b[38;5;28;01mwith\u001b[39;00m \u001b[43mfile_path\u001b[49m\u001b[43m[\u001b[49m\u001b[38;5;241;43m0\u001b[39;49m\u001b[43m]\u001b[49m\u001b[38;5;241m.\u001b[39mopen(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mr\u001b[39m\u001b[38;5;124m\"\u001b[39m) \u001b[38;5;28;01mas\u001b[39;00m json_file:\n\u001b[1;32m     11\u001b[0m     json_data \u001b[38;5;241m=\u001b[39m json\u001b[38;5;241m.\u001b[39mload(json_file)\n\u001b[1;32m     13\u001b[0m \u001b[38;5;66;03m# Normalize the JSON data into a Pandas DataFrame\u001b[39;00m\n",
      "\u001b[0;31mTypeError\u001b[0m: 'PosixPath' object is not subscriptable"
     ]
    }
   ],
   "source": [
    "# The same problem occurs in this code but it fails with a less useful message\n",
    "import json\n",
    "from pathlib import Path\n",
    "\n",
    "import pandas as pd\n",
    "\n",
    "# Create a list of json files\n",
    "file_paths = list(Path(\".\").glob(\"*.json\"))\n",
    "# Open the first file\n",
    "with file_path[0].open(\"r\") as json_file:\n",
    "    json_data = json.load(json_file)\n",
    "\n",
    "# Normalize the JSON data into a Pandas DataFrame\n",
    "df = pd.json_normalize(json_data)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "6bd0a5db-3f17-404c-bc6d-24ad5e6b2083",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[]"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# The problem:\n",
    "file_paths"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "801b50cd-6f41-43d5-84c2-61ba6d4d6311",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Handle errors\n",
    "\n",
    "* Anticipate errors a user may encounter when using your code.\n",
    "* Redirect workflows by catching errors.\n",
    "* Provide helpful error messages"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "95d18999-9ab2-4073-ad3c-a82c92d5c233",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[\"package name I'm a title\"]"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# What happens when the data are in a list rather than provided as a string?\n",
    "# Here, the code runs and doesn't fail at all producing a potential bug\n",
    "title = \"package name I'm a title\"\n",
    "title.split(\":\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "1cc8b017-a30c-402d-ab42-986516e19a33",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": [
     "raises-exception"
    ]
   },
   "outputs": [
    {
     "ename": "AttributeError",
     "evalue": "'int' object has no attribute 'split'",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mAttributeError\u001b[0m                            Traceback (most recent call last)",
      "Cell \u001b[0;32mIn[21], line 3\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[38;5;66;03m# In this case the code is provided with an int - resulting in an attribute error\u001b[39;00m\n\u001b[1;32m      2\u001b[0m title \u001b[38;5;241m=\u001b[39m \u001b[38;5;241m1\u001b[39m\n\u001b[0;32m----> 3\u001b[0m package_name \u001b[38;5;241m=\u001b[39m \u001b[43mtitle\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43msplit\u001b[49m(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124m:\u001b[39m\u001b[38;5;124m\"\u001b[39m)[\u001b[38;5;241m0\u001b[39m]\n",
      "\u001b[0;31mAttributeError\u001b[0m: 'int' object has no attribute 'split'"
     ]
    }
   ],
   "source": [
    "# In this case the code is provided with an int - resulting in an attribute error\n",
    "title = 1\n",
    "package_name = title.split(\":\")[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "1cdbed33-73e6-4125-bffd-1bf1cf7452c7",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'package name'"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# This works as expected\n",
    "title = \"package name: i'm a title\"\n",
    "package_name = title.split(\":\")[0]\n",
    "package_name "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "b305a68e-7a94-4ac9-908d-e18ba64241e8",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "# In some cases, you may want to capture the error and return a default value\n",
    "# (or do something else)\n",
    "title = 9999\n",
    "\n",
    "try:\n",
    "    package_name = title.split(\":\")[0]\n",
    "except AttributeError:\n",
    "    # Ask yourself, how do you want to handle this exception?\n",
    "    package_name = None\n",
    "    # Should the code keep running? Should it exit? Should it assign a default value?\n",
    "    # raise AttributeError(f\"Oops - I expected a string and you provided a {type(title)}\")\n",
    "\n",
    "package_name"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "7a3b1a25-3304-47b3-9000-ecfc454aaa18",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": [
     "raises-exception"
    ]
   },
   "outputs": [
    {
     "ename": "AttributeError",
     "evalue": "Oops - I expected a string and you provided a <class 'int'>",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mAttributeError\u001b[0m                            Traceback (most recent call last)",
      "Cell \u001b[0;32mIn[24], line 5\u001b[0m\n\u001b[1;32m      4\u001b[0m \u001b[38;5;28;01mtry\u001b[39;00m:\n\u001b[0;32m----> 5\u001b[0m     package_name \u001b[38;5;241m=\u001b[39m \u001b[43mtitle\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43msplit\u001b[49m(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124m:\u001b[39m\u001b[38;5;124m\"\u001b[39m)[\u001b[38;5;241m0\u001b[39m]\n\u001b[1;32m      6\u001b[0m \u001b[38;5;28;01mexcept\u001b[39;00m \u001b[38;5;167;01mAttributeError\u001b[39;00m:\n\u001b[1;32m      7\u001b[0m     \u001b[38;5;66;03m# Ask yourself, how do you want to handle this exception?\u001b[39;00m\n\u001b[1;32m      8\u001b[0m     \u001b[38;5;66;03m# Should the code keep running? Should it exit? Should it assign a default value?\u001b[39;00m\n",
      "\u001b[0;31mAttributeError\u001b[0m: 'int' object has no attribute 'split'",
      "\nDuring handling of the above exception, another exception occurred:\n",
      "\u001b[0;31mAttributeError\u001b[0m                            Traceback (most recent call last)",
      "Cell \u001b[0;32mIn[24], line 9\u001b[0m\n\u001b[1;32m      5\u001b[0m     package_name \u001b[38;5;241m=\u001b[39m title\u001b[38;5;241m.\u001b[39msplit(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124m:\u001b[39m\u001b[38;5;124m\"\u001b[39m)[\u001b[38;5;241m0\u001b[39m]\n\u001b[1;32m      6\u001b[0m \u001b[38;5;28;01mexcept\u001b[39;00m \u001b[38;5;167;01mAttributeError\u001b[39;00m:\n\u001b[1;32m      7\u001b[0m     \u001b[38;5;66;03m# Ask yourself, how do you want to handle this exception?\u001b[39;00m\n\u001b[1;32m      8\u001b[0m     \u001b[38;5;66;03m# Should the code keep running? Should it exit? Should it assign a default value?\u001b[39;00m\n\u001b[0;32m----> 9\u001b[0m     \u001b[38;5;28;01mraise\u001b[39;00m \u001b[38;5;167;01mAttributeError\u001b[39;00m(\u001b[38;5;124mf\u001b[39m\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mOops - I expected a string and you provided a \u001b[39m\u001b[38;5;132;01m{\u001b[39;00m\u001b[38;5;28mtype\u001b[39m(title)\u001b[38;5;132;01m}\u001b[39;00m\u001b[38;5;124m\"\u001b[39m)\n\u001b[1;32m     11\u001b[0m package_name\n",
      "\u001b[0;31mAttributeError\u001b[0m: Oops - I expected a string and you provided a <class 'int'>"
     ]
    }
   ],
   "source": [
    "# In others you may want to intentionally raise an error with a custom message.\n",
    "title = 999\n",
    "\n",
    "try:\n",
    "    package_name = title.split(\":\")[0]\n",
    "except AttributeError:\n",
    "    # Ask yourself, how do you want to handle this exception?\n",
    "    # Should the code keep running? Should it exit? Should it assign a default value?\n",
    "    raise AttributeError(f\"Oops - I expected a string and you provided a {type(title)}\")\n",
    "\n",
    "package_name"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a99e061e-fc19-4b9e-8b8a-d5eeb7a0eada",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Start activity three \n",
    "\n",
    "Activity 3 is an interactive notebook you can work on in small groups. \n",
    "\n",
    "Work through the activities and ask questions!"
   ]
  }
 ],
 "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.11.10"
  },
  "toc": {
   "base_numbering": 1
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}