15 - Imports.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "e8954dc6",
   "metadata": {},
   "source": [
    "### Imports"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b399c2f4",
   "metadata": {},
   "source": [
    "In most Python projects it is unlikely that all the functionality you need is part of the plain vanilla (built-in) Python."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8d4f7535",
   "metadata": {},
   "source": [
    "Like in any other language, Python has a concept of libraries (modules) that can be imported and then used."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d35d7e2c",
   "metadata": {},
   "source": [
    "In Python, all the module files you create can be imported into other modules (in a Jupyter notebook, you essentially have a single module, called the main module) - but in larger projects you typically do not use Jupyter, and instead strcuture your application using folders, sub-folders, modules, etc."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f4b422d7",
   "metadata": {},
   "source": [
    "Python comes with a huge assortment of pre-defined modules that can easily be imported into any module."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "04982780",
   "metadata": {},
   "source": [
    "When a module is imported by Python, it essentially **executes** the code in the module, and caches that internally (so if you import the same module in multiple places in your code, it only runs the code once, and thereafter gives you back the \"pre-compiled\" module)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e105f13b",
   "metadata": {},
   "source": [
    "In this primer we're going to stick to some of the modules provided as part of CPython - the so-called **standard library**."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "058f0302",
   "metadata": {},
   "source": [
    "One thing that is really important to understand is that a module is essentially just a namespace - i.e. it is a dictionary of symbols that point to objects, often functions and classes, but possibly other object types too (such as floats, etc)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "88daa624",
   "metadata": {},
   "source": [
    "A module is very much like a class - you access the symbols in the module using dot notation - and Python then looks up the symbol from the module's namespace (which is in fact just a dictionary). \n",
    "\n",
    "And in case you're wondering, a class in Python is also essentially a dictionary, but with a few extra bells and whistles - but a dictionary nonetheless)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "92f09dd4",
   "metadata": {},
   "source": [
    "#### The `import` Statement"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a9f2adf7",
   "metadata": {},
   "source": [
    "Let's import the `math` module, documented [here](https://docs.python.org/3/library/math.html):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "049485ae",
   "metadata": {},
   "outputs": [],
   "source": [
    "import math"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9970db80",
   "metadata": {},
   "source": [
    "That's it, now we have a symbol, called `math` in **our** name space, that points to the compiled `math` module that is being cached by Python."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ad9165cb",
   "metadata": {},
   "source": [
    "Let's look at our namespace:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "5f28d78c",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'__name__': '__main__',\n",
       " '__doc__': 'Automatically created module for IPython interactive environment',\n",
       " '__package__': None,\n",
       " '__loader__': None,\n",
       " '__spec__': None,\n",
       " '__builtin__': <module 'builtins' (built-in)>,\n",
       " '__builtins__': <module 'builtins' (built-in)>,\n",
       " '_ih': ['', '### Imports', 'import math', '__globals__', 'globals()'],\n",
       " '_oh': {},\n",
       " '_dh': ['/Users/fbaptiste/dev/python-primer'],\n",
       " 'In': ['', '### Imports', 'import math', '__globals__', 'globals()'],\n",
       " 'Out': {},\n",
       " 'get_ipython': <bound method InteractiveShell.get_ipython of <ipykernel.zmqshell.ZMQInteractiveShell object at 0x7fbe1054d4f0>>,\n",
       " 'exit': <IPython.core.autocall.ZMQExitAutocall at 0x7fbdf0721220>,\n",
       " 'quit': <IPython.core.autocall.ZMQExitAutocall at 0x7fbdf0721220>,\n",
       " '_': '',\n",
       " '__': '',\n",
       " '___': '',\n",
       " '_i': '__globals__',\n",
       " '_ii': 'import math',\n",
       " '_iii': '### Imports',\n",
       " '_i1': '### Imports',\n",
       " '_i2': 'import math',\n",
       " 'math': <module 'math' from '/Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/lib-dynload/math.cpython-39-darwin.so'>,\n",
       " '_i3': '__globals__',\n",
       " '_i4': 'globals()'}"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "globals()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3e5341cd",
   "metadata": {},
   "source": [
    "As you can see we have quite a few things in our global namespace - including an entry for `math`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "f10d2d6a",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<module 'math' from '/Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/lib-dynload/math.cpython-39-darwin.so'>"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "globals()['math']"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1e393ae6",
   "metadata": {},
   "source": [
    "And yes, we used dictionary notation to recover the `math` symbol - that's because namespaces are essentially just dictionaries."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "e1dd7f1b",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "type(globals())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "049d1532",
   "metadata": {},
   "source": [
    "But of course, we can access the `math` symbol using the easier dot notation (Python essentially translates that dot notation into a dictionary lookup)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "dbb6dd50",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<module 'math' from '/Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/lib-dynload/math.cpython-39-darwin.so'>"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "math"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "affd26ab",
   "metadata": {},
   "source": [
    "And we can access anything inside this `math` module:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "26dfc44b",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3.141592653589793"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "math.pi"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "eb44b849",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1.2246467991473532e-16"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "math.sin(math.pi)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "67aadaa5",
   "metadata": {},
   "source": [
    "Note: What does **global** namespace actually mean?\n",
    "\n",
    "There is no \"global\" global namespace in Python - each module (including this main module Jupyter notebook) has it's own namespace - this root namespace for a module is called the **global** namespace - but it is specific to the module - there is no such thing as an overarching global namespace for your entire application."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9ec32476",
   "metadata": {},
   "source": [
    "#### Aliasing Imports"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1a956489",
   "metadata": {},
   "source": [
    "As you can see, when we wrote:\n",
    "\n",
    "```import math```\n",
    "\n",
    "we basically created a symbol named `math` in our global namespace"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7e250fe5",
   "metadata": {},
   "source": [
    "We could alias this symbol if we wanted to:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "97045295",
   "metadata": {},
   "outputs": [],
   "source": [
    "my_math = math"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a467cba7",
   "metadata": {},
   "source": [
    "Now we added another symbol `my_math` in our global namespace that points to the same object as `math`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "9683ba47",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "math is my_math"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ada9ca2c",
   "metadata": {},
   "source": [
    "In fact, we could even delete `math` from our global namespace:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "00059e54",
   "metadata": {},
   "outputs": [],
   "source": [
    "del math"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "b6fa2c03",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "'math' in globals()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "fb70b98e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "'my_math' in globals()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f55ddea1",
   "metadata": {},
   "source": [
    "As you can see `math` is gone, but our alias `my_math` is still there, and we can use it just as before:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "a8c4366f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(3.141592653589793, 1.2246467991473532e-16)"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "my_math.pi, my_math.sin(my_math.pi)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "35ea14f3",
   "metadata": {},
   "source": [
    "This sort of aliasing is common enough, especially with long winded module names that we don't want to be typing all the time, that Python builds this right into the import statement:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "0363c803",
   "metadata": {},
   "outputs": [],
   "source": [
    "import math as math2"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6bbe4176",
   "metadata": {},
   "source": [
    "Now `math2` is in our global namespace, and points to the same cached module as before (so imported modules are essentially singletons):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "74a2bb47",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "my_math is math2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "865752b5",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(3.141592653589793, 1.2246467991473532e-16)"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "math2.pi, math2.sin(math2.pi)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b4739427",
   "metadata": {},
   "source": [
    "#### Importing Specific Symbols"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "76963da7",
   "metadata": {},
   "source": [
    "You'll notice that the approach we took here was to just import the entire module - this means our global namespace holds on to a reference to the module itself."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d2da7acf",
   "metadata": {},
   "source": [
    "And then when we reach inside the module, we always need to specify which module to use:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "82815a61",
   "metadata": {},
   "outputs": [],
   "source": [
    "import math\n",
    "import random"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "id": "0088b8ca",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(3.141592653589793, 3)"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "math.pi, random.randint(1, 10)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bf410862",
   "metadata": {},
   "source": [
    "Sometimes, we only use a few symbols from a particular import, and there is a way to get a reference to those specific symbols directly, without holding on to a reference to the module itself."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9fabb673",
   "metadata": {},
   "source": [
    "First let's delete any references to the `math` and `random` modules:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "id": "d547e32e",
   "metadata": {},
   "outputs": [],
   "source": [
    "del math\n",
    "del random\n",
    "del math2\n",
    "del my_math"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5c85d079",
   "metadata": {},
   "source": [
    "Now, let's just import what we need from those modules:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "id": "26768714",
   "metadata": {},
   "outputs": [],
   "source": [
    "from math import pi, sin\n",
    "from random import randint"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e24081d3",
   "metadata": {},
   "source": [
    "At this point, we **do not** have a reference to either `math` or `random` in our globals:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "id": "65e7b5cc",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(False, False)"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "'math' in globals(), 'random' in globals()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "095b4984",
   "metadata": {},
   "source": [
    "But we **do** have a direct reference to the symbols we imported:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "id": "4d79de68",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(True, True, True)"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "'pi' in globals(), 'sin' in globals(), 'randint' in globals()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4df221c1",
   "metadata": {},
   "source": [
    "And now we can use them without having to prefix them with the name of the module they came from:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "id": "331a7f6a",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(1.2246467991473532e-16, 1)"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sin(pi), randint(1, 10)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d942667d",
   "metadata": {},
   "source": [
    "**Note**: A common misconception is that by importing only a few symbols from a particular module you are saving memory by only loading these symbols into memory. \n",
    "\n",
    "That is **not** the case. \n",
    "\n",
    "Remember, Python will import the entire module (using a cached instance if present), and then just add references to our global namespace. Whether we ask for a reference to the module itself (`import math`), or just a few symbols (`from math import pi, sin`), the module has to be loaded and stored in memory anyway."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9558df99",
   "metadata": {},
   "source": [
    "#### Aliasing - Redux"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "82f87859",
   "metadata": {},
   "source": [
    "Just like we could alias a module name as we imported it into our global namespace, so can we alias individual symbols we import from a particular module."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aad98521",
   "metadata": {},
   "source": [
    "We could do it the long way:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "id": "d565a4e0",
   "metadata": {},
   "outputs": [],
   "source": [
    "from math import pi\n",
    "\n",
    "PI = pi\n",
    "\n",
    "del pi"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "id": "27d1f7de",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3.141592653589793"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "PI"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b7e45c1a",
   "metadata": {},
   "source": [
    "But we can use the `alias` clause of the import for this as well:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "12908965",
   "metadata": {},
   "source": [
    "Let's first delete `PI` from our namespace:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "id": "d53c4d58",
   "metadata": {},
   "outputs": [],
   "source": [
    "del PI"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "id": "7ecf3ce4",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": 36,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "'PI' in globals()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b172a882",
   "metadata": {},
   "source": [
    "And now let's do the aliased import:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "id": "421cfdeb",
   "metadata": {},
   "outputs": [],
   "source": [
    "from math import pi as PI"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "97db5c8d",
   "metadata": {},
   "source": [
    "Now `pi` is not in our namespace:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "id": "162c84fe",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": 45,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "'pi' in globals()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "85d2faf3",
   "metadata": {},
   "source": [
    "But `PI` is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "id": "41729e54",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 46,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "'PI' in globals()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8383503d",
   "metadata": {},
   "source": [
    "There are a ton of modules (or packages which are collections of modules) provided by the standard library.\n",
    "\n",
    "See these [docs](https://docs.python.org/3/library/index.html) for more info."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a8995124",
   "metadata": {},
   "source": [
    "There are also many 3rd party Python libraries available as well, most of which are documented in **PyPI** - the Python Package Index - available [here](https://pypi.org/)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a487cd76",
   "metadata": {},
   "source": [
    "As of writing this, there are well over 300,000 such libraries."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4ea70108",
   "metadata": {},
   "source": [
    "To install these packages you just have to `pip install` the specific package name into your virtual environment (so remember to activate it first), by using the command line. (In fact, that's what you woudl have done to install Jupyter Notebooks - except we listed all the packages we wanted to install in a `requirements.txt` file, and then told pip to install anything listed in there."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b643ab87",
   "metadata": {},
   "source": [
    "Some of the most common packages to get installed will depend on your project, but common ones include:\n",
    "- `requests` for making http requests, like API requests for example\n",
    "- `pytz` for dealing with those pesky time zones and daylight savings - if you have to deal with timezones then `pytz` is essential!\n",
    "- `numpy` for fast vectorized calculations\n",
    "- `pandas` for dealing with datasets in a structured manner, and plenty of tools to manipulate these datasets - almost like a mini in-memory database\n",
    "- and many more...\n",
    "- "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3beea4c5",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.9.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}