lecture_10_modules.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div style=\"text-align: center\">\n",
    "    <div style=\"font-size: xxx-large ; font-weight: 900 ; color: rgba(0 , 0 , 0 , 0.8) ; line-height: 100%\">\n",
    "        Modules\n",
    "    </div>\n",
    "    <div style=\"font-size: x-large ; padding-top: 20px ; color: rgba(0 , 0 , 0 , 0.5)\">\n",
    "        import + Why\n",
    "    </div>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Notebook vs. Python File\n",
    "\n",
    "Until now you have learned how to create small programs within this `jupyter lab` instance. `jupyter` is really nice when you want to write short scripts in combination with visualizations. In practice though, you will often write your code in one or multiple files ending on `.py` for Python. You can execute these files from a terminal with `python filename.py`.\n",
    "\n",
    "## Why would I do this?\n",
    "The reason again is, so that you can\n",
    "- **reuse your code (functions, classes, variables, ...) in different files or entirely new projects**,\n",
    "    - over time you will probably write a lot of code, e.g. for visualizing data, that you can then simply reuse by importing its functionality into your new project\n",
    "- **split your code into separate and logical parts** which improves maintainability in larger projects.\n",
    "\n",
    "## What is a module?\n",
    "A module simply is a Python file, e.g. `seismometer.py`, which includes (functions, classes, variables, ...).\n",
    "\n",
    "A module can be imported by writing `import seismometer` (the Python filename without the suffix `.py`) at the top of another Python file, or even a notebook like this, which wants to reuse the code in `seismometer.py`.\n",
    "\n",
    "The statement `import seismometer` will basically \"copy\" the code in the file `seismometer.py` and \"paste\" it into the file that calls `import seismometer` at the position of the `import`.\n",
    "\n",
    "Note: This means that any code that you have within `seismometer.py` that would be executed by running `seismometer.py` itself (by executing `python seismometer.py`) will also be executed (e.g. if `seismometer.py` contains just `print('Hello')` and you do `import seismometer` it will print \"Hello\").\n",
    "\n",
    "If a file you want to import, i.e. `hello.py`, is located in a subdirectory relative to the directory your current python file/program is in, i.e. in `lecture_10/hello.py`, then you have to point to that directory with dots as directory delimiters. Here: `import lecture_10.hello`\n",
    "\n",
    "File: [lecture_10/hello.py](lecture_10/hello.py)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello\n"
     ]
    }
   ],
   "source": [
    "import lecture_10.hello"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How does `import` work?\n",
    "You already learned that import will \"copy\" the code of another file into your current one. This \"copy\" actually takes all the code in `seismometer.py` and places it in a \"variable\" called `seismometer`. \n",
    "\n",
    "Imagine you have a class called `class Seismometer():` in `seismometer.py`. When you import `seismometer.py` you cannot simply create a new object with `Seismometer()` but instead you have to do `seismometer.Seismometer()` because everything located in `seismometer.py` now is an attribute of `seismometer`.\n",
    "```python\n",
    "# This does not work!\n",
    "import seismometer\n",
    "Seismometer()\n",
    "```\n",
    "\n",
    "```python\n",
    "# This does work!\n",
    "import seismometer\n",
    "seismometer.Seismometer()\n",
    "```\n",
    "\n",
    "**Problem 1.1:** What would happen if you do `import seismometer` but you already have a variable called seismometer in the file that does the import?\n",
    "- It would override the variable `seismometer` with the module `seismometer`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<module 'math' (built-in)>\n"
     ]
    }
   ],
   "source": [
    "import math\n",
    "print(math)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1\n",
      "<module 'math' (built-in)>\n"
     ]
    }
   ],
   "source": [
    "# An example with the inbuilt python module 'math'\n",
    "math = 1\n",
    "print(math)\n",
    "import math # Overrides the variable math\n",
    "print(math)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Problem 1.2:** What would happen if it is the other way around?\n",
    "- It would override the module `seismometer` with the variable `seismometer`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Solution to 1.1 & 1.2**:\n",
    "\n",
    "- You can use `import seismometer as new_name` to import a module and give it a new name.\n",
    "- You can also do this to shorten really long imports so that you do not have to type so much :)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1\n",
      "1\n",
      "<module 'math' (built-in)>\n"
     ]
    }
   ],
   "source": [
    "# An example with the inbuilt python module 'math'\n",
    "math = 1\n",
    "print(math)\n",
    "import math as math_module # Imports the module 'math' and renames it to 'math_module'\n",
    "print(math)\n",
    "print(math_module)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Problem 3:** What if you don't want to import everything and are only interested in a single class, variable, function in a module?\n",
    "- You can import only parts of a module with `from module import class/variable/function`\n",
    "- You can now directly use that class/variable/function\n",
    "- You can also rename it with `as`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3.141592653589793\n"
     ]
    }
   ],
   "source": [
    "# An example with the inbuilt python module 'math'\n",
    "from math import pi\n",
    "print(pi)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3\n",
      "4\n"
     ]
    }
   ],
   "source": [
    "# You can also import multiple parts\n",
    "from math import floor, ceil\n",
    "print(floor(pi))\n",
    "print(ceil(pi))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3\n",
      "4\n"
     ]
    }
   ],
   "source": [
    "# If the line gets too long you can use parenthesis\n",
    "from math import (\n",
    "    floor,\n",
    "    ceil\n",
    ")\n",
    "print(floor(pi))\n",
    "print(ceil(pi))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "-1.0\n"
     ]
    }
   ],
   "source": [
    "# It also supports renames with 'as'\n",
    "from math import cos as cosinus\n",
    "print(cosinus(pi))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Problem 4:** How do you import modules in subdirectories?\n",
    "\n",
    "When projects grow larger you might end up with tens or hundreds of `.py` files in a directory. This makes navigating files difficult. Therefore you will often group several modules in directories (called packages).\n",
    "\n",
    "- The `from` keyword can also be used to traverse directories\n",
    "    - You can traverse directories with `from directory.subdirectory.subsubdirectory import module`\n",
    "- Alternatively `import directory.subdirectory.subsub.module`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<module 'lecture_10.seismometer' from 'C:\\\\Development\\\\github\\\\geopy-teaching\\\\lecture_10\\\\seismometer.py'>\n",
      "<class 'lecture_10.seismometer.Seismometer'>\n"
     ]
    }
   ],
   "source": [
    "# Let's use a module located in \"lecture_10/seismometer.py\"\n",
    "\n",
    "# Import with from\n",
    "from lecture_10 import seismometer\n",
    "print(seismometer)\n",
    "print(seismometer.Seismometer)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<module 'lecture_10.seismometer' from 'C:\\\\Development\\\\github\\\\geopy-teaching\\\\lecture_10\\\\seismometer.py'>\n",
      "<class 'lecture_10.seismometer.Seismometer'>\n"
     ]
    }
   ],
   "source": [
    "# If you use import you have to specify the full import \n",
    "import lecture_10.seismometer\n",
    "print(lecture_10.seismometer)\n",
    "print(lecture_10.seismometer.Seismometer)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<module 'lecture_10.seismometer' from 'C:\\\\Development\\\\github\\\\geopy-teaching\\\\lecture_10\\\\seismometer.py'>\n",
      "<class 'lecture_10.seismometer.Seismometer'>\n"
     ]
    }
   ],
   "source": [
    "# You can also shorten it\n",
    "import lecture_10.seismometer as l10_seismometer\n",
    "print(l10_seismometer)\n",
    "print(l10_seismometer.Seismometer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Bonus:** You can also do relative imports, but use it with care, it can get tricky to use. For example:\n",
    "```\n",
    "You are here\n",
    "/\n",
    "|\n",
    "|-- package_A\n",
    "    |\n",
    "    |-- module1.py\n",
    "|\n",
    "|-- package_B\n",
    "    |\n",
    "    |-- module2.py\n",
    "        from ..package_A import module1 (with .. you go up one directory)\n",
    "```\n",
    "\n",
    "## Example\n",
    "\n",
    "Coming back to our seismometer example we could have the following files (`/` is the directory where all `.ipynb` files are located, i.e. the root):\n",
    "```\n",
    "You are here\n",
    "/\n",
    "|\n",
    "|-- seismometer_array_hekla.py (This includes logic to setup and administrate an array of seismometer objects on Hekla)\n",
    "|\n",
    "|-- seismometer_array_katla.py (This includes logic to setup and administrate an array of seismometer objects on Katla)\n",
    "|\n",
    "|-- lecture_12 (This is called a package (directory))\n",
    "    |\n",
    "    |-- seismometer.py (This includes our previous \"Seismometer class\")\n",
    "```\n",
    "\n",
    "Because we are within a `jupyter` notebook we will not actually create `seismometer_array_hekla.py` and `seismometer_array_katla.py`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Created Seismometer with min_signal=0.1, max_signal=0.8, calibration_factor=0.0006, storage_size=1024, owner=I_Rule_Volcanoes\n",
      "Created Seismometer with min_signal=0.01, max_signal=0.9, calibration_factor=0.0001, storage_size=8192, owner=I_Rule_Volcanoes\n",
      "Created Seismometer with min_signal=0.2, max_signal=0.6, calibration_factor=0.06, storage_size=1024, owner=I_Rule_Volcanoes\n",
      "0/1024 available.\n",
      "Calibrating ...\n",
      "0/8192 available.\n",
      "Calibrating ...\n",
      "0/1024 available.\n",
      "Calibrating ...\n",
      "Downloading data\n",
      "[1.700602, 1.700602, 1.700602, 1.700602, 1.700602, 1.700602, 1.700602, 1.700602, 1.700602, 1.700602]\n",
      "Downloading data\n",
      "[1.8901020000000002, 1.8901020000000002, 1.8901020000000002, 1.8901020000000002, 1.8901020000000002, 1.8901020000000002, 1.8901020000000002, 1.8901020000000002, 1.8901020000000002, 1.8901020000000002]\n",
      "Downloading data\n",
      "[1.460002, 1.460002, 1.460002, 1.460002, 1.460002, 1.460002, 1.460002, 1.460002, 1.460002, 1.460002]\n"
     ]
    }
   ],
   "source": [
    "# Imagine this is in the file: seismometer_array_hekla.py\n",
    "from lecture_10.seismometer import Seismometer\n",
    "\n",
    "seismometer_array = [\n",
    "    Seismometer(min_signal=0.1, max_signal=0.8, calibration_factor=0.0006, storage_size=1024),\n",
    "    Seismometer(min_signal=0.01, max_signal=0.9, calibration_factor=0.0001, storage_size=8192),\n",
    "    Seismometer(min_signal=0.2, max_signal=0.6, calibration_factor=0.06, storage_size=1024)\n",
    "]\n",
    "\n",
    "for seismometer in seismometer_array:\n",
    "    seismometer.check_storage()\n",
    "    seismometer.calibrate()\n",
    "    \n",
    "for i in range(10):\n",
    "    for seismometer in seismometer_array:\n",
    "        seismometer.start_recording()\n",
    "\n",
    "for seismometer in seismometer_array:\n",
    "    seismometer.stop_recording()\n",
    "    print(seismometer.download())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Created Seismometer with min_signal=0.1, max_signal=0.8, calibration_factor=0.0006, storage_size=1024, owner=I_Rule_Volcanoes\n",
      "Created Seismometer with min_signal=0.01, max_signal=0.9, calibration_factor=0.0001, storage_size=8192, owner=I_Rule_Volcanoes\n",
      "Created Seismometer with min_signal=0.2, max_signal=0.6, calibration_factor=0.055, storage_size=1024, owner=I_Rule_Volcanoes\n",
      "Created Seismometer with min_signal=0.02, max_signal=0.6, calibration_factor=0.009, storage_size=1024, owner=I_Rule_Volcanoes\n",
      "Created Seismometer with min_signal=0.5, max_signal=0.8, calibration_factor=0.06, storage_size=1024, owner=I_Rule_Volcanoes\n",
      "Created Seismometer with min_signal=0.004, max_signal=0.01, calibration_factor=0.0001, storage_size=10024, owner=I_Rule_Volcanoes\n",
      "0/1024 available.\n",
      "Calibrating ...\n",
      "0/8192 available.\n",
      "Calibrating ...\n",
      "0/1024 available.\n",
      "Calibrating ...\n",
      "0/1024 available.\n",
      "Calibrating ...\n",
      "0/1024 available.\n",
      "Calibrating ...\n",
      "0/10024 available.\n",
      "Calibrating ...\n",
      "Downloading data\n",
      "[1.700602, 1.700602, 1.700602, 1.700602, 1.700602, 1.700602, 1.700602, 1.700602, 1.700602, 1.700602]\n",
      "Downloading data\n",
      "[1.8901020000000002, 1.8901020000000002, 1.8901020000000002, 1.8901020000000002, 1.8901020000000002, 1.8901020000000002, 1.8901020000000002, 1.8901020000000002, 1.8901020000000002, 1.8901020000000002]\n",
      "Downloading data\n",
      "[1.455002, 1.455002, 1.455002, 1.455002, 1.455002, 1.455002, 1.455002, 1.455002, 1.455002, 1.455002]\n",
      "Downloading data\n",
      "[1.589002, 1.589002, 1.589002, 1.589002, 1.589002, 1.589002, 1.589002, 1.589002, 1.589002, 1.589002]\n",
      "Downloading data\n",
      "[1.3600020000000002, 1.3600020000000002, 1.3600020000000002, 1.3600020000000002, 1.3600020000000002, 1.3600020000000002, 1.3600020000000002, 1.3600020000000002, 1.3600020000000002, 1.3600020000000002]\n",
      "Downloading data\n",
      "[1.006102, 1.006102, 1.006102, 1.006102, 1.006102, 1.006102, 1.006102, 1.006102, 1.006102, 1.006102]\n"
     ]
    }
   ],
   "source": [
    "# Imagine this is in the file: seismometer_array_katla.py\n",
    "from lecture_10.seismometer import Seismometer\n",
    "\n",
    "seismometer_array = [\n",
    "    Seismometer(min_signal=0.1, max_signal=0.8, calibration_factor=0.0006, storage_size=1024),\n",
    "    Seismometer(min_signal=0.01, max_signal=0.9, calibration_factor=0.0001, storage_size=8192),\n",
    "    Seismometer(min_signal=0.2, max_signal=0.6, calibration_factor=0.055, storage_size=1024),\n",
    "    Seismometer(min_signal=0.02, max_signal=0.6, calibration_factor=0.009, storage_size=1024),\n",
    "    Seismometer(min_signal=0.5, max_signal=0.8, calibration_factor=0.06, storage_size=1024),\n",
    "    Seismometer(min_signal=0.004, max_signal=0.01, calibration_factor=0.0001, storage_size=10024)\n",
    "]\n",
    "\n",
    "for seismometer in seismometer_array:\n",
    "    seismometer.check_storage()\n",
    "    seismometer.calibrate()\n",
    "    \n",
    "for i in range(10):\n",
    "    for seismometer in seismometer_array:\n",
    "        seismometer.start_recording()\n",
    "\n",
    "for seismometer in seismometer_array:\n",
    "    seismometer.stop_recording()\n",
    "    print(seismometer.download())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is just a small example and could definitely be improved but it shows how modules provide a way to structure your code and allow its reuse.\n",
    "\n",
    "# Inbuilt Modules\n",
    "Python provides a lot of inbuilt modules some of which are imported automatically whereas others are not automatically imported when you run a Python file. This is done because every import takes some time and can potential override your variables. You can get a list of available inbuilt (and installed) modules with\n",
    "```python\n",
    "help('modules')\n",
    "```\n",
    "Some useful ones are:\n",
    "- random\n",
    "- math\n",
    "- os\n",
    "- pathlib\n",
    "- csv\n",
    "- argparse\n",
    "\n",
    "In the next lecture you will learn about the Python Package Index which provides some very useful external modules that you first have to install before you can use them.\n",
    "\n",
    "# Prevent running code on `import`\n",
    "To create a clear entry point into your application or to allow the execution of a module you can tell Python what part of your code should only be executed when you run that particular file with `python main_example.py` and not when you do `import main_example`:\n",
    "```python\n",
    "# File: seismometer.py\n",
    "\n",
    "# Code here will always be executed\n",
    "print('Hi')\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    # Code here will only be executed when you run `python my_application.py`. It will not be executed when you do `import my_application`.\n",
    "    print('World')\n",
    "```\n",
    "\n",
    "See [lecture_10/main_example.py](lecture_10/main_example.py) for an example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This was outside a \"if __name__ == '_main__'\" \n"
     ]
    }
   ],
   "source": [
    "import lecture_10.main_example"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This was outside a \"if __name__ == '_main__'\" \n",
      "You ran this file with \"python main_example.py\"\n"
     ]
    }
   ],
   "source": [
    "# !python runs the .py file with Python\n",
    "!python lecture_10/main_example.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Summary\n",
    "\n",
    "* You know how to run a `.py` file.\n",
    "* You know why modules are useful.\n",
    "* You know the different ways to import modules or parts of one.\n",
    "* You have a rough understanding of how to structure your code into packages and modules.\n",
    "* You familiarized yourself with some of the modules available by default."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Next lecture: [Python - PyPI](lecture_11_pypi.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "##### Authors:\n",
    "* [Julian Niedermeier](https://github.com/sleighsoft)"
   ]
  }
 ],
 "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"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}