twp_102a_working_with_modules.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Working with modules\n",
    "\n",
    "[ref]: # (modules - overview)\n",
    "\n",
    "The code in Python is organised in *modules* . To make the functionality available, the module needs to be *imported* first. This is done with `import` command.\n",
    "\n",
    "When the Python is started up, not much is imported yet. The user needs to load the modules he needs himself. \n",
    "This is comparable to starting an operating system (Windows for example) and then starting the applications that are needed.  It is possible to 'autostart' modules, but this would make launch times (and memory requirements) much higher. \n",
    "\n",
    "[ref]: # (getting data - urlretrieve)\n",
    "\n",
    "Let's dive straight into it! \n",
    "The code below will import `urlretreive` function from the built-in *urllib* library. This function is used to download data from the web. With this function we'll get a small dummy module and save it locally.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('testModule.py', <http.client.HTTPMessage at 0x7f8286fe9278>)"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from urllib.request import urlretrieve\n",
    "urlretrieve(\"https://raw.githubusercontent.com/sjev/numpy-sphinx-example/master/lib/testModule.py\",\"testModule.py\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can import it by using the `import` command.\n",
    "\n",
    "*Note:* we are using `import as` command, which allowes us to use a shorthand notation of the library name. Any name will do.  This way we only need to type `tst` instead of `testModule` in further code. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import testModule as tst  # import "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's take a look at the module documentation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on module testModule:\n",
      "\n",
      "NAME\n",
      "    testModule - Example of a simple module.\n",
      "\n",
      "FUNCTIONS\n",
      "    addFun(s)\n",
      "        makes everything fun\n",
      "        \n",
      "        Parameters\n",
      "        --------------\n",
      "        s : str\n",
      "            input string\n",
      "            \n",
      "        Returns \n",
      "        ----------\n",
      "        str : new string\n",
      "    \n",
      "    printFoo()\n",
      "        print 'foo', regardless input\n",
      "\n",
      "FILE\n",
      "    /home/jev/Development/twp_4/source/notebooks/testModule.py\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(tst)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Show a list of all names defined in the package. Names starting with '\\_\\_' are *special* variables. For example `__file__` will give you the location of the module .py file\n",
    "\n",
    "\n",
    "`dir(moduleName)` will give you a list of everything that is contained within module."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['__builtins__',\n",
       " '__cached__',\n",
       " '__doc__',\n",
       " '__file__',\n",
       " '__loader__',\n",
       " '__name__',\n",
       " '__package__',\n",
       " '__spec__',\n",
       " 'addFun',\n",
       " 'printFoo']"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dir(tst)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Often used module variables are \n",
    "\n",
    "* `__version__`  - module version\n",
    "* `__file__` - module location\n",
    "* `__doc__` - docstring\n",
    "\n",
    "for example, let's inspect the `numpy` module"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1.13.3\n",
      "/home/jev/anaconda3/lib/python3.6/site-packages/numpy/__init__.py\n"
     ]
    }
   ],
   "source": [
    "import numpy as np\n",
    "print(np.__version__)\n",
    "print(np.__file__)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's get back to the previously loaded `tst` module and run some functions. Suppose that we've forgot what `addFun` function does. In this case the `help` fuction will provide an answer ( of course if the module author has taken the time to write documentation)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function addFun in module testModule:\n",
      "\n",
      "addFun(s)\n",
      "    makes everything fun\n",
      "    \n",
      "    Parameters\n",
      "    --------------\n",
      "    s : str\n",
      "        input string\n",
      "        \n",
      "    Returns \n",
      "    ----------\n",
      "    str : new string\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(tst.addFun)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Python is fun!'"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# now run it!\n",
    "tst.addFun('Python')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Much more extensive information can be found in [Python docs](https://docs.python.org/3/tutorial/modules.html)"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "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.6.2"
  },
  "toc": {
   "nav_menu": {},
   "number_sections": false,
   "sideBar": true,
   "skip_h1_title": false,
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": "block",
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}