09_modules.ipynb

{
 "nbformat": 4,
 "nbformat_minor": 0,
 "metadata": {
  "colab": {
   "name": "09_modules.ipynb",
   "provenance": [],
   "collapsed_sections": []
  },
  "kernelspec": {
   "name": "python3",
   "display_name": "Python 3"
  }
 },
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "QgpBiDw8M9U4",
    "colab_type": "text"
   },
   "source": [
    "# Modules & Packages\n",
    "\n",
    "Python files are modules. A folder of Python files (with one special file added: `__init__.py`) is a package. The assignment folder of this guide is a package. The init file is a python file that exists to mark a folder as a Python package. It is not required to be empty, but it generally is. Packages have the advantage of allowing the import of all the files at once, rather than each file individually.\n",
    "\n",
    "- [Python Import | python.org](https://docs.python.org/3/reference/import.html)\n",
    "- [Modules and Packages | YouTube.com](https://youtu.be/0oTh1CXRaQ0): David Beazley"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "n-jxHNstIvJ6",
    "colab_type": "text"
   },
   "source": [
    "## Import This - Prefered\n",
    "\n",
    "This is by far the best way to handle imports. Contrary to popular belief - this does not waste memory. All import styles use almost exactly the same amount of memory. All of them will excecute and import the entire namespace of the target, even when it doesn't seem like it. The names are there, in memory no matter which style you choose - but they may or may not be injected into your namespace. This choice is not about memory, it's about namespace clutter. The following example is prefered because it causes the least namespace clutter."
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "id": "LfdZ22TtIWZC",
    "colab_type": "code",
    "colab": {}
   },
   "source": [
    "import random"
   ],
   "execution_count": 0,
   "outputs": []
  },
  {
   "cell_type": "code",
   "metadata": {
    "id": "IQSymBgGIax0",
    "colab_type": "code",
    "outputId": "2ba56bbf-bb1d-426f-ec07-b61d0629a318",
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 34
    }
   },
   "source": [
    "print(random.randint(1, 6))"
   ],
   "execution_count": 3,
   "outputs": [
    {
     "output_type": "stream",
     "text": [
      "4\n"
     ],
     "name": "stdout"
    }
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "09IU_AD-Ixle",
    "colab_type": "text"
   },
   "source": [
    "## From That Import This - Acceptable\n",
    "\n",
    "This style might be the most common import style. It offers a more convienient calling signature for the names that get imported. While this example doesn't have the problems of the next example, it still has issues. For one, everything you import like this will be added to the top level of your namespace. At small scale this is not a problem, but it can become a problem if you have many imports in a large project.\n",
    "\n",
    "This style has the added benifit of listing all the names you intend to use at the top of your module. However, if later you want to use some other part of the module you have to scroll up add that to the import statement, then scroll back down to your code. Small project - no big deal, large project - major pain. Some IDEs can handle imports for you, and this can give you the best of all worlds."
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "id": "uOd4__i_M8Js",
    "colab_type": "code",
    "colab": {}
   },
   "source": [
    "from random import randint"
   ],
   "execution_count": 0,
   "outputs": []
  },
  {
   "cell_type": "code",
   "metadata": {
    "id": "yhaBPa0RILbj",
    "colab_type": "code",
    "outputId": "d45df3b7-ffc3-427a-eb58-44b0f19df308",
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 34
    }
   },
   "source": [
    "print(randint(1, 6))"
   ],
   "execution_count": 5,
   "outputs": [
    {
     "output_type": "stream",
     "text": [
      "6\n"
     ],
     "name": "stdout"
    }
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "P3Iuog6VI0zE",
    "colab_type": "text"
   },
   "source": [
    "## Star Import - Ugly\n",
    "\n",
    "The star import can get you in trouble because when you star import multiple modules you loose encapsulation of those modules. This can also pollute your namespace. In the example below all we need is the `randint()` function - but we've imported all the names in the random module to the top level of our namespace. Best case: we have a cluttered namespace. Worse case: we can no longer be sure that we're not creating name conflicts. Don't use star imports in production code. It's fine if it's the only import in a single module, and no one but you will ever read it, but it's still bad form."
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "id": "GIitrbCtIlo-",
    "colab_type": "code",
    "colab": {}
   },
   "source": [
    "from random import *"
   ],
   "execution_count": 0,
   "outputs": []
  },
  {
   "cell_type": "code",
   "metadata": {
    "id": "JjC2ht5bIpGO",
    "colab_type": "code",
    "outputId": "7a9db39d-b5be-4b5f-958f-fb5cf247630f",
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 34
    }
   },
   "source": [
    "print(randint(1, 6))"
   ],
   "execution_count": 9,
   "outputs": [
    {
     "output_type": "stream",
     "text": [
      "5\n"
     ],
     "name": "stdout"
    }
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "1oY-rafDgEdG",
    "colab_type": "text"
   },
   "source": [
    "## Intra-package, Cross-module Import\n",
    "The following code assumes you have a package named `mypkg` with the file you're working on and a sibling file named `sibling.py` and it contains some item named `example`. Lets also assume that the `example` object is a function, but it could be any object.\n",
    "```\n",
    "mypkg - Package Root Directory\n",
    "    |- __init__.py\n",
    "    |- my_file.py\n",
    "    |- sibling.py\n",
    "```\n",
    "### Absolute Import\n",
    "```python\n",
    "# my_file.py\n",
    "import mypkg.sibling\n",
    "print(mypkg.sibling.example())\n",
    "```\n",
    "or\n",
    "```python\n",
    "# my_file.py\n",
    "from mypkg import sibling\n",
    "print(sibling.example())\n",
    "```\n",
    "or\n",
    "```python\n",
    "# my_file.py\n",
    "from mypkg.sibling import example\n",
    "print(example())\n",
    "```\n",
    "### Python2 Style Import\n",
    "Any of the above styles will work for intra-package importing. However, the following examples will not work in Python3 when importing one module from another module inside the same package. In reality, these still work sometimes, but you should never count on it.\n",
    "```python\n",
    "# my_file.py\n",
    "import sibling\n",
    "```\n",
    "or\n",
    "```python\n",
    "# my_file.py\n",
    "from sibling import example\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "Ru0K0RWb4SOa",
    "colab_type": "text"
   },
   "source": [
    "## Init File: `__init__.py`\n",
    "\n",
    "Typically the `__init__.py` file is empty. However it can be used to unify multiple modules into one namespace.\n",
    "\n",
    "Lets assume we have the following directory structure:\n",
    "```\n",
    "pack - Package Root Directory\n",
    "    |- __init__.py\n",
    "    |- mod1.py\n",
    "    |- mod2.py\n",
    "```\n",
    "```python\n",
    "# __init__.py\n",
    "# blank file\n",
    "```\n",
    "```python\n",
    "# mod1.py\n",
    "def alpha():\n",
    "    return \"alpha\"\n",
    "```\n",
    "```python\n",
    "# mod2.py\n",
    "def beta():\n",
    "    return \"beta\"\n",
    "```\n",
    "In order to use `alpha` and `beta` from outside the package we would have to use something like the following:\n",
    "```python\n",
    "# Import from outside the package\n",
    "from pack.mod1 import alpha\n",
    "from pack.mod2 import beta\n",
    "...\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "OENQr6Ky7DIp",
    "colab_type": "text"
   },
   "source": [
    "However if we modify the `__init__.py` as below, we can unify the package namespace.\n",
    "\n",
    "```python\n",
    "# __init__.py\n",
    "from .mod1 import *\n",
    "from .mod2 import *\n",
    "\n",
    "__all__ = (mod1.__all__ + mod2.__all__)\n",
    "```\n",
    "Now we can use `alpha` and `beta` like so:\n",
    "```python\n",
    "# Import from outside the package\n",
    "from pack import alpha, beta\n",
    "...\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "id": "naWsCO9Mu8Sr",
    "colab_type": "code",
    "colab": {}
   },
   "source": [],
   "execution_count": 0,
   "outputs": []
  }
 ]
}