code/21-errors-and-exceptions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "📝 **Author:** Amirhossein Heydari - 📧 **Email:** <amirhosseinheydari78@gmail.com> - 📍 **Origin:** [mr-pylin/python-workshop](https://github.com/mr-pylin/python-workshop)\n",
    "\n",
    "---\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Table of contents**<a id='toc0_'></a>    \n",
    "- [Errors and Exceptions](#toc1_)    \n",
    "  - [Exception Handling](#toc1_1_)    \n",
    "    - [`try-except-else-finally`](#toc1_1_1_)    \n",
    "    - [`raise`](#toc1_1_2_)    \n",
    "    - [`assert`](#toc1_1_3_)    \n",
    "\n",
    "<!-- vscode-jupyter-toc-config\n",
    "\tnumbering=false\n",
    "\tanchor=true\n",
    "\tflat=false\n",
    "\tminLevel=1\n",
    "\tmaxLevel=6\n",
    "\t/vscode-jupyter-toc-config -->\n",
    "<!-- THIS CELL WILL BE REPLACED ON TOC UPDATE. DO NOT WRITE YOUR TEXT IN THIS CELL -->"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <a id='toc1_'></a>[Errors and Exceptions](#toc0_)\n",
    "\n",
    "- These are crucial parts of Python programming. Understanding them helps in writing robust, maintainable, and bug-free code.\n",
    "- Python has a sophisticated system for handling errors that allows programs to handle issues gracefully rather than crashing.\n",
    "\n",
    "✍️ **Types of Errors**\n",
    "\n",
    "- **Logical Errors**\n",
    "  - These occur when a program runs without crashing but produces incorrect or unintended results due to a flaw in the logic.\n",
    "  - Logical errors are often harder to identify and fix since they do not raise exceptions.\n",
    "- **Syntax Errors**\n",
    "  - These occur when the parser detects something wrong with the syntax of your program.\n",
    "  - Example: `print(\"Hello World\"` (The closing parenthesis is missing, so Python will raise a `SyntaxError`)\n",
    "- **Runtime Errors (Exceptions)**\n",
    "  - Exceptions are errors detected during the execution of a program.\n",
    "  - Unlike syntax errors, exceptions do not occur when Python tries to parse your code.\n",
    "  - Example: `8/0` (Division by zero is mathematically undefined, so Python will raise a `ZeroDivisionError`)\n",
    "\n",
    "📃 **A list of Exceptions**:\n",
    "<table>\n",
    "  <tr>\n",
    "    <th>Parent class</th>\n",
    "    <th colspan=\"4\">Child class</th>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">object</td>\n",
    "    <td colspan=\"4\" style=\"font-family: monospace;\">BaseException</td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td rowspan=\"2\" style=\"font-family: monospace;\">BaseException</td>\n",
    "    <td style=\"font-family: monospace;\">BaseExceptionGroup</td>\n",
    "    <td style=\"font-family: monospace;\">GeneratorExit</td>\n",
    "    <td style=\"font-family: monospace;\">KeyboardInterrupt</td>\n",
    "    <td style=\"font-family: monospace;\">SystemExit</td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">Exception</td>\n",
    "    <td></td>\n",
    "    <td></td>\n",
    "    <td></td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td rowspan=\"5\" style=\"font-family: monospace;\">Exception</td>\n",
    "    <td style=\"font-family: monospace;\">ArithmeticError</td>\n",
    "    <td style=\"font-family: monospace;\">AssertionError</td>\n",
    "    <td style=\"font-family: monospace;\">AttributeError</td>\n",
    "    <td style=\"font-family: monospace;\">BufferError</td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">EOFError</td>\n",
    "    <td style=\"font-family: monospace;\">ExceptionGroup</td>\n",
    "    <td style=\"font-family: monospace;\">ImportError</td>\n",
    "    <td style=\"font-family: monospace;\">LookupError</td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">MemoryError</td>\n",
    "    <td style=\"font-family: monospace;\">NameError</td>\n",
    "    <td style=\"font-family: monospace;\">OSError</td>\n",
    "    <td style=\"font-family: monospace;\">ReferenceError</td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">RuntimeError</td>\n",
    "    <td style=\"font-family: monospace;\">StopAsyncIteration</td>\n",
    "    <td style=\"font-family: monospace;\">StopIteration</td>\n",
    "    <td style=\"font-family: monospace;\">SyntaxError</td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">SystemError</td>\n",
    "    <td style=\"font-family: monospace;\">TypeError</td>\n",
    "    <td style=\"font-family: monospace;\">ValueError</td>\n",
    "    <td style=\"font-family: monospace;\">Warning</td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">ArithmeticError</td>\n",
    "    <td style=\"font-family: monospace;\">FloatingPointError</td>\n",
    "    <td style=\"font-family: monospace;\">OverflowError</td>\n",
    "    <td style=\"font-family: monospace;\">ZeroDivisionError</td>\n",
    "    <td></td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">BaseExceptionGroup</td>\n",
    "    <td style=\"font-family: monospace;\">ExceptionGroup</td>\n",
    "    <td></td>\n",
    "    <td></td>\n",
    "    <td></td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">ImportError</td>\n",
    "    <td style=\"font-family: monospace;\">ModuleNotFoundError</td>\n",
    "    <td></td>\n",
    "    <td></td>\n",
    "    <td></td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">LookupError</td>\n",
    "    <td style=\"font-family: monospace;\">IndexError</td>\n",
    "    <td style=\"font-family: monospace;\">KeyError</td>\n",
    "    <td></td>\n",
    "    <td></td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">NameError</td>\n",
    "    <td style=\"font-family: monospace;\">UnboundLocalError</td>\n",
    "    <td></td>\n",
    "    <td></td>\n",
    "    <td></td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td rowspan=\"3\" style=\"font-family: monospace;\">OSError</td>\n",
    "    <td style=\"font-family: monospace;\">BlockingIOError</td>\n",
    "    <td style=\"font-family: monospace;\">ChildProcessError</td>\n",
    "    <td style=\"font-family: monospace;\">ConnectionError</td>\n",
    "    <td style=\"font-family: monospace;\">FileExistsError</td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">FileNotFoundError</td>\n",
    "    <td style=\"font-family: monospace;\">InterruptedError</td>\n",
    "    <td style=\"font-family: monospace;\">IsADirectoryError</td>\n",
    "    <td style=\"font-family: monospace;\">NotADirectoryError</td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">PermissionError</td>\n",
    "    <td style=\"font-family: monospace;\">ProcessLookupError</td>\n",
    "    <td style=\"font-family: monospace;\">TimeoutError</td>\n",
    "    <td></td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">ConnectionError</td>\n",
    "    <td style=\"font-family: monospace;\">BrokenPipeError</td>\n",
    "    <td style=\"font-family: monospace;\">ConnectionAbortedError</td>\n",
    "    <td style=\"font-family: monospace;\">ConnectionRefusedError</td>\n",
    "    <td style=\"font-family: monospace;\">ConnectionResetError</td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">RuntimeError</td>\n",
    "    <td style=\"font-family: monospace;\">NotImplementedError</td>\n",
    "    <td style=\"font-family: monospace;\">PythonFinalizationError</td>\n",
    "    <td style=\"font-family: monospace;\">RecursionError</td>\n",
    "    <td></td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">SyntaxError</td>\n",
    "    <td style=\"font-family: monospace;\">IndentationError</td>\n",
    "    <td></td>\n",
    "    <td></td>\n",
    "    <td></td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">IndentationError</td>\n",
    "    <td style=\"font-family: monospace;\">TabError</td>\n",
    "    <td></td>\n",
    "    <td></td>\n",
    "    <td></td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">ValueError</td>\n",
    "    <td style=\"font-family: monospace;\">UnicodeError</td>\n",
    "    <td></td>\n",
    "    <td></td>\n",
    "    <td></td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">UnicodeError</td>\n",
    "    <td style=\"font-family: monospace;\">UnicodeDecodeError</td>\n",
    "    <td style=\"font-family: monospace;\">UnicodeEncodeError</td>\n",
    "    <td style=\"font-family: monospace;\">UnicodeTranslateError</td>\n",
    "    <td></td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td rowspan=\"3\" style=\"font-family: monospace;\">Warning</td>\n",
    "    <td style=\"font-family: monospace;\">BytesWarning</td>\n",
    "    <td style=\"font-family: monospace;\">DeprecationWarning</td>\n",
    "    <td style=\"font-family: monospace;\">EncodingWarning</td>\n",
    "    <td style=\"font-family: monospace;\">FutureWarning</td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">ImportWarning</td>\n",
    "    <td style=\"font-family: monospace;\">PendingDeprecationWarning</td>\n",
    "    <td style=\"font-family: monospace;\">ResourceWarning</td>\n",
    "    <td style=\"font-family: monospace;\">RuntimeWarning</td>\n",
    "  </tr>\n",
    "  <tr>\n",
    "    <td style=\"font-family: monospace;\">SyntaxWarning</td>\n",
    "    <td style=\"font-family: monospace;\">UnicodeWarning</td>\n",
    "    <td style=\"font-family: monospace;\">UserWarning</td>\n",
    "    <td></td>\n",
    "  </tr>\n",
    "</table>\n",
    "\n",
    "📝 **Docs**:\n",
    "\n",
    "- Errors and Exceptions: [docs.python.org/3/tutorial/errors.html](https://docs.python.org/3/tutorial/errors.html)\n",
    "- Built-in Exceptions: [docs.python.org/3/library/exceptions.html](https://docs.python.org/3/library/exceptions.html)\n",
    "- The try statement: [docs.python.org/3/reference/compound_stmts.html#the-try-statement](https://docs.python.org/3/reference/compound_stmts.html#the-try-statement)\n",
    "- The raise statement: [docs.python.org/3/reference/simple_stmts.html#the-raise-statement](https://docs.python.org/3/reference/simple_stmts.html#the-raise-statement)\n",
    "- The assert statement: [docs.python.org/3/reference/simple_stmts.html#the-assert-statement](https://docs.python.org/3/reference/simple_stmts.html#the-assert-statement)\n",
    "- User-defined Exceptions: [docs.python.org/3/tutorial/errors.html#user-defined-exceptions](https://docs.python.org/3/tutorial/errors.html#user-defined-exceptions)\n",
    "\n",
    "🐍 **PEP**:\n",
    "\n",
    "- Exception Chaining and Embedded Tracebacks [[PEP 3134](https://peps.python.org/pep-3134/)]\n",
    "- Suppressing exception context [[PEP 409](https://peps.python.org/pep-0409/)]\n",
    "- Reworking the OS and IO exception hierarchy [[PEP 3151](https://peps.python.org/pep-3151/)]\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# logical error\n",
    "def add_numbers(a: int, b: int) -> int:\n",
    "    return a - b  # should be a + b\n",
    "\n",
    "\n",
    "# log\n",
    "result = add_numbers(3, 5)\n",
    "print(result)  # output will be -2 instead of 8"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# syntax error\n",
    "print(\"Hello World!\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# runtime error\n",
    "print(8 / 0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "num + 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import fake_name"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <a id='toc1_1_'></a>[Exception Handling](#toc0_)\n",
    "\n",
    "- It allows a program to handle errors or exceptional conditions gracefully\n",
    "- Instead of crashing, the program can recover or perform alternative actions.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <a id='toc1_1_1_'></a>[`try-except-else-finally`](#toc0_)\n",
    "\n",
    "- It is used to handle exceptions that might occur during the execution of a program.\n",
    "- This allows the program to continue running, even if an error happens.\n",
    "\n",
    "<figure style=\"text-align: center;\">\n",
    "  <img src=\"../assets/images/svgs/error-try-except.svg\" alt=\"error-try-except.svg\" style=\"width: 75%;\">\n",
    "  <figcaption style=\"text-align:center;\">Try-Except-Else-Finally</figcaption>\n",
    "</figure>\n",
    "\n",
    "🧑‍💻 **General Syntax**:\n",
    "\n",
    "```python\n",
    "    try:\n",
    "        # code that may raise an exception\n",
    "        ...\n",
    "    except ExceptionType1:\n",
    "        # code to handle ExceptionType1\n",
    "        ...\n",
    "    except ExceptionType2 as e:\n",
    "        # code to handle ExceptionType2 with exception object 'e'\n",
    "        ...\n",
    "    else:\n",
    "        # code that runs if no exception occurs in the try block\n",
    "        ...\n",
    "    finally:\n",
    "        # code that always runs, regardless of whether an exception occurred\n",
    "        ...\n",
    "```\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def divide_numbers() -> None:\n",
    "    try:\n",
    "        # get user input\n",
    "        num1 = input(\"Enter the first number: \")\n",
    "        num2 = input(\"Enter the second number: \")\n",
    "\n",
    "        # perform division\n",
    "        result = float(num1) / float(num2)\n",
    "\n",
    "    except ValueError:\n",
    "        # handle non-numeric input\n",
    "        print(f\"Error: Invalid input (num1={num1},num2={num2}). Please enter numeric values.\")\n",
    "\n",
    "    except ZeroDivisionError:\n",
    "        # handle division by zero\n",
    "        print(f\"Error: Cannot divide by zero (num1={num1},num2={num2}).\")\n",
    "\n",
    "    else:\n",
    "        # executes if no exceptions were raised\n",
    "        print(f\"The result of {num1} divided by {num2} is {result}.\")\n",
    "\n",
    "    finally:\n",
    "        # always executes\n",
    "        print(\"Thank you for using the calculator.\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# scenario 1: valid input\n",
    "divide_numbers()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# scenario 2: invalid input\n",
    "divide_numbers()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# scenario 3: division by zero\n",
    "divide_numbers()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <a id='toc1_1_2_'></a>[`raise`](#toc0_)\n",
    "\n",
    "- It is used to trigger an exception manually.\n",
    "- This is useful when you want to signal an error condition explicitly in your program.\n",
    "\n",
    "🧑‍💻 **General Syntax**:\n",
    "\n",
    "```python\n",
    "    raise ExceptionType(\"Error message\")\n",
    "```\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class InsufficientFundsError(Exception):\n",
    "    \"\"\"Custom exception for insufficient funds\"\"\"\n",
    "\n",
    "    pass"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# simulating user interaction with the banking system\n",
    "def withdraw(balance: int, amount: int) -> int:\n",
    "    # raise an exception if the withdrawal amount is negative\n",
    "    if amount < 0:\n",
    "        raise ValueError(\"Withdrawal amount cannot be negative.\")\n",
    "\n",
    "    # raise an exception if there are insufficient funds\n",
    "    if amount > balance:\n",
    "        raise InsufficientFundsError(\n",
    "            f\"Insufficient funds: You tried to withdraw {amount}, but your balance is only {balance}.\"\n",
    "        )\n",
    "\n",
    "    # process the withdrawal if no exceptions\n",
    "    balance -= amount\n",
    "    return balance"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# scenario 1: successful withdrawal\n",
    "balance = 100\n",
    "withdrawal_amount = 90\n",
    "new_balance = withdraw(balance, withdrawal_amount)\n",
    "\n",
    "# log\n",
    "print(f\"new balance : {new_balance}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# scenario 2: insufficient funds\n",
    "balance = 100\n",
    "withdrawal_amount = 110\n",
    "new_balance = withdraw(balance, withdrawal_amount)\n",
    "\n",
    "# log\n",
    "print(f\"new balance : {new_balance}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# scenario 3: negative amount\n",
    "balance = 100\n",
    "withdrawal_amount = -10\n",
    "new_balance = withdraw(balance, withdrawal_amount)\n",
    "\n",
    "# log\n",
    "print(f\"new balance : {new_balance}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <a id='toc1_1_3_'></a>[`assert`](#toc0_)\n",
    "\n",
    "- It is used for testing conditions that should be `true` during program execution.\n",
    "- If the condition evaluates to `False`, it raises an `AssertionError` and optionally provides a message.\n",
    "- Can be disabled globally using the `-O` (optimize) flag when running Python code, making it useful only during development or testing.\n",
    "\n",
    "🧑‍💻 **General Syntax**:\n",
    "\n",
    "```python\n",
    "    assert condition, \"Error message if the assertion fails\"\n",
    "```\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def register_for_event(age: int) -> None:\n",
    "    # assert that the age is a positive number\n",
    "    assert age > 0, \"Age cannot be negative or zero.\"\n",
    "\n",
    "    # assert that the age is within a reasonable range (e.g., below 120)\n",
    "    assert age < 120, \"Age exceeds the realistic limit.\"\n",
    "\n",
    "    # check if the user is eligible for the event (age must be 18 or above)\n",
    "    assert age >= 18, \"User must be at least 18 years old to register.\"\n",
    "\n",
    "    print(\"Registration successful. Welcome to the event!\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# scenario 1: valid age\n",
    "register_for_event(19)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# scenario 2: negative age\n",
    "register_for_event(-2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# scenario 3: age below event requirement\n",
    "register_for_event(16)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# scenario 4: unrealistic age\n",
    "register_for_event(200)"
   ]
  }
 ],
 "metadata": {
  "author_email": "AmirhosseinHeydari78@gmail.com",
  "author_github": "https://github.com/mr-pylin",
  "author_name": "Amirhossein Heydari",
  "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.12.3"
  },
  "origin_repo": "https://github.com/mr-pylin/python-workshop"
 },
 "nbformat": 4,
 "nbformat_minor": 2
}