13_python_modules.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Modules\n",
    "from http://nbviewer.jupyter.org/github/jrjohansson/scientific-python-lectures/blob/master/Lecture-1-Introduction-to-Python-Programming.ipynb\n",
    "\n",
    "One of the most important concepts in good programming is to reuse code and avoid repetitions.\n",
    "\n",
    "The idea is to write functions and classes with well-defined purpose and scope, and reuse these instead of repeating similar code in different part of the program (modular programming). Following this principle will result in greatly improved ability to read and maintain your code for you and other people. What this means in practice is that your programs will have fewer bugs, are easier to extend and debug/troubleshoot.\n",
    "\n",
    "Python supports modular programming at different levels. Functions and classes are examples of tools for low-level modular programming. Python modules are a higher-level modular programming construct, where we can collect related variables, functions and classes in a module. A python module is defined in a python file (with file-ending .py), and it can be made accessible to other Python modules and programs using the import statement.\n",
    "\n",
    "*(Modules can be further united in packages (==libraries), which is outside the scope of this course)*  \n",
    "\n",
    "Consider the following example: the file mymodule.py contains simple example implementations of a variable, function and a class. An IPython magic command `%%file` allows you to create the module file `mymodule.py` right from the notebook:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting mymodule.py\n"
     ]
    }
   ],
   "source": [
    "%%file mymodule_test.py\n",
    "\"\"\"\n",
    "Example of a python module. Contains a variable called my_variable,\n",
    "a function called my_function, and a class called MyClass.\n",
    "\"\"\"\n",
    "\n",
    "my_variable = 0\n",
    "\n",
    "def my_function():\n",
    "    \"\"\"\n",
    "    Example function\n",
    "    \"\"\"\n",
    "    return my_variable\n",
    "    \n",
    "class MyClass():\n",
    "    \"\"\"\n",
    "    Example class.\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self):\n",
    "        self.variable = my_variable\n",
    "        \n",
    "    def set_variable(self, new_value):\n",
    "        \"\"\"\n",
    "        Set self.variable to a new value\n",
    "        \"\"\"\n",
    "        self.variable = new_value\n",
    "        \n",
    "    def get_variable(self):\n",
    "        return self.variable"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can import the module mymodule into our Python program using import:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import mymodule_test"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use `help(module)` to get a summary of what the module provides:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on module mymodule:\n",
      "\n",
      "NAME\n",
      "    mymodule\n",
      "\n",
      "DESCRIPTION\n",
      "    Example of a python module. Contains a variable called my_variable,\n",
      "    a function called my_function, and a class called MyClass.\n",
      "\n",
      "CLASSES\n",
      "    builtins.object\n",
      "        MyClass\n",
      "    \n",
      "    class MyClass(builtins.object)\n",
      "     |  Example class.\n",
      "     |  \n",
      "     |  Methods defined here:\n",
      "     |  \n",
      "     |  __init__(self)\n",
      "     |      Initialize self.  See help(type(self)) for accurate signature.\n",
      "     |  \n",
      "     |  get_variable(self)\n",
      "     |  \n",
      "     |  set_variable(self, new_value)\n",
      "     |      Set self.variable to a new value\n",
      "     |  \n",
      "     |  ----------------------------------------------------------------------\n",
      "     |  Data descriptors defined here:\n",
      "     |  \n",
      "     |  __dict__\n",
      "     |      dictionary for instance variables (if defined)\n",
      "     |  \n",
      "     |  __weakref__\n",
      "     |      list of weak references to the object (if defined)\n",
      "\n",
      "FUNCTIONS\n",
      "    my_function()\n",
      "        Example function\n",
      "\n",
      "DATA\n",
      "    my_variable = 0\n",
      "\n",
      "FILE\n",
      "    /media/sergey/DATA/Projects/advanced-python-training/mymodule.py\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(mymodule_test)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mymodule_test.my_variable"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mymodule_test.my_function() "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "10"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "my_class = mymodule_test.MyClass() \n",
    "my_class.set_variable(10)\n",
    "my_class.get_variable()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Why you need to create your own modules instead of just defining your functions inside the script? There are several reasons:\n",
    "\n",
    "1. Complexity management reason. Because programming applications grow very complicated, we need to manage the complexity by using levels of abstraction. In a sense, it is like saying \"I've done the code for this level, and I will build on top of it, not thinking about how that works on the lower level\". Creating modules is another level of abstraction. Practically it means separating out related functions and constants, only importing some of them when it is needed.\n",
    "\n",
    "2. Isolation reason. This is especially crucial for Python. As we have seen before, Python does not have proper function isolation: if you define a variable outside the function, you can use it inside the function even if it wasn't submitted as an argument to this function (but, thankfully, not vice versa). This makes it much easier to write code in Python, but may lead to bugs and confusions. It is fine during the prototyping stage, it is better to avoid at the production stage. An important exception to the absence of isolation is that modules are fully isolated from each other and the main namespace. In other words, an imported function will not have access to the varialbes defined in the current script. So -- inside the module:  no isolation, between modules: full isolation.\n",
    "\n",
    "Try this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "42\n"
     ]
    }
   ],
   "source": [
    "LOCAL_VAR_NOTEBOOK = 42\n",
    "\n",
    "def test_notebook():\n",
    "    print(LOCAL_VAR_NOTEBOOK)\n",
    "\n",
    "test_notebook()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Writing module_test.py\n"
     ]
    }
   ],
   "source": [
    "%%file mymodule_test.py\n",
    "\n",
    "LOCAL_VAR_MODULE = 1101\n",
    "\n",
    "def test_module_loc():\n",
    "    print(LOCAL_VAR_MODULE)\n",
    "    \n",
    "def test_module_nb():\n",
    "    print(LOCAL_VAR_NOTEBOOK)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1101\n"
     ]
    }
   ],
   "source": [
    "from mymodule_test import test_module_loc, test_module_nb\n",
    "\n",
    "test_module_loc()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "ename": "NameError",
     "evalue": "name 'LOCAL_VAR_NOTEBOOK' is not defined",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mNameError\u001b[0m                                 Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-8-9f9388788e0d>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mtest_module_nb\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;32m/media/sergey/DATA/Projects/advanced-python-training/module_test.py\u001b[0m in \u001b[0;36mtest_module_nb\u001b[0;34m()\u001b[0m\n\u001b[1;32m      6\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      7\u001b[0m \u001b[0;32mdef\u001b[0m \u001b[0mtest_module_nb\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 8\u001b[0;31m     \u001b[0mprint\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mLOCAL_VAR_NOTEBOOK\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mNameError\u001b[0m: name 'LOCAL_VAR_NOTEBOOK' is not defined"
     ]
    }
   ],
   "source": [
    "test_module_nb()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.5",
   "language": "python",
   "name": "py35"
  },
  "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.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}