Week_3/Python_Basics_18_-_Exceptions_&_Assertions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a href='https://www.learntocodeonline.com/'><img src=\"../IMGs/learn-to-code-online.png\"></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# What Is An Exception?\n",
    "\n",
    "[**Errors & Exceptions**](https://docs.python.org/3/tutorial/errors.html) are events that disrupt the normal flow of a program's instructions. It is basically a situation that Python cannot cope with. For example:  expecting one kind of input and it being different.\n",
    "\n",
    "An exception is an object that represents an error. When this object is raised, it not handled it will immediately terminate the program.\n",
    "\n",
    "When used properly, it allows you to perform better troubleshooting.\n",
    "(In Java, it is known as a [try-catch block](https://docs.oracle.com/javase/tutorial/essential/exceptions/catch.html).)\n",
    "\n",
    "You can find more on built-in exceptions [here](https://docs.python.org/3/library/exceptions.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# How To [Handle Exceptions](https://docs.python.org/3/tutorial/errors.html#handling-exceptions)\n",
    "\n",
    "When you have code that you know could potentially break your script (like reading/writing to a file, end user input, etc) you can defend your program by using a **try** block with an **except** statement, followed by a block of code to handle the problem elegantly."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here is some example pseudo code:\n",
    "\n",
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "```python\n",
    "try:\n",
    "    # do operation here (this is intended for a single line of code)\n",
    "    pass\n",
    "except ExceptionTypeI:\n",
    "    # Exception is a BaseException type...\n",
    "    # but is bad practice to use this catch all!\n",
    "    # This section of code will only run if this kind of Exception is hit\n",
    "    pass\n",
    "except ExceptionTypeII:\n",
    "    # This section of code will only run if this kind of Exception is hit\n",
    "    pass\n",
    "# there can be multiple kinds of exceptions\n",
    "else:\n",
    "    # this block of code executes if no exception\n",
    "    pass\n",
    "```\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-success\">\n",
    "<b>Try this!</b>\n",
    "\n",
    "```python\n",
    "try:\n",
    "    fh = open('textfile.txt', 'w')\n",
    "except IOError as err:\n",
    "    print(\"ERROR:  {}\".format(err))\n",
    "else:\n",
    "    fh.write('This is my test file for exception handling!!')\n",
    "    print(\"Written content in the file successfully.\")\n",
    "finally:\n",
    "    fh.close()\n",
    "```\n",
    "</div>\n",
    "\n",
    "_What do you think will happen if you run the above code?_"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or how about this one?\n",
    "\n",
    "<div class=\"alert alert-success\">\n",
    "\n",
    "```python\n",
    "try:\n",
    "    fh = open('textfile.txt', 'r')\n",
    "except IOError as err:\n",
    "    print(\"ERROR:  {}\".format(err))\n",
    "else:\n",
    "    fh.write('This is my test file for exception handling!!')\n",
    "    print(\"Written content in the file successfully.\")\n",
    "finally:\n",
    "    fh.close()\n",
    "```\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Please note that you can choose to gracefully handle exceptions, or [re-raise them](https://docs.python.org/3/tutorial/errors.html#raising-exceptions)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "How would you resolve the above?<br>\n",
    "    1. You could wrap the close() function in a try-except<br>\n",
    "    2. You could re-raise the exception\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```python\n",
    "try:\n",
    "    fh = open('textfile.txt', 'r')\n",
    "except IOError as err:\n",
    "    print(\"ERROR:  {}\".format(err))\n",
    "else:\n",
    "    fh.write('This is my test file for exception handling!!')\n",
    "    print(\"Written content in the file successfully.\")\n",
    "finally:\n",
    "    try:\n",
    "        fh.close()\n",
    "    except NameError as err:\n",
    "        print(\"ERROR:  {}\".format(repr(err)))\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Can You Have An **except** Clause With No Exceptions?\n",
    "\n",
    "If you had something like this:\n",
    "\n",
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "```python\n",
    "try:\n",
    "    # do operation\n",
    "    pass\n",
    "except:\n",
    "    #do something\n",
    "    pass\n",
    "```\n",
    "</div>\n",
    "\n",
    "This is \"bad programming\" because:\n",
    "- it catches ALL exceptions (so it's difficult to troubleshoot)\n",
    "- it does not identify the root cause of an issue that may occur\n",
    "- causes most scripts to have additional unintended bugs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Can You Have Multiple Exceptions?\n",
    "\n",
    "A single try statement can have many exception clauses.\n",
    "\n",
    "For example ...\n",
    "\n",
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "```python\n",
    "try:\n",
    "    # do\n",
    "    pass\n",
    "except Exception0 as e:\n",
    "    # do stuff if Exception0 was triggered\n",
    "    pass\n",
    "except (Exception1[, Exception2[,...ExceptionN]]):\n",
    "    # If there is any of the exceptions listed in the list\n",
    "    # do stuff in this section\n",
    "    pass\n",
    "else:\n",
    "    # If no exception found, execute this block\n",
    "    # else is not required though ... depends on needed logic\n",
    "    pass\n",
    "```\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Defining [Cleanup Actions](https://docs.python.org/3/tutorial/errors.html#defining-clean-up-actions) (try-finally Clause)\n",
    "\n",
    "The `finally` block of code is a place to put any code that MUST execute - regardless of a raised exception.\n",
    "\n",
    "If an exception is thrown, the code in the block is executed followed by the `finally` clause. It is mostly meant for cleaning up resources, including but not limited to:\n",
    "\n",
    "- closing files\n",
    "- closing network sockets\n",
    "- closing database connections\n",
    "\n",
    "A great example of built-in or [predefined clean-up actions](https://docs.python.org/3/tutorial/errors.html#predefined-clean-up-actions) is the **[with()](https://docs.python.org/3/reference/compound_stmts.html#with)** statement."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Click on the image below to learn more about exceptions care of [RealPython](https://realpython.com).\n",
    "\n",
    "<a href=\"https://realpython.com/python-exceptions/#cleaning-up-after-using-finally\">![alt text](https://files.realpython.com/media/try_except_else_finally.a7fac6c36c55.png \"RealPython Intro To Exceptions\")</a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example Good --> Better\n",
    "\n",
    "While you CAN do it this way ...\n",
    "\n",
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "```python\n",
    "try:\n",
    "    fh = open('testfile', 'r')\n",
    "    fh.write('This is my test file for exception handlings!!!')\n",
    "except IOError:\n",
    "    # do something then either gracefully catch or re-raise\n",
    "    print('IOError occurred:  {}'.format(repr(err)))\n",
    "    print('IOError occurred:  {}'.format(err))\n",
    "    # raise\n",
    "finally:\n",
    "    # this happens always\n",
    "    print('Closing file...')\n",
    "    fh.close()\n",
    "```\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Just like it is \"bad programming\" to have a general Exception? If you have multiple statements in the same try-except block, you may have difficulty knowing exactly where you had the issue.\n",
    "\n",
    "This would be better:\n",
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "```python\n",
    "try:\n",
    "    fh = open('testfile.txt', 'r')\n",
    "except IOError as err:\n",
    "    # do something then either gracefully catch or re-raise\n",
    "    print('IOError occurred:  {}'.format(repr(err)))\n",
    "    print('IOError occurred:  {}'.format(err))\n",
    "    # raise\n",
    "else:\n",
    "    fh.write('This is my test file for exception handlings!!!')\n",
    "    print('Closing file...')\n",
    "    fh.close()\n",
    "```\n",
    "Why not put the close() in a finally?\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you've been following along, you've only seen the errors if the file doesn't already exist ... what would happen if:\n",
    "\n",
    "1. The file was there?\n",
    "2. The file existed but the `r` on file open was changed to `r+`?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Can I [Make My Own Exception](https://docs.python.org/3/tutorial/errors.html#user-defined-exceptions)?\n",
    "\n",
    "Yup! The easiest way is to do something like this:\n",
    "\n",
    "```python\n",
    "x = 5\n",
    "if x >= 5:\n",
    "    raise Exception('Error message here.')\n",
    "```\n",
    "\n",
    "But you can read more on it:\n",
    "- [here](https://www.codementor.io/sheena/how-to-write-python-custom-exceptions-du107ufv9#raising-exceptions-on-purpose) from CodeMentor\n",
    "- [here](http://www.tutorialspoint.com/python3/python_exceptions.htm) from TutorialsPoint\n",
    "- [here](https://docs.python.org/3/tutorial/errors.html) from official Python docs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Argument Of An Exception\n",
    "\n",
    "An excpetion's \"argument\" is a value that provides additional information about the problem - also referred to as the **exception object**. It is never a string or number, but it can hold this information as an attribute.\n",
    "\n",
    "The contents of an **exception object** vary by Exception type:\n",
    "- error string\n",
    "- error number\n",
    "- error location\n",
    "\n",
    "Here is the pseudo code:\n",
    "\n",
    "```python\n",
    "try:\n",
    "    # do something\n",
    "    pass\n",
    "exception ExceptionType as Argument:\n",
    "    # do other stuff\n",
    "    pass\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Temperature Change Example**\n",
    "\n",
    "<div class=\"alert alert-success\">\n",
    "\n",
    "```python\n",
    "def num_rtn(temp):\n",
    "    try:\n",
    "        return int(temp)\n",
    "    except ValueError as arg:\n",
    "        print(\"The argument does not contain numbers!\\n\", arg)\n",
    "num_rtn(\"abc\")\n",
    "```\n",
    "</div>\n",
    "\n",
    "What do you expect will happen?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Assertion Statements\n",
    "\n",
    "When used at the beginning of a function, these are great for sanity checks to ensure the inputs are as expected. Though it is suggested to use this in testing, not production code.\n",
    "\n",
    "**Assertion statements** test an expression, that raises an [AssertionError](https://docs.python.org/3/library/exceptions.html#AssertionError) if it renders `False`.\n",
    "\n",
    "This is meant more for a tool of the developers. For while you CAN catch the errors, they are **meant** to crash the program. In other words, if you do not catch them in a try-except statement they will terminate the program."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-success\">\n",
    "<b>Example With Try-Except</b>\n",
    "\n",
    "```python\n",
    "# ----------\n",
    "# Functions\n",
    "# ----------\n",
    "def f1(x):\n",
    "    assert x == 1, \"your_input != 1\" # raised every time evaluates to false\n",
    "\n",
    "def f2(x):\n",
    "    f1(x)\n",
    "\n",
    "def f3(x):\n",
    "    f2(x)\n",
    "\n",
    "# -----------------------\n",
    "# try-except & assertion\n",
    "# -----------------------\n",
    "input_str = input('Provide input:  ')\n",
    "try:\n",
    "    f1(int(input_str)) # try different input to see if Exception is handled\n",
    "\n",
    "# --------------------------------------------------------------\n",
    "# if you tried \"except\" without the \"Exception as some_var_name\"\n",
    "# then you would not know what kind of exception it was\n",
    "# --------------------------------------------------------------\n",
    "except Exception as err:  # giving it a variable name to work with\n",
    "    print(\"caught exception:  {}\". format(repr(err)))\n",
    "\n",
    "# ------------------------------------\n",
    "# default except must be last in 3.6\n",
    "# ------------------------------------\n",
    "except:\n",
    "    print(\"Some stuff happened, right?\")\n",
    "\n",
    "else:\n",
    "    print(\"no exception\")\n",
    "finally:\n",
    "    print('The end! Here was your input:  {}'.format(input_str))\n",
    "```\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Additional Notes & Resources\n",
    "\n",
    "A single **try** statement can have _multiple_ **except** statements.\n",
    "\n",
    "If you have a generic **except Exception** clause, it makes it more difficult to troubleshoot your code.\n",
    "\n",
    "As mentioned prior, the **else** clause option runs if no exception was raised against the code in the **try** block. It is where code should go that doesn't need the **try** block protection.\n",
    "\n",
    "## Different Levels Of Exception\n",
    "\n",
    "`except` is **not** the same as `except Exception`!\n",
    "\n",
    "1. Broadest Exception\n",
    "\n",
    "`except` catches everything that inherits from [BaseException](https://docs.python.org/3/library/exceptions.html#BaseException).\n",
    "\n",
    "2. Less Broad Exception\n",
    "\n",
    "`except Exception` catches everything that inherits from [Exception](https://docs.python.org/3/library/exceptions.html#Exception) - this is better but could still be improved when using things like [TypeError](https://docs.python.org/3/library/exceptions.html#TypeError)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}