5. Modules and packages.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Modules and packages"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "### Can be used to break down large programs into smaller pieces and/or organizing code based on, for instance, specific functionality."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Module"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "- <h3>Collection of definitions (functions, variables, etcetera)</h3>\n",
    "- <h3>Stored as .py file</h3>\n",
    "- <h3>Can be imported by/into other modules or scripts</h3>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Example: built-in module \"math\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "import math"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<module 'math' (built-in)>"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "math"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on built-in module math:\n",
      "\n",
      "NAME\n",
      "    math\n",
      "\n",
      "DESCRIPTION\n",
      "    This module is always available.  It provides access to the\n",
      "    mathematical functions defined by the C standard.\n",
      "\n",
      "FUNCTIONS\n",
      "    acos(...)\n",
      "        acos(x)\n",
      "        \n",
      "        Return the arc cosine (measured in radians) of x.\n",
      "    \n",
      "    acosh(...)\n",
      "        acosh(x)\n",
      "        \n",
      "        Return the hyperbolic arc cosine (measured in radians) of x.\n",
      "    \n",
      "    asin(...)\n",
      "        asin(x)\n",
      "        \n",
      "        Return the arc sine (measured in radians) of x.\n",
      "    \n",
      "    asinh(...)\n",
      "        asinh(x)\n",
      "        \n",
      "        Return the hyperbolic arc sine (measured in radians) of x.\n",
      "    \n",
      "    atan(...)\n",
      "        atan(x)\n",
      "        \n",
      "        Return the arc tangent (measured in radians) of x.\n",
      "    \n",
      "    atan2(...)\n",
      "        atan2(y, x)\n",
      "        \n",
      "        Return the arc tangent (measured in radians) of y/x.\n",
      "        Unlike atan(y/x), the signs of both x and y are considered.\n",
      "    \n",
      "    atanh(...)\n",
      "        atanh(x)\n",
      "        \n",
      "        Return the hyperbolic arc tangent (measured in radians) of x.\n",
      "    \n",
      "    ceil(...)\n",
      "        ceil(x)\n",
      "        \n",
      "        Return the ceiling of x as an int.\n",
      "        This is the smallest integral value >= x.\n",
      "    \n",
      "    copysign(...)\n",
      "        copysign(x, y)\n",
      "        \n",
      "        Return x with the sign of y.\n",
      "    \n",
      "    cos(...)\n",
      "        cos(x)\n",
      "        \n",
      "        Return the cosine of x (measured in radians).\n",
      "    \n",
      "    cosh(...)\n",
      "        cosh(x)\n",
      "        \n",
      "        Return the hyperbolic cosine of x.\n",
      "    \n",
      "    degrees(...)\n",
      "        degrees(x)\n",
      "        \n",
      "        Convert angle x from radians to degrees.\n",
      "    \n",
      "    erf(...)\n",
      "        erf(x)\n",
      "        \n",
      "        Error function at x.\n",
      "    \n",
      "    erfc(...)\n",
      "        erfc(x)\n",
      "        \n",
      "        Complementary error function at x.\n",
      "    \n",
      "    exp(...)\n",
      "        exp(x)\n",
      "        \n",
      "        Return e raised to the power of x.\n",
      "    \n",
      "    expm1(...)\n",
      "        expm1(x)\n",
      "        \n",
      "        Return exp(x)-1.\n",
      "        This function avoids the loss of precision involved in the direct evaluation of exp(x)-1 for small x.\n",
      "    \n",
      "    fabs(...)\n",
      "        fabs(x)\n",
      "        \n",
      "        Return the absolute value of the float x.\n",
      "    \n",
      "    factorial(...)\n",
      "        factorial(x) -> Integral\n",
      "        \n",
      "        Find x!. Raise a ValueError if x is negative or non-integral.\n",
      "    \n",
      "    floor(...)\n",
      "        floor(x)\n",
      "        \n",
      "        Return the floor of x as an int.\n",
      "        This is the largest integral value <= x.\n",
      "    \n",
      "    fmod(...)\n",
      "        fmod(x, y)\n",
      "        \n",
      "        Return fmod(x, y), according to platform C.  x % y may differ.\n",
      "    \n",
      "    frexp(...)\n",
      "        frexp(x)\n",
      "        \n",
      "        Return the mantissa and exponent of x, as pair (m, e).\n",
      "        m is a float and e is an int, such that x = m * 2.**e.\n",
      "        If x is 0, m and e are both 0.  Else 0.5 <= abs(m) < 1.0.\n",
      "    \n",
      "    fsum(...)\n",
      "        fsum(iterable)\n",
      "        \n",
      "        Return an accurate floating point sum of values in the iterable.\n",
      "        Assumes IEEE-754 floating point arithmetic.\n",
      "    \n",
      "    gamma(...)\n",
      "        gamma(x)\n",
      "        \n",
      "        Gamma function at x.\n",
      "    \n",
      "    hypot(...)\n",
      "        hypot(x, y)\n",
      "        \n",
      "        Return the Euclidean distance, sqrt(x*x + y*y).\n",
      "    \n",
      "    isfinite(...)\n",
      "        isfinite(x) -> bool\n",
      "        \n",
      "        Return True if x is neither an infinity nor a NaN, and False otherwise.\n",
      "    \n",
      "    isinf(...)\n",
      "        isinf(x) -> bool\n",
      "        \n",
      "        Return True if x is a positive or negative infinity, and False otherwise.\n",
      "    \n",
      "    isnan(...)\n",
      "        isnan(x) -> bool\n",
      "        \n",
      "        Return True if x is a NaN (not a number), and False otherwise.\n",
      "    \n",
      "    ldexp(...)\n",
      "        ldexp(x, i)\n",
      "        \n",
      "        Return x * (2**i).\n",
      "    \n",
      "    lgamma(...)\n",
      "        lgamma(x)\n",
      "        \n",
      "        Natural logarithm of absolute value of Gamma function at x.\n",
      "    \n",
      "    log(...)\n",
      "        log(x[, base])\n",
      "        \n",
      "        Return the logarithm of x to the given base.\n",
      "        If the base not specified, returns the natural logarithm (base e) of x.\n",
      "    \n",
      "    log10(...)\n",
      "        log10(x)\n",
      "        \n",
      "        Return the base 10 logarithm of x.\n",
      "    \n",
      "    log1p(...)\n",
      "        log1p(x)\n",
      "        \n",
      "        Return the natural logarithm of 1+x (base e).\n",
      "        The result is computed in a way which is accurate for x near zero.\n",
      "    \n",
      "    modf(...)\n",
      "        modf(x)\n",
      "        \n",
      "        Return the fractional and integer parts of x.  Both results carry the sign\n",
      "        of x and are floats.\n",
      "    \n",
      "    pow(...)\n",
      "        pow(x, y)\n",
      "        \n",
      "        Return x**y (x to the power of y).\n",
      "    \n",
      "    radians(...)\n",
      "        radians(x)\n",
      "        \n",
      "        Convert angle x from degrees to radians.\n",
      "    \n",
      "    sin(...)\n",
      "        sin(x)\n",
      "        \n",
      "        Return the sine of x (measured in radians).\n",
      "    \n",
      "    sinh(...)\n",
      "        sinh(x)\n",
      "        \n",
      "        Return the hyperbolic sine of x.\n",
      "    \n",
      "    sqrt(...)\n",
      "        sqrt(x)\n",
      "        \n",
      "        Return the square root of x.\n",
      "    \n",
      "    tan(...)\n",
      "        tan(x)\n",
      "        \n",
      "        Return the tangent of x (measured in radians).\n",
      "    \n",
      "    tanh(...)\n",
      "        tanh(x)\n",
      "        \n",
      "        Return the hyperbolic tangent of x.\n",
      "    \n",
      "    trunc(...)\n",
      "        trunc(x:Real) -> Integral\n",
      "        \n",
      "        Truncates x to the nearest Integral toward 0. Uses the __trunc__ magic method.\n",
      "\n",
      "DATA\n",
      "    e = 2.718281828459045\n",
      "    pi = 3.141592653589793\n",
      "\n",
      "FILE\n",
      "    (built-in)\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(math)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1.0"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "math.cos(0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "import math as m"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.0"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.sin(0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "from math import acos, asin"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.0"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "asin(0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "from math import *"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "-1.0"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cos(pi)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Write your own module"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "# Save this as mymodule.py\n",
    "myvariable = \"world\"\n",
    "\n",
    "def hello(name):\n",
    "    print(\"Hello \" + name + \"!\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "from mymodule import myvariable"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "world\n"
     ]
    }
   ],
   "source": [
    "print(myvariable)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "import mymodule as mm"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'world'"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mm.myvariable"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello Bob!\n"
     ]
    }
   ],
   "source": [
    "mm.hello(\"Bob\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Running a module as a script"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "### Since a module is a regular .py file, just like any Python script, you could try to run it. This will basically run the code in the file, just like when you import the module. However, a special variable __name__ will be set to the value \"__main__\" in this case. This can be used to determine if the code is either being imported as a module or being run as a script."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "# Modified version of mymodule.py\n",
    "\n",
    "myvariable = \"world\"\n",
    "\n",
    "def hello(name):\n",
    "    print(\"Hello \" + name + \"!\")\n",
    "    \n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    # The file is run as a script: call the hello function.\n",
    "    hello(myvariable)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "```\n",
    "$ python mymodule.py\n",
    "Hello world!\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Packages"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "- <h3>Collection of organized modules</h3>\n",
    "- <h3>Can be used to get even more structure, e.g. for large projects</h3>\n",
    "- <h3>Organized by putting modules (.py files) into (sub)directories, the name of the (sub)directory will be the name of the (sub)package</h3>\n",
    "- <h3>Modules can now be referenced like package.subpackage.module</h3>\n",
    "- <h3>Each (sub)directory containing modules should have a __init__.py file, in order to make Python treat the directory as a package</h3>\n",
    "    - <h4>The __init__.py should contain initialization code that is run when the package is imported<h4>\n",
    "    - <h4>Often, the file can be empty</h4>\n",
    "    - <h4>The \\_\\_all\\_\\_ variable can be used to specify which modules should be loaded when one uses import package.*</h4>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Example of a project:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "```\n",
    "mypackage/                         # Top-level package\n",
    "      __init__.py                  # Initialization code for mypackage\n",
    "      mysubpackage1/               # First subpackage\n",
    "                    __init__.py\n",
    "                    module1.py\n",
    "                    module2.py\n",
    "      mysubpackage2/               # Another subpackage\n",
    "                    __init__.py\n",
    "                    module1.py\n",
    "                    module2.py\n",
    "\n",
    "\n",
    "All modules only contain a function info(), that will print the name of the module, e.g.:\n",
    "\n",
    "def info():\n",
    "    print(\"This is mypackage.mysubpackage2.module1!\")\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This is module1 from mypackage.mysubpackage1!\n"
     ]
    }
   ],
   "source": [
    "import mypackage.mysubpackage1.module1\n",
    "mypackage.mysubpackage1.module1.info()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This is module1 from mypackage.mysubpackage1!\n"
     ]
    }
   ],
   "source": [
    "import mypackage.mysubpackage1.module1 as m1\n",
    "m1.info()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This is module1 from mypackage.mysubpackage1!\n"
     ]
    }
   ],
   "source": [
    "from mypackage.mysubpackage1 import module1\n",
    "module1.info()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This is module1 from mypackage.mysubpackage1!\n"
     ]
    }
   ],
   "source": [
    "from mypackage.mysubpackage1.module1 import info\n",
    "info()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "ename": "NameError",
     "evalue": "name 'module2' is not defined",
     "output_type": "error",
     "traceback": [
      "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m\n\u001b[1;31mNameError\u001b[0m                                 Traceback (most recent call last)",
      "\u001b[1;32m<ipython-input-5-8eec77832d3c>\u001b[0m in \u001b[0;36m<module>\u001b[1;34m()\u001b[0m\n\u001b[0;32m      1\u001b[0m \u001b[1;32mfrom\u001b[0m \u001b[0mmypackage\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mmysubpackage1\u001b[0m \u001b[1;32mimport\u001b[0m \u001b[1;33m*\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m      2\u001b[0m \u001b[1;31m# This will not do anything. Python does not know what * (\"all modules\") means in this case.\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m----> 3\u001b[1;33m \u001b[0mmodule2\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0minfo\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[1;31mNameError\u001b[0m: name 'module2' is not defined"
     ]
    }
   ],
   "source": [
    "from mypackage.mysubpackage1 import *\n",
    "# This will not do anything. Python does not know what * (\"all modules\") means in this case.\n",
    "module2.info()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "<h3>We can specify what \"all\" means by changing the contents of the __init__.py file of the subpackage to:</h3>\n",
    "    \n",
    "<pre>\n",
    "__all__ = ['module3', 'module4']\n",
    "</pre>\n",
    "\n",
    "<h3>Let's try this for subpackage2:</h3>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This is module3 from mypackage.mysubpackage2!\n",
      "This is module4 from mypackage.mysubpackage2!\n"
     ]
    }
   ],
   "source": [
    "from mypackage.mysubpackage2 import *\n",
    "module3.info()\n",
    "module4.info()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This is module3 from mypackage.mysubpackage2!\n",
      "This is module4 from mypackage.mysubpackage2!\n"
     ]
    }
   ],
   "source": [
    "import mypackage.mysubpackage2\n",
    "mypackage.mysubpackage2.module3.info()\n",
    "mypackage.mysubpackage2.module4.info()"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "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.4.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}