0. Executing Your First Python Script.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Executing Your First Python Script"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Objectives\n",
    "By the end of this tutorial, you will be able to:  \n",
    "- Download Python\n",
    "- Understand the concept of a Python script\n",
    "- Write a basic Python script\n",
    "- Execute basic shell commands from the command line\n",
    "- Execute a Python script from the command line\n",
    "- Write comments on your code\n",
    "- Import other modules to your script\n",
    "- Know where to go to learn more"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='toc'></a>\n",
    "## Table of Contents"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- [Downloading Python](#download)\n",
    "- [Python Scripts](#scripts)\n",
    "- [Other Tips](#tips)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='download'></a>\n",
    "## Downloading Python"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First, you need to test if you already have Python pre-installed on your computer (as is the case if you have a Mac). To do this, open your command line interpreter. From here on out, when I say \"command line\" or \"shell\", I am referring to Command Prompt in Windows or Terminal in Mac.\n",
    "\n",
    "Once open, type \"python\" and press enter. If you have it installed, you'll get the following display. (You can quit by typing **quit()** and pressing enter.)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"Screenshots/ExecutingPython-CheckPython.png\" alt=\"Terminal\" style=\"width: 400px;\"/>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you have Windows or it is not pre-installed on your Mac, you can get started by downloading Python [here](https://www.python.org/downloads/).\n",
    "\n",
    "However, if you're planning to use Python for data science, I would instead install Python by downloading Anaconda, a Python distribution. Once you download Anaconda, Python will automatically be downloaded onto your computer and placed in your PATH.\\* Furthermore, Anaconda will automatically download more than 1000 of the most popular data science packages, including numpy, pandas, and will set up Jupyter notebook. You can download Anaconda [here](https://www.anaconda.com/download/).\n",
    "\n",
    "If you choose not to download Anaconda, that's fine. It's typically very easy to install packages as you need them (assuming you are not behind a firewall). You just open the terminal and type: **pip install [package name]**\n",
    "\n",
    "\\* I wouldn't worry about this for now, but if you're interested: PATH is a system variable that holds the name of all the directories where it will look for some executable program. What does this mean? Let's say that the directory with your Python executable file is \"yourname/Documents/.\" When you download Python, this path is *usually* added to your PATH. So, when you open the command line, you can type \"python\" and your system will know to look for a file named \"python.exe\" in one of the directories in your PATH (including yourname/Documents) and try to execute it.\n",
    "\n",
    "A problem arises if you download Python, type \"python\" in the command line, and get a message that says \"Python is not recognized as an internal or external command.\" This means your python installation was not added to your PATH. Therea are two ways around this.\n",
    "\n",
    "1. You can just type \"yourname/Documents/python [yourscript.py]\" every time you want to execute Python.\n",
    "2. This can be tedious. Instead, you should Google how to edit system variables on your OS and make sure you add the directory holding Python to your PATH."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='scripts'></a>\n",
    "## Python Scripts\n",
    "([Back to Table of Contents](#toc))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Overview"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A Python script is simply a text document that you create using any text editor, like Notepad, though anyone who works with a programming language regularly uses something at least as sophisticated as Notepad++ (Windows) or TextWrangler (Mac). Other popular text editors/IDEs for Python include Atom, Sublime, pyCharm, or Spyder."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Writing your first script"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**1. Open up your text editor and save it with the extension \".py\".**  \n",
    "In this case, let's save it as \"HelloWorld.py\". It's good practice to leave out spaces in the names of folder and file names.\n",
    "\n",
    "**2. Type a line of code in the document.**  \n",
    "Let's try this line:\n",
    "**print(\"Hello, world.\")**\n",
    "\n",
    "**3. Hit save when you're finished.**  \n",
    "Every time you make a change, you need to save it to push the change."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"Screenshots/ExecutingPython-HelloWorld.png\" alt=\"Create Hello, World\" style=\"width: 400px;\"/>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Executing a Python Script"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**1. Open the Command Line **  \n",
    "As I mentioned above, this means Command Prompt for Windows or Terminal for Mac. Note, since I'm working off Mac, some commands may be different for Windows. If you get an error, remember that Google and StackOverflow are a programmer's best friend!\n",
    "\n",
    "**2. Navigate to the directory where you saved HelloWorld.py.**  \n",
    "So, your first step is to check your current working directory. To do this, type **pwd** in the command line and press return.\n",
    "\n",
    "Then you want to change your directory to wherever you saved the HelloWorld.py folder. You can do this using the change directory command (**cd**). In my case, I'll simply change to my \"Documents\" folder by typing **cd Documents**.\n",
    "\n",
    "**3. Execute the script!**\n",
    "In the command line type **python HelloWorld.py**\n",
    "\n",
    "Note that, you can type the first few letters of a file (e.g., \"Hel\") and press tab. If you do this, the command should auto-complete (you can do this when changing your directory as well!)\n",
    "\n",
    "**4. Sit back and appreciate your hard work!**\n",
    "Once you press return, you should see \"Hello, world!\" print to the Terminal.\n",
    "\n",
    "And that's all there is to it! The world is yours!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"Screenshots/ExecutingPython-ExecutingPython.png\" alt=\"Execute Hello, World\" style=\"width: 400px;\"/>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "** TIP: I've only included the bare minimum on how to use the shell. You should really explore the various things you can do with the command line (in fact, you'll find that the  mouse and GUI combo is completely redundant!).**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Building Out Your Script"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So, obviously this isn't all there is to it. Even relatively simple scripts can be hundreds of lines long. And, most likely, most of the functions you want to use won't be a part of \"base\" Python's functionality (i.e., without the aid of packages and modules).\n",
    "\n",
    "So, there's a few other things you should know:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Comments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In a script, you can write comments. Comments are lines or parts of lines of code that are not executed. They're just for humans to help our tiny brains understand the code.\n",
    "\n",
    "On a given line of code, once you use an octothorp (#), or pound sign, the rest of the line is commented out. Observe:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello\n"
     ]
    }
   ],
   "source": [
    "print(\"Hello\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello\n"
     ]
    }
   ],
   "source": [
    "print(\"Hello\") # This will print the word \"Hello\" to the console"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# In practice, you'll usually see comments take up their own line"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Importing packages"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In practice, you'll write a lot of code that relies on functions that are written by other people. If you want to use some of this code, you'll have to \"import\" it before you use it. Generally, people import all their commands at once at the top of the script.\n",
    "\n",
    "Note: When I use the term \"package\", I typically mean package *or* module. This distinction can be found in the Appendix of the \"The Basics of Programming with Python\" notebook in this tutorial series."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# You can import functions one at a time\n",
    "import os\n",
    "import csv"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Or you can import them all at once\n",
    "import os, csv"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([1, 2, 3])"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# You don't have to worry about this for now, but you can also\n",
    "# import function under a different name. This is a matter of \n",
    "# convention that you can learn by reading documentation for \n",
    "# specific packages\n",
    "\n",
    "import numpy as np \n",
    "\n",
    "# This way, you can reference a numpy method by using \"np\"\n",
    "# instead of \"numpy\", which is much more verbose\n",
    "\n",
    "np.array([1, 2, 3]) #equivalent to numpy.array([1, 2, 3])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='tips'></a>\n",
    "## Other Tips\n",
    "([Back to Table of Contents](#toc))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**1. Read the Documentation**  \n",
    "Python has a rich set of [documentation](https://docs.python.org/3/). Also, most individual Python packages and modules have really robust documentation. Documentation gives you the syntax of the various functions associated with a package, best practices, and examples. It's usually a good idea to read these for any packages you use. It'll help you get up to speed and it's usually a good first place to go (rather than immediately asking your question on a web forum, where someone will almost always ask \"Did you read the documentation?\").\n",
    "\n",
    "**2. Read the style guide**  \n",
    "The [style guide](https://www.python.org/dev/peps/pep-0008/) is indispensable. It lets you know the most \"Pythonic\" way to write code. It will make it easier to both read other people's code, and to share your own (see next item).\n",
    "\n",
    "**3. Learn to search and read answers on forums like StackOverflow.**  \n",
    "StackOverflow will be your best friend as you learn Python. If you have a question, it's almost certainly been answered. \n",
    "\n",
    "Make sure you read the various guides on how to ask questions. This way, people can help you in the most productive way. You might start [here](https://stackoverflow.com/help/how-to-ask)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# END OF FILE"
   ]
  }
 ],
 "metadata": {
  "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.6.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}