{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "c13b000e",
   "metadata": {},
   "source": [
    "## modules\n",
    "\n",
    "Why do we use modules?\n",
    "\n",
    "- Code reuse: allows code to be shared & reused.\n",
    "- Namespace partitioning: Avoid namespace clashes among different parts of your program.\n",
    "\n",
    "e.g.\n",
    "```\n",
    "math.isclose(a, b)                    # compares two floats (math.isclose(0.1+0.2, 0.3) == True)\n",
    "directions.isclose(point1, location)   \n",
    "```\n",
    "\n",
    "### Terminology\n",
    "\n",
    "Python files can either be:\n",
    "\n",
    "**Top Level Files**\n",
    "\n",
    "Sometimes called a \"script\", consists of main control flow of program.  Will typically use modules.\n",
    "\n",
    "**Modules**\n",
    "\n",
    "Define set of variables, functions, classes, etc. that can be used by other programs/modules.\n",
    "\n",
    "**Application**\n",
    "\n",
    "Top-level file that uses other modules.\n",
    "\n",
    "**Library**\n",
    "\n",
    "Collection of one or more modules with no top level file.\n",
    "\n",
    "\n",
    "### Import Syntax\n",
    "\n",
    "```python\n",
    "# bring `modulename` into current scope\n",
    "import modulename   \n",
    "\n",
    "# brings `thing1`, `thing2` into current scope\n",
    "from math import sin, cos    \n",
    "\n",
    "# bring `thing1` into current scope, but with `new_name`\n",
    "from modulename import thing1 as new_name \n",
    "\n",
    "# import everything from `modulename` into scope (DO NOT USE)\n",
    "from modulename import *\n",
    "```\n",
    "\n",
    "When an `import` statement is run (either form), the following happens:\n",
    "\n",
    "- Python searches on disk for the module.   (order determined by PYTHONPATH)\n",
    "- Once found, the file is executed until the end of the file is reached.\n",
    "- If `import modname`, then all top-level definitions are assigned to the module namespace.\n",
    "- If `from modname`, then the imported definitions are added to the global namespace.\n",
    "\n",
    "Note: `print` statements & other top-level code will run."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "de09d942",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "4d5f6e18",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import statistics\n",
    "#help(statistics)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ce952a10",
   "metadata": {},
   "source": [
    "### import `modulename`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "09c27388",
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "-1.0"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import math\n",
    "\n",
    "math.cos(math.pi)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9d5f6a9f",
   "metadata": {},
   "source": [
    "### `help` and `dir`\n",
    "\n",
    "`help` can be called on functions or modules and returns their docstring\n",
    "\n",
    "`dir` can be called on any object and returns all properties"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "164caf5b",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on built-in function cos in module math:\n",
      "\n",
      "cos(x, /)\n",
      "    Return the cosine of x (measured in radians).\n",
      "\n"
     ]
    }
   ],
   "source": [
    "#help(math)\n",
    "help(math.cos)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "58c6b06f",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "#dir(math)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0128b8f4",
   "metadata": {},
   "source": [
    "### from `modulename` import `thing`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "87bef5f0",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "39.4"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from statistics import mean\n",
    "\n",
    "mean([34, 44, 16, 21, 82])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "1604f2d7",
   "metadata": {},
   "outputs": [],
   "source": [
    "#help(statistics.mode)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "47280629-2406-4730-b04e-b2df88c37b14",
   "metadata": {},
   "source": [
    "## Ed Post on importing your code from IPython: \n",
    "\n",
    "https://edstem.org/us/courses/68016/discussion/5533114\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "1b80b290",
   "metadata": {},
   "outputs": [],
   "source": [
    "#dir(__builtins__)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "361acaa7",
   "metadata": {},
   "source": [
    "## module conventions\n",
    "\n",
    "Named in snake_case, typically concise.\n",
    "\n",
    "Convention is to use underscore prefix for modules intended to be internal:\n",
    "\n",
    "`import _util`\n",
    "\n",
    "Avoid built-in module names, `fast_math` not `math`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "57d95a79",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "29519f78",
   "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.10.15"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": false,
   "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": true
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}