010_Python_Function_Package.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<small><small><i>\n",
    "All the IPython Notebooks in **Python Functions** lecture series by Dr. Milaan Parmar are available @ **[GitHub](https://github.com/milaan9/04_Python_Functions)**\n",
    "</i></small></small>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Python Package\n",
    "\n",
    "In this class, you'll learn to divide your code base into clean, efficient modules using Python packages. Also, you'll learn to import and use your own or third party packagesin your Python program."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What are packages?\n",
    "\n",
    "We don't usually store all of our files on our computer in the same location. We use a well-organized hierarchy of directories for easier access.\n",
    "\n",
    "Similar files are kept in the same directory, for example, we may keep all the songs in the \"**music**\" directory. Analogous to this, Python has packages for directories and **[modules](https://github.com/milaan9/04_Python_Functions/blob/main/007_Python_Function_Module.ipynb)** for files.\n",
    "\n",
    "As our application program grows larger in size with a lot of modules, we place similar modules in one package and different modules in different packages. This makes a project (program) easy to manage and conceptually clear.\n",
    "\n",
    "Similarly, as a directory can contain subdirectories and files, a Python package can have sub-packages and modules.\n",
    "\n",
    "A directory must contain a file named **`__init__.py`** in order for Python to consider it as a package. This file can be left empty but we generally place the initialization code for that package in this file.\n",
    "\n",
    "Here is an example. Suppose we are developing a game. One possible organization of packages and modules could be as shown in the figure below.\n",
    "\n",
    "| <img src=\"img/pack1.png\" width=\"400\" /> | \n",
    "|:--:| \n",
    "| **Package Module Structure in Python Programming** |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Importing module from a package\n",
    "\n",
    "We can import modules from packages using the dot **`.`** operator.\n",
    "\n",
    "For example, if we want to import the **`start`** module in the above example, it can be done as follows:\n",
    "\n",
    "```python\n",
    ">>>import Game.Level.start\n",
    "```\n",
    "\n",
    "Now, if this module contains a **[function](https://github.com/milaan9/04_Python_Functions/blob/main/001_Python_Functions.ipynb)** named **`select_difficulty()`**, we must use the full name to reference it.\n",
    "\n",
    "```python\n",
    ">>>Game.Level.start.select_difficulty(2)\n",
    "```\n",
    "\n",
    "If this construct seems lengthy, we can import the module without the package prefix as follows:\n",
    "\n",
    "```python\n",
    ">>>from Game.Level import start\n",
    "```\n",
    "\n",
    "We can now call the function simply as follows:\n",
    "\n",
    "```python\n",
    ">>>start.select_difficulty(2)\n",
    "```\n",
    "\n",
    "Another way of importing just the required function (or class or variable) from a module within a package would be as follows:\n",
    "\n",
    "```python\n",
    ">>>from Game.Level.start import select_difficulty\n",
    "```\n",
    "\n",
    "Now we can directly call this function.\n",
    "\n",
    "```python\n",
    ">>>select_difficulty(2)\n",
    "```\n",
    "\n",
    "Although easier, this method is not recommended. Using the full **[namespace](https://github.com/milaan9/01_Python_Introduction/blob/main/013_Python_Namespace_and_Scope.ipynb)** avoids confusion and prevents two same identifier names from colliding.\n",
    "\n",
    "While importing packages, Python looks in the list of directories defined in **`sys.path`**, similar as for **[module search path](https://github.com/milaan9/04_Python_Functions/blob/main/007_Python_Function_Module.ipynb)**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "hide_input": false,
  "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.8.8"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}