02 Error Handling.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Exception Handling\n",
    "\n",
    "Python has built-in exception handling you can use with Try/Except statements. PyEZ predefined exceptions are located in `jnpr.junos.exception`.\n",
    "\n",
    "You first need to import the exceptions.You can import individual exceptions like this:\n",
    "\n",
    "```python\n",
    "# Device errors\n",
    "from jnpr.junos.exception import ConnectError\n",
    "from jnpr.junos.exception import ConnectTimeoutError\n",
    "from jnpr.junos.exception import ConnectAuthError\n",
    "from jnpr.junos.exception import ConnectRefusedError\n",
    "# Config errors\n",
    "from jnpr.junos.exception import LockError\n",
    "from jnpr.junos.exception import UnlockError\n",
    "from jnpr.junos.exception import ConfigLoadError\n",
    "from jnpr.junos.exception import CommitError\n",
    "```\n",
    "\n",
    "You can also import all exceptions with:\n",
    "\n",
    "```python\n",
    "from jnpr.junos.exception import *\n",
    "```\n",
    "\n",
    "With all of the exceptions imported you can now take action on a per-exception basis."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example: Exception Handling\n",
    "\n",
    "Here is an example where we will purposefully connect to a device on the wrong port to induce a `ConnectTimeoutError`.\n",
    "\n",
    "Try changing the host/user/password/port values to generate different types of errors.\n",
    "\n",
    "Hint: use 127.0.0.2 for a `ConnectRefusedError`.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from jnpr.junos import Device\n",
    "from jnpr.junos.exception import ConnectError\n",
    "from jnpr.junos.exception import ConnectTimeoutError\n",
    "from jnpr.junos.exception import ConnectAuthError\n",
    "from jnpr.junos.exception import ConnectRefusedError\n",
    "\n",
    "try:\n",
    "    dev = Device(host='10.0.0.180', user='root', password='Juniper', port='222')\n",
    "    dev.open()\n",
    "except ConnectTimeoutError as err:\n",
    "    print (\"Timeout: {0}\".format(err))\n",
    "except ConnectAuthError as err:\n",
    "    print (\"Auth Error: {0}\".format(err))\n",
    "except ConnectRefusedError as err:\n",
    "    print (\"Refused: {0}\".format(err))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## No exception handling\n",
    "Compare the output above to the output of the cell below where there is no error handling:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from jnpr.junos import Device\n",
    "from jnpr.junos import exception\n",
    "\n",
    "dev = Device(host='10.0.0.180', user='root', password='Juniper', port='222')\n",
    "dev.open()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example: No exception handling\n",
    "\n",
    "```python\n",
    "---------------------------------------------------------------------------\n",
    "SSHError                                  Traceback (most recent call last)\n",
    "/opt/conda/lib/python3.5/site-packages/jnpr/junos/device.py in open(self, *vargs, **kvargs)\n",
    "    875                 ssh_config=self._sshconf_lkup(),\n",
    "--> 876                 device_params={'name': 'junos', 'local': False})\n",
    "    877 \n",
    "\n",
    "/opt/conda/lib/python3.5/site-packages/ncclient/manager.py in connect(*args, **kwds)\n",
    "    152         else:\n",
    "--> 153             return connect_ssh(*args, **kwds)\n",
    "    154 \n",
    "\n",
    "/opt/conda/lib/python3.5/site-packages/ncclient/manager.py in connect_ssh(*args, **kwds)\n",
    "    117     try:\n",
    "--> 118        session.connect(*args, **kwds)\n",
    "    119     except Exception as ex:\n",
    "\n",
    "/opt/conda/lib/python3.5/site-packages/ncclient/transport/ssh.py in connect(self, host, port, timeout, unknown_host_cb, username, password, key_filename, allow_agent, hostkey_verify, look_for_keys, ssh_config)\n",
    "    368             else:\n",
    "--> 369                 raise SSHError(\"Could not open socket to %s:%s\" % (host, port))\n",
    "    370 \n",
    "\n",
    "SSHError: Could not open socket to 10.0.0.181:222\n",
    "\n",
    "During handling of the above exception, another exception occurred:\n",
    "\n",
    "ConnectRefusedError                       Traceback (most recent call last)\n",
    "<ipython-input-13-90c69cb002fa> in <module>()\n",
    "      3 \n",
    "      4 dev = Device(host='10.0.0.181', user='root', password='Juniper', port='222')\n",
    "----> 5 dev.open()\n",
    "\n",
    "/opt/conda/lib/python3.5/site-packages/jnpr/junos/device.py in open(self, *vargs, **kvargs)\n",
    "    891             diff_ts = ts_err - ts_start\n",
    "    892             if diff_ts.seconds < 3:\n",
    "--> 893                 raise EzErrors.ConnectRefusedError(self)\n",
    "    894 \n",
    "    895             # at this point, we assume that the connection\n",
    "\n",
    "ConnectRefusedError: ConnectRefusedError(10.0.0.181)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Catching all exceptions\n",
    "\n",
    "Python's highest level exception is `BaseException`. Using this exception you can catch all other exceptions. This is useful if you want brevity of code (*read: lazy*)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from jnpr.junos import Device\n",
    "from jnpr.junos import exception\n",
    "try:\n",
    "    dev = Device(host='10.0.0.180', user='root', password='Juniper', port='222')\n",
    "    dev.open()\n",
    "except BaseException as err:\n",
    "    print (\"Cannot connect to device: {0}\".format(err))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Why Exception Handling\n",
    "\n",
    "Without exception handling any exceptions which occur will generate unsightly output which may not make much sense to your user. \n",
    "\n",
    "However with exception handling you can display more appropriate messages and more importantly, now take action depending on the exception.\n",
    "\n",
    "For example, if authentication fails you can prompt the user for the passwrod again. If locking the configuration database fails you can trigger a cooldown to wait for any existing config to be committed and try again."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Full Example\n",
    "\n",
    "This script was pulled from the PyEZ developer guide as an example of exception handling throughout the script.\n",
    "\n",
    "```python\n",
    "from jnpr.junos import Device\n",
    "from jnpr.junos.utils.config import Config\n",
    "from jnpr.junos.exception import ConnectError\n",
    "from jnpr.junos.exception import LockError\n",
    "from jnpr.junos.exception import UnlockError\n",
    "from jnpr.junos.exception import ConfigLoadError\n",
    "from jnpr.junos.exception import CommitError\n",
    "\n",
    "host = 'dc1a.example.com'\n",
    "conf_file = 'configs/junos-config-add-op-script.conf'\n",
    "\n",
    "\n",
    "def main():\n",
    "    # open a connection with the device and start a NETCONF session\n",
    "    try:\n",
    "        dev = Device(host=host)\n",
    "        dev.open()\n",
    "    except ConnectError as err:\n",
    "        print (\"Cannot connect to device: {0}\".format(err))\n",
    "        return\n",
    "\n",
    "    dev.bind(cu=Config)\n",
    "\n",
    "    # Lock the configuration, load configuration changes, and commit\n",
    "    print (\"Locking the configuration\")\n",
    "    try:\n",
    "        dev.cu.lock()\n",
    "    except LockError as err:\n",
    "        print (\"Unable to lock configuration: {0}\".format(err))\n",
    "        dev.close()\n",
    "        return\n",
    "\n",
    "    print (\"Loading configuration changes\")\n",
    "    try:\n",
    "        dev.cu.load(path=conf_file, merge=True)\n",
    "    except (ConfigLoadError, Exception) as err:\n",
    "        print (\"Unable to load configuration changes: {0}\".format(err))\n",
    "        print (\"Unlocking the configuration\")\n",
    "        try:\n",
    "                dev.cu.unlock()\n",
    "        except UnlockError:\n",
    "            print (\"Unable to unlock configuration: {0}\".format(err))\n",
    "        dev.close()\n",
    "        return\n",
    "\n",
    "    print (\"Committing the configuration\")\n",
    "    try:\n",
    "        dev.cu.commit(comment='Loaded by example.')\n",
    "    except CommitError as err:\n",
    "        print (\"Unable to commit configuration: {0}\".format(err))\n",
    "        print (\"Unlocking the configuration\")\n",
    "        try:\n",
    "            dev.cu.unlock()\n",
    "        except UnlockError as err:\n",
    "            print (\"Unable to unlock configuration: {0}\".format(err))\n",
    "        dev.close()\n",
    "        return\n",
    "\n",
    "    print (\"Unlocking the configuration\")\n",
    "    try:\n",
    "        dev.cu.unlock()\n",
    "    except UnlockError as err:\n",
    "        print (\"Unable to unlock configuration: {0}\".format(err))\n",
    "\n",
    "    # End the NETCONF session and close the connection\n",
    "    dev.close()\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    main()\n",
    "```"
   ]
  }
 ],
 "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.5.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}