week05_input_validation.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Week 05 Functions\n",
    "\n",
    "Input validation is the process of testing the argument values supplied by a caller to confirm if they\n",
    "satisfy the preconditions of the function. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Input validation\n",
    "\n",
    "Functions that have simple preconditions should usually test if the preconditions are true before doing\n",
    "anything else. For example, consider the following function that returns the real-valued square root of `x`:\n",
    "\n",
    "```python\n",
    "import math\n",
    "\n",
    "def real_sqrt(x):\n",
    "    if x <= 0:\n",
    "        raise ValueError('cannot compute the real square root of a negative value')\n",
    "    return math.sqrt(x)\n",
    "```\n",
    "\n",
    "`real_sqrt` has the precondition that `x` must be a non-negative value because a negative value does not have \n",
    "a real valued square root.\n",
    "`real_sqrt` tests if the value of the parameter `x` violates the precondition; if it does, then the function\n",
    "raises a `ValueError` exception which causes the function to stop running. Testing preconditions involving\n",
    "the parameters is called *input validation*. Calling `real_sqrt` with a non-negative value allows `real_sqrt`\n",
    "to satisfy its postcondition (return the real-valued square root of `x`), but calling `real_sqrt` with a\n",
    "negative value causes `real_sqrt` to immediately stop running (run the following cell):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import math\n",
    "\n",
    "def real_sqrt(x):\n",
    "    if x <= 0:\n",
    "        raise ValueError('real_sqrt() not defined for a negative value, x = ' + str(x))\n",
    "    return math.sqrt(x)\n",
    "\n",
    "y = real_sqrt(16)\n",
    "print(y)\n",
    "\n",
    "y = real_sqrt(-16)\n",
    "print(y)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that it is useful for the caller if the exception message includes information about the value of the \n",
    "argument that caused the exception to be raised. In the exception message in `real_sqrt`, the value of `x` is\n",
    "included in the message.\n",
    "\n",
    "Consider writing a function that returns the last element of a sequence `t`. Such a method would have the\n",
    "precondition that `t` not be empty. Python sequences are considered to be equal to `False` if they are empty\n",
    "so we can perform input validation in the `last` function like so:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def last(t):\n",
    "    if not t:    # Python idiom for testing for an empty list\n",
    "        raise ValueError('last() no last element of an empty list')\n",
    "    return t[-1]\n",
    "\n",
    "\n",
    "t = [1, 2, 3]\n",
    "print(last(t))\n",
    "\n",
    "t = []\n",
    "print(last(t))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A slightly more complicated example of input validation occurs when writing a function that converts \n",
    "a time on a 12-hour clock to the number of minutes after midnight. The function is called with arguments\n",
    "representing the hour, the minute, and a string that is equal to either `AM` or `PM`; for example:\n",
    "\n",
    "```python\n",
    "minutes = to_minutes(12, 15, 'PM')    # 12:15 PM\n",
    "```\n",
    "\n",
    "The preconditions of `to_minutes` are:\n",
    "\n",
    "* the hour must be between 1 and 12 (inclusive)\n",
    "* the minute must be between 0 and 59 (inclusive)\n",
    "* the indicator must be equal to `AM` or `PM`\n",
    "\n",
    "The function might be implemented like so:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def to_minute(hour, minute, indicator):\n",
    "    if hour < 1 or hour > 12:\n",
    "        raise ValueError('to_minute() hour must be between 1 and 12, hour = ' + str(hour))\n",
    "    if minute < 0 or minute > 59:\n",
    "        raise ValueError('to_minute() hour must be between 0 and 59, minute = ' + str(minute))\n",
    "    if indicator != 'AM' and indicator != 'PM':\n",
    "        raise ValueError('to_minute() indicator must be \\'AM\\' or \\'PM\\', indicator = ' + indicator)\n",
    "    \n",
    "    MIN_PER_HOUR = 60\n",
    "    result = (hour % 12) * MIN_PER_HOUR + minute\n",
    "    if indicator == 'PM':\n",
    "        result += 12 * MIN_PER_HOUR\n",
    "    return result\n",
    "        \n",
    "\n",
    "minutes = to_minute(12, 0, 'AM')\n",
    "print('12:00AM = ', minutes, 'minutes after midnight')\n",
    "\n",
    "minutes = to_minute(12, 1, 'AM')\n",
    "print('12:01AM = ', minutes, 'minutes after midnight')\n",
    "\n",
    "minutes = to_minute(11, 59, 'AM')\n",
    "print('11:59AM = ', minutes, 'minutes after midnight')\n",
    "\n",
    "minutes = to_minute(12, 1, 'PM')\n",
    "print('12:01PM = ', minutes, 'minutes after midnight')\n",
    "\n",
    "# uncomment one of the following lines to test if an exception is raised\n",
    "\n",
    "#minutes = to_minute(13, 1, 'PM')    # oops, bad hour\n",
    "\n",
    "#minutes = to_minute(1, -1, 'PM')    # oops, bad minute\n",
    "\n",
    "#minutes = to_minute(1, 1, 'am')    # oops, bad indicator\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise 1** Add input validation to the textbook function `harmonic` in the cell below. You can find \n",
    "the `harmonic` function near the beginning of Chapter 2.1."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def harmonic(n):\n",
    "    total = 0.0\n",
    "    for i in range(1, n + 1):\n",
    "        total += 1.0 / i\n",
    "    return total"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise 2** Add input validation to the textbook function `isPrime` in the cell below. You can find the\n",
    "`isPrime` function in Chapter 2.1 under the section *Multiple return statements*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def isPrime(n):\n",
    "    if n < 2: \n",
    "        return False\n",
    "    i = 2\n",
    "    while i*i <= n:\n",
    "        if n % i == 0: return False\n",
    "        i += 1\n",
    "    return True"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise 3** Add input validation to the textbook function `exchange` in the cell below. You can find the\n",
    "`exchange` function in Chapter 2.1 under the section *Side effects with arrays*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def exchange(a, i, j):\n",
    "   temp = a[i]\n",
    "   a[i] = a[j]\n",
    "   a[j] = temp"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise 4** Does the textbook function `shuffle` shown in the cell below require any input validation? You can\n",
    "find the `shuffle` function in Chapter 2.1 under the section *Side effects with arrays*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def shuffle(a):\n",
    "    n = len(a)\n",
    "    for i in range(n):\n",
    "        r = random.randrange(i, n)\n",
    "        exchange(a, i, r)"
   ]
  }
 ],
 "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.8.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}