lecture_08_modules_input_errors.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Making your own modules"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If a function will be used in multiple programs, it should be written \n",
    "as a module instead. \n",
    "\n",
    "All one has to do is put the functions in a program_name.py\n",
    "file and import it (the whole thing) or the functions, then \n",
    "use them in the main program.\n",
    "\n",
    "Exactly the same way how you import and use other libraries.\n",
    "\n",
    "## Example\n",
    "Given mass and velocity, this function calculates the kinetic energy of a particle\n",
    "in meters/kilograms/seconds (mks) units."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$E_k = \\frac{1}{2} \\cdot mv^2$$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "def eKinetic(mass, velocity):\n",
    "    return 0.5 * mass * velocity**2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "eKinetic(1, 10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q. What will the output be?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following function calculates the x, y, and z accelerations \n",
    "of a particle resulting from forces acting upon it given its mass.\n",
    "\n",
    "All units are SI."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$a=\\frac{F}{m}$ rearranged from $F=ma$\n",
    "\n",
    "> Note: These techniques are also related to some of the tasks in the homework and the final project."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "def acceleration(xForce, yForce, zForce, mass):\n",
    "    xAccel = float(xForce) / float(mass)\n",
    "    yAccel = float(yForce) / float(mass)\n",
    "    zAccel = float(zForce) / float(mass)\n",
    "    \n",
    "    return (xAccel, yAccel, zAccel)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q. What will this do?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "acceleration(10, 20, 30, 5)"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "I put eKinetic and acceleration in a module called kinematics.py using a text editor.\n",
    "\n",
    "Now, try the module in an IPython session:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# remember that this line overwrites the local definition\n",
    "# because it has the same name as above!\n",
    "\n",
    "from kinematics import eKinetic, acceleration\n",
    "\n",
    "mass = 100\n",
    "velocity = 10\n",
    "xForce = 10\n",
    "yForce = 20\n",
    "zForce = 30\n",
    "\n",
    "kEnergy = eKinetic(mass, velocity)\n",
    "mAccel = acceleration(xForce, yForce, zForce, mass)\n",
    "\n",
    "kEnergy, mAccel"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Providing program arguments on the command-line"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Input is often supplied to Python scripts via the command line.\n",
    "\n",
    "Put another way, \"arguments\" are provided to scripts.\n",
    "\n",
    "Here are some Linux examples:\n",
    "\n",
    "```bash\n",
    "echo $PATH\n",
    "```    \n",
    "\n",
    "echo is the command, `$PATH` is an argument. Or, \n",
    "\n",
    "```bash\n",
    "cd some_directory\n",
    "```\n",
    "\n",
    "cd is the commmand, `some_directory` is an argument.\n",
    "\n",
    "```bash\n",
    "    cd\n",
    "```\n",
    "\n",
    "No arguments here -- default behavior: cd $HOME"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can do the same sort of thing in Python using the sys module. \n",
    "The following script (lecture_08_wavetofreq.py) converts a \n",
    "user-supplied wavelength (in Angstroms) to frequency (in Hz).\n",
    "\n",
    "I show you here how to quickly load an existing script into the notebook, using %load:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# %load lecture_08_wavetofreq.py\n",
    "#!/usr/bin/env python\n",
    "\n",
    "import sys\n",
    "wave = float(sys.argv[1])\n",
    "freq = 3.0e8 / (wave / 1e10)\n",
    "print('frequency (Hz) = %e' % freq)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import sys                   # \"sys\" is short for \"system\"\n",
    "wave = float(sys.argv[1])\n",
    "freq = 3.0e8 / (wave / 1e10) # pass wavelength in Angstroms\n",
    "print('frequency (Hz) = %e' % freq)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "sys.argv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "sys.argv contains a list of the command line arguments to the program. \n",
    "\n",
    "sys.argv[0] is always the name of the program."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To run it in a Linux terminal (must be in same directory as file):\n",
    "\n",
    "```bash\n",
    "python lecture_08_wavetofreq.py 5000\n",
    "```\n",
    "\n",
    "To run it within here or a simple ipython terminal (file must be in same directory that you \n",
    "launched the notebook from):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%run lecture_08_wavetofreq.py 5000"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q. What if there is more than one command-line input required?"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Consider the following script:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import sys\n",
    "\n",
    "for i, element in enumerate(sys.argv):\n",
    "    print(\"Argument #{} = {}\".format(i, element))"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "I have it saved in a file called lecture_08_systest.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q. What will the following command do in a Linux session?"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "python lecture_08_systest.py 'hello' 2 4 6"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You will practice with sys in the tutorial!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%run lecture_08_systest.py 'hello' 2 4 6"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Error Handling"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The script lecture_08_wavetofreq.py expects an argument, the \n",
    "wavelength in Angstroms:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# lecture_08_wavetofreq.py\n",
    "\n",
    "import sys\n",
    "wave = float(sys.argv[1])          # Attempting to use the argument here.\n",
    "freq = 3.0e8 / (wave / 1e10)       # Convert wavelength in Angstroms to frequency in Hz\n",
    "print('frequency (Hz) = %e' % freq)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we forget to supply that argument, we get an error message:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%run lecture_08_wavetofreq.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It tells us what file and what line where the error occured and \n",
    "the type of error (IndexError)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q. What is a simple way we could tell if the user forgot the  argument and exit the program gracefully without a crash?"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Hint:  Where are the arguments held again?"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "We could test the length of sys.argv and if it is < 2; if so, we could \n",
    "abort with an error message (this script is saved in \n",
    "lecture_08_wavetofreq2.py):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# lecture_08_wavetofreq2.py\n",
    "\n",
    "import sys\n",
    "\n",
    "if len(sys.argv) < 2:\n",
    "    print('Enter the wavelength in Angstroms on the command line.')\n",
    "    sys.exit(1) # Exits and 1 indicates failure\n",
    "                # sys.exit() or sys.exit(0) is used to indicate success\n",
    "\n",
    "wave = float(sys.argv[1])\n",
    "freq = 3.0e8 / (wave / 1e10)\n",
    "print('frequency (Hz) = %e' % freq )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q. What will the following yield?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%run lecture_08_wavetofreq2.py 5000"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q. And this?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%run lecture_08_wavetofreq2.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%tb"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exception Handling"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, the program can try to run the code and \n",
    "if errors are found, jump to statements that handle \n",
    "the error as desired.\n",
    "\n",
    "This is done with two new reserved words, \"try\" and \"except\", \n",
    "which are used in a similar way as \"if\" and \"elif\". "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is the script lecture_08_wavetofreq3.py:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# lecture_08_wavetofreq3.py\n",
    "\n",
    "import sys\n",
    "\n",
    "try:\n",
    "    wave = float(sys.argv[1])\n",
    "except:\n",
    "    print('Enter the wavelength in Angstroms on the command line.')\n",
    "    sys.exit(1)\n",
    "\n",
    "freq = 3.0e8 / (wave / 1e10)\n",
    "print('frequency (Hz) = %e' % freq)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the command in the try block produces an error, the except block \n",
    "is executed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q. What does \"wave = float(sys.argv[1])\" attempt to do?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q. What if we try to do the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%run lecture_08_wavetofreq3.py x"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%tb"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> The program could also fail if something other than a number is given \n",
    "on the command line!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That produces a ValueError, not an IndexError.\n",
    "\n",
    "We can fix this with two separate exceptions appropriate for the two \n",
    "possible errors (this is similar to if/elif/elif):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# lecture_08_wavetofreq4.py\n",
    "\n",
    "import sys\n",
    "\n",
    "try:\n",
    "    wave = float(sys.argv[1])\n",
    "    \n",
    "except IndexError:\n",
    "    print('Enter the wavelength in Angstroms on the command line.')\n",
    "    sys.exit(1)\n",
    "\n",
    "except ValueError as error:\n",
    "    #print 'The wavelength must be a number'\\\n",
    "    #' not %s.' % type(sys.argv[1])\n",
    "    print(\"The error is:\", error)\n",
    "    sys.exit(2)\n",
    "\n",
    "freq = 3.0e8 / (wave / 1e10)\n",
    "print('frequency (Hz) = %e' % freq)"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "This script is saved in the file lecture_08_wavetofreq4.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q. What do these yield?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%run lecture_08_wavetofreq4.py 5000"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%run lecture_08_wavetofreq4.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%run lecture_08_wavetofreq4.py x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Common error types"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "IndexError for indices out of range:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "data = range(9)\n",
    "data[9]"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Q. Why does it fail?\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Converting a str to a float gives a ValueError:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "y = float('x')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "y = float('3')\n",
    "y"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Using an uninitialized variable gives a NameError:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "x"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Division by zero raises a ZeroDivisionError exception:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "4.0/0"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Syntax errors lead to SyntaxErrors!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "iff 2 > 1:\n",
    "    print('it is.')"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Multiplying a string by a float yields a TypeError:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "10.0 * 'blah'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Q. But what will this do?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "5 * 'blah '"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Nice flowchart on error handling (http://i.imgur.com/WRuJV6r.png):\n",
    "\n",
    "![errors](http://i.imgur.com/WRuJV6r.png \"Error handling\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python3 (stable)",
   "language": "python",
   "name": "stable"
  },
  "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.1"
  },
  "widgets": {
   "state": {},
   "version": "1.1.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}