{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installing Python with Anaconda"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> **This is a sample section from [Learning IPython for Interactive Computing and Data Visualization, second edition](http://ipython-books.github.io/minibook/).**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Although Python is an open-source, cross-platform language, installing it with the usual scientific packages used to be overly complicated. Fortunately, there is an all-in-one scientific Python distribution, **Anaconda** (by Continuum Analytics), that is free, cross-platform, and easy to install. Anaconda comes with Jupyter and all of the scientific packages we will use in this book. There are other distributions and installation options (like Canopy, WinPython, Python(x, y), and others), but for the purpose of this book we will use Anaconda throughout."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> TIP (Running Jupyter in the cloud): You can also use Jupyter directly from your web browser, without installing anything on your local computer: go to http://try.jupyter.org. Note that the notebooks created there are not saved. Let's also mention a similar service, [Wakari](https://wakari.io), by Continuum Analytics."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Anaconda comes with a package manager named **conda**, which lets you manage your Python distribution and install new packages."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> TIP (Miniconda): **Miniconda** (http://conda.pydata.org/miniconda.html) is a light version of Anaconda that gives you the ability to only install the packages you need."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "### Downloading Anaconda"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The first step is to [download Anaconda from Continuum Analytics' website](http://continuum.io/downloads). This is actually not the easiest part since several versions are available. Three properties define a particular version:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* The **operating system** (OS): Linux, Mac OS X, or Windows. This will depend on the computer you want to install Python on.\n",
    "* 32-bit or 64-bit: **you want the 64-bit version**, unless you're on a old or low-end computer. The 64-bit version will allow you to manipulate large datasets.\n",
    "* The version of Python: 2.7, or 3.4 (or later). In this book, **we will use Python 3.4**, because that's the latest version available at the time of this writing. However, it is easy to temporarily switch to a Python 2.7 environment with Anaconda if necessary (see below)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> INFO (Python 2 or Python 3?): Python 3 brought a few backward-incompatible changes. This is why many people are still using Python 2.7 at this time, even though Python 3 was released in 2008. **We will use Python 3 in this book, and we recommend that newcomers learn Python 3**. If you need to use legacy Python code that hasn't yet been updated to Python 3, you can use conda to temporarily switch to a Python 2 interpreter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once you have found the right link for your OS and Python 3 64-bit, you can download the package. You should then find it in your `downloads` directory (depending on your OS and your browser's settings)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "### Installing Anaconda"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Anaconda installer comes in different flavors depending on your OS:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Linux: the installer is a bash `.sh` script. Run it with a command like `bash Anaconda3-2.3.0-Linux-x86_64.sh` (if necessary, replace the filename by the one you downloaded).\n",
    "* The Mac graphical installer is a `.pkg` file that you can run with a double-click.\n",
    "* The Windows graphical installer is a `.exe` file that you can run with a double-click."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then, follow the instructions to install Anaconda on your computer. A few remarks:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* You don't need administrator rights to install Anaconda; in most cases, you can choose to install it in your personal user account.\n",
    "* Choose to put Anaconda in your system path, so that Anaconda's Python is the system default."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> INFO (Graphical launcher): Anaconda comes with a graphical launcher that you can use to start IPython, manage environments, and so on. You will find more details at http://docs.continuum.io/anaconda-launcher/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "### Before you get started..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before you get started with Anaconda, there are a few things you need to know:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Opening a terminal\n",
    "* Finding your home directory\n",
    "* Manipulating your system's PATH"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can skip this paragraph if you already know how to do these things."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Opening a terminal"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A **terminal** is a command-line application that lets you interact with your computer by typing commands with the keyboard, instead of clicking on windows with the mouse. While most computer users only know Graphical User Interfaces, developers and scientists generally need to know how to use the command-line interface for advanced usage. To use the command-line interface, follow the instructions that are specific to your OS:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* On Windows, you can use **Powershell**. Press the *Windows* and *R* keys, type `powershell` in the *Run* box, and press *Enter*. You will find more information about Powershell at https://blog.udemy.com/powershell-tutorial/. Alternatively, you can use the older Windows terminal by typing `cmd` in the *Run* box.\n",
    "* On Mac OS X, you can open the Terminal application, for example by pressing *Cmd-Space*, typing `terminal`, and pressing *Enter*.\n",
    "* On Linux, you can open the Terminal from your application manager."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In a terminal, use the `cd /path/to/directory` command to move to a given directory. For example, `cd ~` moves to your home directory, which is introduced in the next paragraph."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "#### Finding your home directory"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Your **home directory** is specific to your user account on your computer. It generally contains your applications' settings. It is often referred to as `~`. Depending on the OS, the location of the home directory is as follows:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* On Windows, its location is `C:\\Users\\YourName\\` where `YourName` is the name of your account\n",
    "* On Mac OS X, its location is `/Users/YourName/` where `YourName` is the name of your account\n",
    "* On Linux, its location is generally `/home/yourname/` where `yourname` is the name of your account"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, the directory `~/anaconda3` refers to `C:\\Users\\YourName\\anaconda3\\` on Windows and `/home/yourname/anaconda3/` on Linux."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "#### Manipulating your system's PATH"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The **PATH** is a global variable (also called an **environment variable**) defined by your operating system with the list of directories where executable programs are located. If you type a command like `python` in your terminal, you generally need to have a `python` (or `python.exe` on Windows) executable in one of the directories listed in the PATH. If that's not the case, an error may be raised."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can manually add directories to your system's PATH:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* On Windows, press the *Windows* and *R* keys, type `rundll32.exe sysdm.cpl,EditEnvironmentVariables`, and press *Enter*. You can then edit the PATH variable and append `;C:\\path\\to\\directory` if you want to add that directory. You will find more detailed instructions at http://www.computerhope.com/issues/ch000549.htm.\n",
    "* On Mac OS X, edit or create the file `~/.bash_profile` and add `export PATH=\"$PATH:/path/to/directory\"` at the end of the file.\n",
    "* On Linux, edit or create the file `~/.bashrc` and add `export PATH=\"$PATH:/path/to/directory\"` at the end of the file."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "### Testing your installation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To test Anaconda once it has been installed, open a terminal and type `python`. This opens a **Python console**, not to be confused with the **OS terminal**. The Python console is identified with a `>>>` prompt string, whereas the OS terminal is identified with a `$` (Linux/OS X) or `>` (Windows) prompt string. These strings are displayed in the terminal, often preceded by your computer's name, your login, and the current directory (for example, `yourname@computer:~$` on Linux or `PS C:\\Users\\YourName>` on Windows). You can type commands after the prompt string. After typing `python`, you should see something like the following:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```bash\n",
    "$ python\n",
    "Python 3.4.3 |Anaconda 2.3.0 (64-bit)| (default, Jun  4 2015, 15:29:08)\n",
    "[GCC 4.4.7 20120313 (Red Hat 4.4.7-1)] on linux\n",
    "Type \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n",
    ">>>\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What matters is that `Anaconda` or `Continuum Analytics` is mentioned here. Otherwise, typing `python` might have launched your system's default Python, which is *not* the one you want to use in this book."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you have this problem, you may need to add the path to the Anaconda executables to your PATH. For example, this path will be `~/anaconda3/bin` if you chose to install Anaconda in `~/anaconda3`. The `bin` directory contains Anaconda executables including `python`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you have any problem installing and testing Anaconda, you can ask for help on the mailing list (see the link at the end of this section)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, exit the Python prompt by typing `exit()` and pressing *Enter*."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "### Managing environments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Anaconda lets you create different isolated Python environments. For example, you can have a Python 2 distribution for the rare cases where you need to temporarily switch to Python 2."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To create a new environment for Python 2, type the following command in an OS terminal:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```bash\n",
    "$ conda create -n py2 anaconda python=2.7\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This will create a new isolated environment named `py2` based on the original Anaconda distribution, but with Python 2.7. You could also use the command `conda env`: type `conda env -h` to see the details."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can now activate your `py2` environment by typing the following command in a terminal:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Windows: `activate py2` (note that you might have problems with Powershell, see https://github.com/conda/conda/issues/626, or use the old `cmd` terminal)\n",
    "* Linux and Mac OS X: `source activate py2`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, you should see a `(py2)` prefix in front of your terminal prompt. Typing `python` in your terminal with the `py2` environment activated will open a Python 2 interpreter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Type `deactivate` on Windows or `source deactivate` on Linux/Mac OS X to deactivate the environment in the terminal."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Common conda commands"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here is a list of common commands:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* `conda help`: display the list of conda commands.\n",
    "* `conda list`: list all packages installed in the current environment.\n",
    "* `conda info`: display system information.\n",
    "* `conda env list`: display the list of environments installed. The currently active one is marked by a star `*`.\n",
    "* `conda install somepackage`: install a Python package (replace `somepackage` by the name of the package you want to install).\n",
    "* `conda install somepackage=0.7`: install a specific version of a package.\n",
    "* `conda update somepackage`: update a Python package to the latest available version.\n",
    "* `conda update anaconda`: update all packages.\n",
    "* `conda update conda`: update conda itself.\n",
    "* `conda update --all`: update all packages.\n",
    "* `conda remove somepackage`: uninstall a Python package.\n",
    "* `conda remove -n myenv --all`: remove the environment named `myenv` (replace this by the name of the environment you want to uninstall).\n",
    "* `conda clean -t`: remove the old tarballs that are left over after installation and updates."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some commands ask for confirmation (you need to press `y` to confirm). You can also use the `-y` option to avoid the confirmation prompt."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If `conda install somepackage` fails, you can try `pip install somepackage` instead. This will use the **Python Package Index (PyPI)** instead of Anaconda. Many scientific Anaconda packages are easier to install than the corresponding PyPI packages, because they are precompiled for your platform. However, many packages are available on PyPI but not on Anaconda."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here are some references:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* pip documentation at https://pip.pypa.io/en/stable/\n",
    "* PyPI repository at https://pypi.python.org/pypi"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### References"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here are a few references about Anaconda:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Continuum Analytics' website: http://continuum.io/\n",
    "* Anaconda main page: https://store.continuum.io/cshop/anaconda/\n",
    "* Anaconda downloads: http://continuum.io/downloads\n",
    "* List of Anaconda packages: http://docs.continuum.io/anaconda/pkg-docs\n",
    "* Conda main page: http://conda.io/\n",
    "* Anaconda mailing list: https://groups.google.com/a/continuum.io/forum/#!forum/anaconda\n",
    "* Continuum Analytics Twitter account at https://twitter.com/ContinuumIO\n",
    "* Conda FAQ: http://conda.pydata.org/docs/faq.html\n",
    "* Curated list of Python packages at http://awesome-python.com/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "### Downloading the notebooks"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All of this book's code is available on GitHub as notebooks. We recommend that you download the notebooks and experiment with them as you're working through the book."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> INFO (Git and GitHub): **GitHub** is a popular online service that hosts open source projects. It is based on the **Git Distributed Version Control System (DVCS)**. Git keeps track of file changes and enables collaborative work on a given project. Learning a version control system like Git is highly recommended for all programmers. Not using a version control system when working with code or even text documents is now considered as bad practice. You will find several references at https://help.github.com/articles/good-resources-for-learning-git-and-github/. The IPython Cookbook also contains several recipes about Git and best interactive programming practices."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here is how to download the book's notebooks:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Install git: http://git-scm.com/downloads\n",
    "* Check your git installation: open a new OS terminal and type `git version`. You should see the version of git and not an error message.\n",
    "* Type the following command:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```bash\n",
    "$ git clone https://github.com/ipython-books/minibook-2nd-code.git  \"$HOME/minibook\"\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This will download the very latest version of the code into a `minibook` subdirectory in your home directory. You can also choose another directory."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "From this directory, you can update to the latest version at any time by typing `git pull`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> TIP (Notebooks on GitHub): Notebook documents stored on GitHub (with the file extension `.ipynb`) are automatically rendered on the GitHub website."
   ]
  }
 ],
 "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.4.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}