11-CommandLine.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Command Line, Scripts & Modules\n",
    "\n",
    "- command line & shell commands\n",
    "- file paths (absolute and relative)\n",
    "- scripts and modules\n",
    "- `import`\n",
    "    - `from`\n",
    "    - `as`"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Jupyter Notebooks are a helpful tool, but they're _bulky_."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## File Systems"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "Computers use a hierarchical file systems that organizes files & folders.\n",
    "</div>"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "When you click through the folders (directories) on your computer, you're interacting with this hierarchical system."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Command Line"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "A <b>command line interface</b> is a way to interact with a computer through written commands.\n",
    "</div>"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "The command line allows us to:\n",
    "\n",
    "- create files\n",
    "- edit files\n",
    "- run python scripts\n",
    "- etc.\n",
    "\n",
    "...without clicking on anything."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### The Terminal\n",
    "\n",
    "The **terminal** is where you can type these commands into the command line.\n",
    "\n",
    "Accessing the terminal...\n",
    "\n",
    "- possible on your computer\n",
    "- and on datahub"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Shell Commands\n",
    "\n",
    "...can be run in the terminal _and_ Jupyter notebooks\n",
    "\n",
    "Do this by starting with `!`"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "#### Check current directory"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "# print working directory\n",
    "!pwd"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## An important aside: File Paths"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "The specific location of a file or folder on your computer. </div>"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "When using a Graphical User Interface (GUI), you click on directories to access subdirectories and finally find the file you're interested in."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "When using the command line, you specify a file's path explicitly with text. "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Absolute vs. Relative Paths\n",
    "\n",
    "The two ways to specify the path to your file of interest allow for flexibility in programming."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "#### Absolute Paths"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "<b>Absolute paths</b> specify the <b>full</b> path for a given file system (starting from the root directory). \n",
    "</div>"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "**root** specifies the 'highest' directory in the file structure (the start).\n",
    "\n",
    "An absolute file path starts with a slash `/` specifying the root directory.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "01-Introduction.ipynb 07-Collections.ipynb  A1-CodeStyle.ipynb\r\n",
      "02-Tooling.ipynb      08-Debugging.ipynb    A2-Syntax.ipynb\r\n",
      "03-Variables.ipynb    09-Loops.ipynb        A3-Examples.ipynb\r\n",
      "04-Operators.ipynb    10-Algorithms.ipynb   \u001b[34mCL-Answers\u001b[m\u001b[m\r\n",
      "05-Functions.ipynb    11-Methods.ipynb      \u001b[34mExam-Prep\u001b[m\u001b[m\r\n",
      "06-Conditionals.ipynb 12-Classes.ipynb      \u001b[34mimg\u001b[m\u001b[m\r\n"
     ]
    }
   ],
   "source": [
    "## absolute path\n",
    "## this is specific to my computer\n",
    "## look at the path output above for you computer\n",
    "!ls /Users/shannonellis/Desktop/Teaching/COGS18/LectureNotes-COGS18"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Relative Paths"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "<b>Relative paths</b> specify the path to a file from your <b>current working directory</b> (where your computer is working right now). \n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# remind us of our current working directory\n",
    "!pwd"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[34mCAPE\u001b[m\u001b[m       \u001b[34mChegg\u001b[m\u001b[m      \u001b[34mR\u001b[m\u001b[m          \u001b[34mclass_data\u001b[m\u001b[m\r\n"
     ]
    }
   ],
   "source": [
    "# relative path\n",
    "# this is specific to my computer\n",
    "!ls ../../COGS108"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "\n",
    "- `..` specify you want to move one directory up in your hierarchy\n",
    "- `COGS108/` specifies the path to the directory I want to list files in\n",
    "- each directory is separated with a slash (`/`)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "This **relative** path does _not_ start with a leading slash (b/c it's not an absolute path)."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Clicker Question #1\n",
    "\n",
    "Given the following file structure: \n",
    "\n",
    "- `/`\n",
    "    - `scripts/`\n",
    "        - cool_thing.py\n",
    "        - super_cool_thing.py\n",
    "    - `images/`\n",
    "        - image1.png\n",
    "        - image2.png\n",
    "    - `notebooks/`\n",
    "        - 00_intro.ipynb\n",
    "        - 01_variables.ipynb\n",
    "    \n",
    "\n",
    "If your current working directory is `notebooks`, what is the **absolute path** to `cool_thing.py`?\n",
    "\n",
    "- A) `/scripts/cool_thing.py`\n",
    "- B) `scripts/cool_thing.py`\n",
    "- C) `cool_thing.py`\n",
    "- D) `../scripts/cool_thing.py`\n",
    "- E) ¯\\\\\\_(ツ)\\_/¯"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Clicker Question #2\n",
    "\n",
    "Given the same file structure: \n",
    "\n",
    "- `/`\n",
    "    - `scripts/`\n",
    "        - cool_thing.py\n",
    "        - super_cool_thing.py\n",
    "    - `images/`\n",
    "        - image1.png\n",
    "        - image2.png\n",
    "    - `notebooks/`\n",
    "        - 00_intro.ipynb\n",
    "        - 01_variables.ipynb\n",
    "    \n",
    "\n",
    "If your current working directory is `notebooks`, what is the **relative path** to `cool_thing.py`?\n",
    "\n",
    "- A) `/notebooks/../scripts/cool_thing.py`\n",
    "- B) `scripts/cool_thing.py`\n",
    "- C) `/scripts/cool_thing.py`\n",
    "- D) `../scripts/cool_thing.py`\n",
    "- E) ¯\\\\\\_(ツ)\\_/¯"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Shell Commands\n",
    "\n",
    "...can be run in the terminal _and_ Jupyter notebooks"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "#### Check current directory"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# print working directory\n",
    "!pwd"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "#### Change directory"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# change directory \n",
    "!cd ~/ "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "Here, we saw `~/`. \n",
    "\n",
    "- `~` specifies the user's home directory of your computer\n",
    "- each directory is separated with a slash (`/`)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### List files in a directory"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# list files (list segments)\n",
    "!ls"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### More Shell Commands"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "#### Make a new directory"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# make directory \n",
    "!mkdir dir_name"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "#### Create a file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# create an empty file\n",
    "!touch new_file.py "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "#### Move a file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# move file\n",
    "# notice the relative file path\n",
    "!mv new_file.py dir_name/"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### And Some More"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "#### Print out a message"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "!echo Hello World!"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "#### Print the contents of a file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "!cat dir_name/new_file.py"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "#### Open to see and edit contents of a file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "outputs": [],
   "source": [
    "# will not work on datahub\n",
    "!open dir_name/new_file.py"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Clicker Question #3\n",
    "\n",
    "Which is the best description of the following command:\n",
    "    \n",
    "`ls -l`\n",
    "\n",
    "- A) `ls -l` is most analogous to a class in Python\n",
    "- B) The whole `ls -l` is like a function call\n",
    "- C) `-l` is analogous to a function call, and `ls` is like a parameter\n",
    "- D) `ls` is analogous to a function, and `-l` is like a parameter\n",
    "- E) There is no clear analogy here to Python"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "## test out here"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Clicker Question #4\n",
    "\n",
    "Which creates a file?     \n",
    "   \n",
    "- A) `mkdir`\n",
    "- B) `pwd`\n",
    "- C) `cd`\n",
    "- D) `touch`\n",
    "- E) `cat`"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Windows Command Prompt\n",
    "\n",
    "Some commands are slightly different if you are using windows command prompt:\n",
    "\n",
    "- `dir` : lists files in current directory\n",
    "- `move` : moves a file\n",
    "- `copy` : copies a file\n",
    "- `rename` : renames a file\n",
    "- `type` : can be used to print out a file\n",
    "    \n",
    "Note that `pwd`, `cd`, `mkdir`, `echo` are all the same in Windows command prompt.\n",
    "\n",
    "If you want to make a new empty file, you can do:\n",
    "\n",
    "`'' > my_file.py`\n",
    "\n",
    "^This construction puts an empty string into a file. If the filename is not found, it will create a new (empty) file."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Python Files"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "Python files are plain-text files, with Python code in them, that can be executed and/or imported from.\n",
    "</div>"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Script vs. Module File"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "### Scripts"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "A <b>script</b> is a Python file that can be run to execute a particular task. \n",
    "</div>"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "### Module Files"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "A <b>module</b> file is a file with Python code (typically functions & classes) that we can import and use.\n",
    "</div>"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Remember: if you're writing code, you cannot just click through to the file you want. You need to specify _using code_ where the file you want is. \n",
    "\n",
    "This is where understanding file paths is critically important."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Text Editors"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "Text-editors are programs made for editing text. Many text-editors are designed for writing code specifically. \n",
    "</div>"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "### Terminal Based Text Editors\n",
    "\n",
    "There are text editors designed to be used within a terminal, such as `vim`, `emacs`, or `nano`. "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "#### vim\n",
    "\n",
    "`vim` is a terminal based text-editor. Type `vim filename` in command line to open a file in vim. \n",
    "\n",
    "`vim` has different modes:\n",
    "\n",
    "- click `escape` + `i` to enter edit mode (insert mode). \n",
    "    - This will let you write text / code into the file\n",
    "- To escape vim, press `escape` then type `:wq` and enter to save and quit vim\n",
    "    - If you want to exit without saving, you can do `:!q` to force quit without saving"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "### Non-Terminal Text Editors\n",
    "\n",
    "For writing code (outside of notebooks and the terminal), you probably want a code-focused IDE (i.e. Visual Studio Code) or stand-alone text editor (i.e. `Sublime`)."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Namespaces & Scope"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-success\">\n",
    "A <b>namespace</b> is a 'place' with a set of names and their corresponding objects.\n",
    "</div>"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Each Jupyter Notebook has its own Namespace.\n",
    "\n",
    "If you have two notebooks open at the same time, they don't know about eachother or what variables have been created in the other."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Names that are defined and available in a given namespace are in **scope**."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That is, the *scope* of an object is where it is available to / from. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# see what's stored in global namespace\n",
    "a = 3\n",
    "b = 15\n",
    "%whos"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Modules & Packages"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-success\">\n",
    "A <b>module</b> is a set of Python code with functions, classes, etc. available in it. A Python <b>package</b> is a directory of modules.\n",
    "</div>"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Modules are stored in Python files (.py). We can import these files into our namespace, to gain access to the module within Python."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In A3 you had to import the package: `nltk`: \n",
    "\n",
    "- **package** is a whole bunch of modules\n",
    "- a **module** stores python (.py) files\n",
    "- when imported, we have access to its functionality"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `import`"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-success\">\n",
    "<code>import</code> is a keyword to import external code into the local namespace.\n",
    "</div>"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Why do it this way (importing modules)? \n",
    "\n",
    "1. Minimize startup costs\n",
    "2. Functions in different packages could have the same name - break programs"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `import` example: math module"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For something not yet in your Namespace..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# we haven't imported the module yet\n",
    "# this code fails if you haven't yet imported math\n",
    "type(math)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import the math module\n",
    "import math"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Check the type of math\n",
    "type(math)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# By the way - modules are objects\n",
    "isinstance(math, object)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Using code from our math module\n",
    "# remember to tab complete or use dir(math)\n",
    "math.sqrt(9)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `import` example: random module"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import random"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Random is also a module\n",
    "type(random)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Explore what is available in random\n",
    "dir(random)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# working with random\n",
    "random."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "## access documentation\n",
    "random.choice?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "## access underlying code\n",
    "random.choice??"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `random` Example"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# random.sample() documentation\n",
    "random.sample?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Random example\n",
    "to_choose_from = ['1', '2', '3', '4', '5']\n",
    "number_to_choose = 2\n",
    "\n",
    "chosen = random.sample(to_choose_from, number_to_choose)\n",
    "\n",
    "print(chosen)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Imports: `from` & `as`"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-success\">\n",
    "<code>from</code> and <code>as</code> allows us to decide exactly what objects to import into our namespace, and what we call them (in our namespace).\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import a specific object from a module\n",
    "from random import choice"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "## do NOT have to type module name \n",
    "## using this approach\n",
    "## to call this\n",
    "choice(to_choose_from)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import a module with a specific name in our namespace\n",
    "# used when module names are long\n",
    "import collections as cols"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "## collections is not defined\n",
    "## this code will fail\n",
    "collections."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# this is how you would do it\n",
    "cols."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# putting it all together\n",
    "# Import a specific thing and give it a specific name\n",
    "from string import punctuation as punc"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Clicker Question #1\n",
    "\n",
    "Which of the following is NOT a valid Python import statement?\n",
    "\n",
    "- A) `import collections as col`\n",
    "- B) `from statistics import mean as average`\n",
    "- B) `from os import path`\n",
    "- D) `from random import choice, choices`\n",
    "- E) `import ascii_letters from string`"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Clicker Question Answer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Check our imports\n",
    "# import collections as col\n",
    "# from statistics import mean as average\n",
    "# from os import path\n",
    "# from random import choice, choices\n",
    "# import ascii_letters from string"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Importing Custom Code I"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Why do this? \n",
    "\n",
    "Having a whole bunch of functions in a Jupyter Notebook will start to get clutered.\n",
    "\n",
    "Also, they're not reusable later without copying them into your new notebook. \n",
    "\n",
    "Modules avoid this!"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## module: `remote.py`\n",
    "\n",
    "If you want to practice using import with the `remote` example in lecture, store the code in the next cell in a text file saved as `remote.py`. Be sure this is saved in the same directory (folder) as the notebook from which you're trying to call it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def my_remote_function(input_1, input_2):\n",
    "    \"\"\"A function from far away.\n",
    "    \n",
    "    This function returns the sum of the two inputs.\n",
    "    \"\"\"\n",
    "    \n",
    "    return input_1 + input_2\n",
    "\n",
    "def choice(list_to_choose_from):\n",
    "    \"\"\"Choose and return an item from a list. \n",
    "    \n",
    "    Notes: I am a custom choice function: I am NOT from `random`.\n",
    "    \n",
    "    Hint: my favorite is the last list item.\n",
    "    \"\"\"\n",
    "    \n",
    "    return list_to_choose_from[-1]\n",
    "\n",
    "class MyNumbers():\n",
    "    \n",
    "    kind_of_thing = 'numbers'\n",
    "    \n",
    "    def __init__(self, num1, num2):\n",
    "        \n",
    "        self.num1 = num1\n",
    "        self.num2 = num2\n",
    "        \n",
    "    def add(self):\n",
    "        \n",
    "        return self.num1 + self.num2\n",
    "    \n",
    "    def subtract(self):\n",
    "        \n",
    "        return self.num2 - self.num1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import some custom code\n",
    "from remote import my_remote_function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Investigate our imported function\n",
    "my_remote_function?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Run our function\n",
    "my_remote_function(2, 1)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Importing Custom Code II"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import a class class from an external module\n",
    "from remote import MyNumbers"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Define an instance of our custom class\n",
    "nums = MyNumbers(2, 3)\n",
    "type(nums)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Check \n",
    "nums.add()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Check the definition of the code we imported\n",
    "nums.add??"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Name Conflicts"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from random import choice"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# choice is currently from random module\n",
    "choice?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "choice([1, 2, 3, 4, 5])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from remote import choice"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# now it's from my remote module\n",
    "choice?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "choice([1, 2, 3, 4, 5])"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "While you _can_ have functions with the same name in two different places...do your best to avoid this.\n",
    "\n",
    "It's Python legal but bad for your nerves."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A note on `*`\n",
    "\n",
    "If you see `from module import *` this means to import everything (read as 'from module import everything'). \n",
    "\n",
    "This is generally considered not to be the best, as it is then unclear in your code exactly where the functionality came from."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# a valid way to import\n",
    "from random import choice\n",
    "choice([2,3,4])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# a valid way to import\n",
    "import random\n",
    "random.choice([2,3,4,])"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## script: `remote_script.py`\n",
    "\n",
    "\n",
    "If you want to run your own script example in lecture, store the code in the next cell in a text file saved as `remote_script.py`. Be sure this is saved in the same directory (folder) as the notebook from which you're trying to call it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from remote import MyNumbers\n",
    "nums = MyNumbers(2, 3)\n",
    "print(\"nums value: \", nums.num1, nums.num2)\n",
    "print(\"nums type: \", type(nums))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# run the script\n",
    "!python remote_script.py"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Executing Python Files"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "From the command line, you can execute a Python script using the `python` command:\n",
    "\n",
    "`python dir_name/new_file.py`"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Clicker Question #5\n",
    "\n",
    "To create a file and see its contents, which command line commands would you use (and in which order)?    \n",
    "   \n",
    "- A) `mkdir` > `cd`\n",
    "- B) `pwd` > `ls`\n",
    "- C) `cd` > `pwd`\n",
    "- D) `touch` > `cat`\n",
    "- E) `cat` > `touch`"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Clicker Question #6\n",
    "\n",
    "Given the file structure from earlier: \n",
    "\n",
    "- `/`\n",
    "    - `scripts/`\n",
    "        - cool_thing.py\n",
    "        - super_cool_thing.py\n",
    "    - `images/`\n",
    "        - image1.png\n",
    "        - image2.png\n",
    "    - `notebooks/`\n",
    "        - 00_intro.ipynb\n",
    "        - 01_variables.ipynb\n",
    "\n",
    "Your currently working within `notebooks` and you want to execute the code in 'cool_thing.py' from the command line. How would you do that?\n",
    "\n",
    "\n",
    "- A) `python cool_thing.py` \n",
    "- B) `python ../notebooks/cool_thing.py` \n",
    "- C) `python ../scripts/cool_thing.py` \n",
    "- D) `python ../cool_thing.py` \n",
    "- E) ¯\\\\\\_(ツ)\\_/¯ "
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "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.11.8"
  },
  "rise": {
   "scroll": true
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}