modules.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Modules and Packages\n",
    "\n",
    "Jupyter notebooks are great for some things, but they aren't so great if we want to define a large library of functions to use.\n",
    "\n",
    "You have probably noticed that we are able to import functions to use from numpy using the `import` keyword\n",
    "\n",
    "```python\n",
    "import numpy\n",
    "import numpy as np\n",
    "```\n",
    "\n",
    "You can do this with your own code by writing your own Python modules and packages."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Modules\n",
    "\n",
    "A Python module is simply a `.py` file which contains definitions we would like to use.  For instance, we can import the `mymod` module defined in [`mymod.py`](mymod.py)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import mymod\n",
    "mymod.plus1(1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default, the contents of the module will be imported into a **namespace** with the same name as the file (dropping the `.py` extension).  We can re-name the namespace using the `as` keyword"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import mymod as mm\n",
    "mm.plus1(1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also import specific functions or classes from a module using the `from` keyword"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<mymod.myclass object at 0x7fde4868e700>\n",
      "2\n"
     ]
    }
   ],
   "source": [
    "from mymod import plus1, myclass\n",
    "print(myclass(1,2))\n",
    "print(plus1(1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we want to import all functions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from mymod import *\n",
    "plus1(1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "you can see what is available in the `mymod` namespace using `dir`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['__builtins__',\n",
       " '__cached__',\n",
       " '__doc__',\n",
       " '__file__',\n",
       " '__loader__',\n",
       " '__name__',\n",
       " '__package__',\n",
       " '__spec__',\n",
       " 'myclass',\n",
       " 'plus1']"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dir(mymod)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Modules vs. Scripts\n",
    "\n",
    "What is the difference between a module and a script?  Both are plain text files with a `*.py` extension.\n",
    "\n",
    "Conceptually, a *module* contains functionality (e.g. functions, classes) that we would like to use and re-use, without needing to redefine in our interpreter every time.  Typically, we use modules with an `import` statement.  A *script* contains code that *does something*.  This might include defining classes and functions, but usually also includes some sort of task such as analyzing data in a `*.csv` file, which it wouldn't make sense to do in an `import` statement.\n",
    "\n",
    "There isn't really a clear cut line between modules and scripts - you might run a `*.py` file that was written for a module as a script, or import a `*.py` file that was written as a script. \n",
    "\n",
    "If you want to have a file that can be used as *both* a module and a script, you can put the \"scripting\" part of the file in a block that begins with \n",
    "```python\n",
    "if __name__ == '__main__':\n",
    "    # scripting code here\n",
    "```\n",
    "An example can be found in [`mymod.py`](mymod.py)\n",
    "\n",
    "`__name__` is a global variable, which is set to `__main__` when the file is executed from the command line, as in\n",
    "```\n",
    "python mymod.py\n",
    "```\n",
    "\n",
    "If the file is imported as a module, you see that `__name__` is set to be the name of the file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'mymod'"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mymod.__name__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'mymod'"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import mymod as mm\n",
    "mm.__name__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Packages\n",
    "\n",
    "Python packages are contained in a directory with an `__init__.py` file.  These directories may contain muliple `*.py` files, as well as nested directories with `__init__.py` files (sub-packages).  These directories might also contain other sorts of files such as documentation files or shared object libraries."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can use the `__init__.py` file to automate import of modules inside a package, or modify namespaces.\n",
    "\n",
    "An example can be found in the [`mypack`](mypack) directory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "import mypack"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['__builtins__',\n",
       " '__cached__',\n",
       " '__doc__',\n",
       " '__file__',\n",
       " '__loader__',\n",
       " '__name__',\n",
       " '__package__',\n",
       " '__path__',\n",
       " '__spec__',\n",
       " 'functions',\n",
       " 'hello',\n",
       " 'more',\n",
       " 'mypack']"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dir(mypack)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following function is imported from `mypack/mypack.py` in `__init__.py`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hello from mypack\n"
     ]
    }
   ],
   "source": [
    "mypack.hello()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`cube` is in `mypack/functions.py`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "27"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mypack.functions.cube(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "we can import a submodule from a package into a new namespace:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'mypack.functions'"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import mypack.functions as fun1\n",
    "fun1.__name__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`square` is also in `mypack/functions.py`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "4"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fun1.square(2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also have subpackages in packages (subdirectories of our directory).\n",
    "\n",
    "`plus2` is defined in `mypack/subpackage/functions.py`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import mypack.subpackage.functions as fun2\n",
    "fun2.plus2(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Conventions\n",
    "\n",
    "By convention, Python packages and modules should have short lowercase names.  See [here](https://www.python.org/dev/peps/pep-0008/#package-and-module-names) for reference."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python (pycourse)",
   "language": "python",
   "name": "pycourse"
  },
  "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.8.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}