5_using_modules.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "# Using modules*\n",
    "\n",
    "* Functions allow blocks of code to be separated into reusable parts that can be called from a user's script. Modules take this idea one step further and allow the grouping of functions and code that all perform similar tasks into a library, or in Python speak, module.\n",
    "\n",
    "* A module has its definitions, the functions and code that make it up, within a separate file ending with a '.py' extension and this file is then imported into a user's current script. This is most easily demonstrated through an example. We will define a mathematics module called mymath and use this from a separate script.\n",
    "    \n",
    "* The operations are supported as long as it makes sense for that type, e.g. there is no string division but `+` just means join the two strings together.\n",
    "\n",
    "```python\n",
    "## File: mymath.py ##\n",
    "def square(n):\n",
    "    return n*n\n",
    "\n",
    "def cube(n):\n",
    "    return n*n*n\n",
    "\n",
    "def average(values):\n",
    "    nvals = len(values)\n",
    "    sum = 0.0\n",
    "    for v in values:\n",
    "        sum += v \n",
    "    return float(sum)/nvals\n",
    "```\n",
    "\n",
    "To use this module from a user script we need to tell the script about the module using the `import` statement. Once the definitions are imported we can then use the functions by calling them as `module.functionname`. This syntax is to prevent name clashes.\n",
    "\n",
    "```python\n",
    "## My script using the math module ##\n",
    "import mymath  # Note no .py\n",
    " \n",
    "values = [2,4,6,8,10]\n",
    "print('Squares:')\n",
    "for v in values:\n",
    "    print(mymath.square(v))\n",
    "print 'Cubes:'\n",
    "for v in values:\n",
    "    print(mymath.cube(v))\n",
    "\n",
    "print('Average: ' + str(mymath.average(values)))\n",
    "```\n",
    "\n",
    "* Another variant of the import statement, import module as new-name can be used to have the module referred to under a different name, which can be useful for modules with long name\n",
    "\n",
    "```python \n",
    "import mymath as mt\n",
    "\n",
    "print(mt.square(2))\n",
    "print(mt.square(3))\n",
    "```\n",
    "\n",
    "* It is possible to avoid the `module.functionname` syntax by using an alternate version of the import statement, `from module import *`. The functions can then be used as if they were defined in the current file. This is dangerous however as you do not have any protection against name conflicts when using multiple modules.\n",
    "\n",
    "* If the module lives within the same directory as the script that is using it, then it can be imported directly into your code. For system modules, these are pre-loaded into pythons sys.path list. For example the numpy module location is here \n",
    "\n",
    "```python\n",
    "import numpy\n",
    "print(numpy.__file__)\n",
    "```\n",
    "\n",
    "* PYTHONPATH environmental variable is used by python on startup to determine the locations of any additional modules. You can extend it before launching your python console for example on Linux or Windows respectively.  \n",
    "\n",
    "```bash\n",
    "export PYTHONPATH=$PYTONPATH:{Path to mymodule directory} \n",
    "SET PYTHONPATH=%PYTHONPATH%;{Path to mymodule directory}\n",
    "```\n",
    "* Another way to make modules available for import is to append their directory paths onto sys.path within your python session. \n",
    "\n",
    "```python\n",
    "import sys\n",
    "sys.path.append({Path to mymodule directory})\n",
    "import mymodule\n",
    "```\n",
    "\n",
    "*Modified from https://www.mantidproject.org/Using_Modules"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise (1)** <br>\n",
    "On your local machine create a module `mymodule.py` that contains `greeting` function (you can use any text editor for this):\n",
    "```python\n",
    "def greeting(name):\n",
    "    print(\"Hello, \" + name) \n",
    "```\n",
    "And upload the file to the jupyterhub (to python_basics directory). Now import the module and execute greeting function with your name as a argument  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# -- YOUR CODE HERE --\n",
    "# --------------------"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise (2)** <br>\n",
    "Now create a folder named `my_awesome_module` in `python_basics` directory and copy over `mymodule.py` to this folder. Now execute greeting function again (remember to change import statement)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# -- YOUR CODE HERE --\n",
    "# --------------------"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Exercise (3)** <br>\n",
    "Eventually create a folder named my_awsome_module in directory notebooks directory (one level up), copy `mymodule.py` and rename it to `myawsomemodule.py`. Then exectute greeting function from there.   "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# -- YOUR CODE HERE --\n",
    "# --------------------"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installing python packages using conda and pip\n",
    "There are different ways to install external python packages but the most popular way to do this is to use `conda` or `pip`. These two utility tools enable installation from repositories  anaconda cloud (https://anaconda.org/) and pypi (https://pypi.org/) respectively. In order to use `conda` one needs to install `anaconda` locally (https://www.anaconda.com/distribution/#download-section), whereas `pip` can be installed following the instructions (https://pip.pypa.io/en/stable/installing/). Once installation is complete, one can use `conda` and `pip` directly from the terminal. For example to install `numpy` mathematical library it is enough to execute one of these commands:\n",
    "```bash\n",
    "conda install numpy \n",
    "pip install numpy \n",
    "\n",
    "```\n",
    "If you run your notebook with the same python `kernel` as you installed packages too, packages will be directly avaialable for notebook session (though `kernel` may need to be restarted). One can also install packages from jupyter notebook directly, however this may sometimes lead to unexpected behaviour if we want to use the same package outside of jupyter notebook (from terminal for example). To be on the safe side, the recommended way to use `conda` is to run from notebook:\n",
    "```python\n",
    "import sys\n",
    "!conda install --yes --prefix {sys.prefix} numpy\n",
    "```\n",
    "and `pip`: \n",
    "```python\n",
    "import sys\n",
    "!{sys.executable} -m pip install numpy\n",
    "```\n",
    "\n",
    "`conda` and `pip` tools provides broader functionality than just installation of new package they can also for example update or remove package. Please use `pip --help` or `conda --help` in terminal to learn more about available options "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.7.3"
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}