005_Python_User_defined_Exceptions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<small><small><i>\n",
    "All the IPython Notebooks in **Python Files** lecture series by **[Dr. Milaan Parmar](https://www.linkedin.com/in/milaanparmar/)** are available @ **[GitHub](https://github.com/milaan9/05_Python_Files)**\n",
    "</i></small></small>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Python Custom Exceptions\n",
    "\n",
    "In this class, you will learn how to define custom exceptions depending upon your requirements with the help of examples.\n",
    "\n",
    "Python has numerous **[built-in exceptions](https://github.com/milaan9/05_Python_Files/blob/main/003_Python_File_Exception.ipynb)** that force your program to output an error when something in the program goes wrong.\n",
    "\n",
    "However, sometimes you may need to create your own custom exceptions that serve your purpose."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating Custom Exceptions\n",
    "\n",
    "In Python, users can define custom exceptions by creating a new class. This exception class has to be derived, either directly or indirectly, from the built-in **`Exception`** class. Most of the built-in exceptions are also derived from this class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-18T17:19:27.045590Z",
     "start_time": "2021-06-18T17:19:27.028011Z"
    }
   },
   "outputs": [],
   "source": [
    "class CustomError(Exception):\n",
    "    pass"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-18T17:19:28.105637Z",
     "start_time": "2021-06-18T17:19:27.828299Z"
    }
   },
   "outputs": [
    {
     "ename": "CustomError",
     "evalue": "",
     "output_type": "error",
     "traceback": [
      "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[1;31mCustomError\u001b[0m                               Traceback (most recent call last)",
      "\u001b[1;32m<ipython-input-2-dfca0b041b3d>\u001b[0m in \u001b[0;36m<module>\u001b[1;34m\u001b[0m\n\u001b[1;32m----> 1\u001b[1;33m \u001b[1;32mraise\u001b[0m \u001b[0mCustomError\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[1;31mCustomError\u001b[0m: "
     ]
    }
   ],
   "source": [
    "raise CustomError"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-18T17:19:28.901530Z",
     "start_time": "2021-06-18T17:19:28.883955Z"
    }
   },
   "outputs": [
    {
     "ename": "CustomError",
     "evalue": "An error occurred",
     "output_type": "error",
     "traceback": [
      "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[1;31mCustomError\u001b[0m                               Traceback (most recent call last)",
      "\u001b[1;32m<ipython-input-3-d75c9779269a>\u001b[0m in \u001b[0;36m<module>\u001b[1;34m\u001b[0m\n\u001b[1;32m----> 1\u001b[1;33m \u001b[1;32mraise\u001b[0m \u001b[0mCustomError\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;34m\"An error occurred\"\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[1;31mCustomError\u001b[0m: An error occurred"
     ]
    }
   ],
   "source": [
    "raise CustomError(\"An error occurred\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, we have created a user-defined exception called **`CustomError`** which inherits from the **`Exception`** class. This new exception, like other exceptions, can be raised using the **`raise`** statement with an optional error message.\n",
    "\n",
    "When we are developing a large Python program, it is a good practice to place all the user-defined exceptions that our program raises in a separate file. Many standard modules do this. They define their exceptions separately as **`exceptions.py`** or **`errors.py`** (generally but not always).\n",
    "\n",
    "User-defined exception class can implement everything a normal class can do, but we generally make them simple and concise. Most implementations declare a custom base class and derive others exception classes from this base class. This concept is made clearer in the following example."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example: User-Defined Exception in Python\n",
    "\n",
    "In this example, we will illustrate how user-defined exceptions can be used in a program to raise and catch errors.\n",
    "\n",
    "This program will ask the user to enter a number until they guess a stored number correctly. To help them figure it out, a hint is provided whether their guess is greater than or less than the stored number."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-18T17:19:35.140743Z",
     "start_time": "2021-06-18T17:19:31.339989Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Enter a number: 9\n",
      "This value is too small, try again!\n",
      "\n",
      "Enter a number: 10\n",
      "Congratulations! You guessed it correctly.\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "'\\n**Output**:\\n\\nEnter a number: 12\\nThis value is too large, try again!\\n\\nEnter a number: 0\\nThis value is too small, try again!\\n\\nEnter a number: 8\\nThis value is too small, try again!\\n\\nEnter a number: 10\\nCongratulations! You guessed it correctly.\\n'"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# define Python user-defined exceptions\n",
    "class Error(Exception):\n",
    "    \"\"\"Base class for other exceptions\"\"\"\n",
    "    pass\n",
    "\n",
    "\n",
    "class ValueTooSmallError(Error):\n",
    "    \"\"\"Raised when the input value is too small\"\"\"\n",
    "    pass\n",
    "\n",
    "\n",
    "class ValueTooLargeError(Error):\n",
    "    \"\"\"Raised when the input value is too large\"\"\"\n",
    "    pass\n",
    "\n",
    "\n",
    "# you need to guess this number\n",
    "number = 10\n",
    "\n",
    "# user guesses a number until he/she gets it right\n",
    "while True:\n",
    "    try:\n",
    "        i_num = int(input(\"Enter a number: \"))\n",
    "        if i_num < number:\n",
    "            raise ValueTooSmallError\n",
    "        elif i_num > number:\n",
    "            raise ValueTooLargeError\n",
    "        break\n",
    "    except ValueTooSmallError:\n",
    "        print(\"This value is too small, try again!\")\n",
    "        print()\n",
    "    except ValueTooLargeError:\n",
    "        print(\"This value is too large, try again!\")\n",
    "        print()\n",
    "\n",
    "print(\"Congratulations! You guessed it correctly.\")\n",
    "\n",
    "\n",
    "'''\n",
    "**Output**:\n",
    "\n",
    "Enter a number: 12\n",
    "This value is too large, try again!\n",
    "\n",
    "Enter a number: 0\n",
    "This value is too small, try again!\n",
    "\n",
    "Enter a number: 8\n",
    "This value is too small, try again!\n",
    "\n",
    "Enter a number: 10\n",
    "Congratulations! You guessed it correctly.\n",
    "'''"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Explanation**:\n",
    "\n",
    "We have defined a base class called **`Error`**.\n",
    "\n",
    "The other two exceptions (**`ValueTooSmallError`** and **`ValueTooLargeError`**) that are actually raised by our program are derived from this class. This is the standard way to define user-defined exceptions in Python programming, but you are not limited to this way only."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Customizing Exception Classes\n",
    "\n",
    "We can further customize this class to accept other arguments as per our needs.\n",
    "\n",
    "To learn about customizing the Exception classes, you need to have the basic knowledge of **[Python Object-Oriented programming](https://github.com/milaan9/06_Python_Object_Class/blob/main/001_Python_OOPs_Concepts.ipynb)**.\n",
    "\n",
    "For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-18T17:19:44.198773Z",
     "start_time": "2021-06-18T17:19:39.516192Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Enter salary amount: 3000\n"
     ]
    },
    {
     "ename": "SalaryNotInRangeError",
     "evalue": "Salary is not in (5000, 15000) range",
     "output_type": "error",
     "traceback": [
      "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[1;31mSalaryNotInRangeError\u001b[0m                     Traceback (most recent call last)",
      "\u001b[1;32m<ipython-input-5-7e786bcbd078>\u001b[0m in \u001b[0;36m<module>\u001b[1;34m\u001b[0m\n\u001b[0;32m     15\u001b[0m \u001b[0msalary\u001b[0m \u001b[1;33m=\u001b[0m \u001b[0mint\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0minput\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;34m\"Enter salary amount: \"\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[0;32m     16\u001b[0m \u001b[1;32mif\u001b[0m \u001b[1;32mnot\u001b[0m \u001b[1;36m5000\u001b[0m \u001b[1;33m<\u001b[0m \u001b[0msalary\u001b[0m \u001b[1;33m<\u001b[0m \u001b[1;36m15000\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m---> 17\u001b[1;33m     \u001b[1;32mraise\u001b[0m \u001b[0mSalaryNotInRangeError\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0msalary\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m     18\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m     19\u001b[0m '''\n",
      "\u001b[1;31mSalaryNotInRangeError\u001b[0m: Salary is not in (5000, 15000) range"
     ]
    }
   ],
   "source": [
    "class SalaryNotInRangeError(Exception):\n",
    "    \"\"\"Exception raised for errors in the input salary.\n",
    "\n",
    "    Attributes:\n",
    "        salary -- input salary which caused the error\n",
    "        message -- explanation of the error\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, salary, message=\"Salary is not in (5000, 15000) range\"):\n",
    "        self.salary = salary\n",
    "        self.message = message\n",
    "        super().__init__(self.message)\n",
    "\n",
    "\n",
    "salary = int(input(\"Enter salary amount: \"))\n",
    "if not 5000 < salary < 15000:\n",
    "    raise SalaryNotInRangeError(salary)\n",
    "    \n",
    "'''\n",
    "**Output**:\n",
    "\n",
    "Enter salary amount: 3000\n",
    "\n",
    "SalaryNotInRangeError                     Traceback (most recent call last)\n",
    "<ipython-input-10-6ab0f28c63a7> in <module>\n",
    "     15 salary = int(input(\"Enter salary amount: \"))\n",
    "     16 if not 5000 < salary < 15000:\n",
    "---> 17     raise SalaryNotInRangeError(salary)\n",
    "\n",
    "SalaryNotInRangeError: Salary is not in (5000, 15000) range\n",
    "'''"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Explanation:**\n",
    "\n",
    "Here, we have overridden the constructor of the **`Exception`** class to accept our own custom arguments **`salary`** and **`message`**. Then, the constructor of the parent **`Exception`** class is called manually with the **`self.message`** argument using **`super()`**.\n",
    "\n",
    "The custom **`self.salary`** attribute is defined to be used later.\n",
    "\n",
    "The inherited **`__str__`** method of the **`Exception`** class is then used to display the corresponding message when **`SalaryNotInRangeError`** is raised."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also customize the **`__str__`** method itself by overriding it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-06-18T17:20:11.265939Z",
     "start_time": "2021-06-18T17:20:08.927580Z"
    },
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Enter salary amount: 3000\n"
     ]
    },
    {
     "ename": "SalaryNotInRangeError",
     "evalue": "3000 -> Salary is not in (5000, 15000) range",
     "output_type": "error",
     "traceback": [
      "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[1;31mSalaryNotInRangeError\u001b[0m                     Traceback (most recent call last)",
      "\u001b[1;32m<ipython-input-6-3681b3969e27>\u001b[0m in \u001b[0;36m<module>\u001b[1;34m\u001b[0m\n\u001b[0;32m     18\u001b[0m \u001b[0msalary\u001b[0m \u001b[1;33m=\u001b[0m \u001b[0mint\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0minput\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;34m\"Enter salary amount: \"\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[0;32m     19\u001b[0m \u001b[1;32mif\u001b[0m \u001b[1;32mnot\u001b[0m \u001b[1;36m5000\u001b[0m \u001b[1;33m<\u001b[0m \u001b[0msalary\u001b[0m \u001b[1;33m<\u001b[0m \u001b[1;36m15000\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m---> 20\u001b[1;33m     \u001b[1;32mraise\u001b[0m \u001b[0mSalaryNotInRangeError\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0msalary\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m     21\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m     22\u001b[0m '''\n",
      "\u001b[1;31mSalaryNotInRangeError\u001b[0m: 3000 -> Salary is not in (5000, 15000) range"
     ]
    }
   ],
   "source": [
    "class SalaryNotInRangeError(Exception):\n",
    "    \"\"\"Exception raised for errors in the input salary.\n",
    "\n",
    "    Attributes:\n",
    "        salary -- input salary which caused the error\n",
    "        message -- explanation of the error\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, salary, message=\"Salary is not in (5000, 15000) range\"):\n",
    "        self.salary = salary\n",
    "        self.message = message\n",
    "        super().__init__(self.message)\n",
    "\n",
    "    def __str__(self):\n",
    "        return f'{self.salary} -> {self.message}'\n",
    "\n",
    "\n",
    "salary = int(input(\"Enter salary amount: \"))\n",
    "if not 5000 < salary < 15000:\n",
    "    raise SalaryNotInRangeError(salary)\n",
    "    \n",
    "'''\n",
    "**Output**:\n",
    "\n",
    "Enter salary amount: 3000\n",
    "\n",
    "SalaryNotInRangeError                     Traceback (most recent call last)\n",
    "<ipython-input-12-c454c1331524> in <module>\n",
    "     18 salary = int(input(\"Enter salary amount: \"))\n",
    "     19 if not 5000 < salary < 15000:\n",
    "---> 20     raise SalaryNotInRangeError(salary)\n",
    "\n",
    "SalaryNotInRangeError: 3000 -> Salary is not in (5000, 15000) range\n",
    "'''"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To learn more about how you can handle exceptions in Python, visit **[Python Exception Handling](https://github.com/milaan9/05_Python_Files/blob/main/004_Python_Exceptions_Handling.ipynb)**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "hide_input": false,
  "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.8.8"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}