Installing Requirements
=======================

Let's get our tutorial environment setup. Most of the setup work is in standard
Python development practices (install Python, make an isolated environment, and
setup packaging tools.)

This *Quick Tutorial* is based on:

* **Python 2.7**.

* **setuptools and easy_install**. We use `setuptools
  <https://pypi.python.org/pypi/setuptools/>`_ and its ``easy_install`` for
  package management.

* **Virtual environment.** Our home directory will contain a Python virtual
  environment that we'll use to run commands, and which will also serve as a
  directory in which we can dump stuff.

* **Unix commands**. Commands in this tutorial use UNIX syntax and paths.
  Windows users should adjust commands accordingly, although examples are given
  for Windows users in this chapter too.

.. _install-python-2.7:

Install Python 2.7
------------------

If you use Linux or Mac OS X, download the latest standard Python 2.7 release
(not development release) from `python.org
<https://www.python.org/downloads/>`_.

Windows users should also install the `Python for Windows extensions
<http://sourceforge.net/projects/pywin32/files/pywin32/>`_. Carefully read the
``README.txt`` file at the end of the list of builds, and follow its
directions. Make sure you get the proper 32- or 64-bit build and Python
version.

Linux users can either use their package manager to install Python 2.7 or may
`build Python 2.7 from source
<http://pyramid.readthedocs.org/en/master/narr/install.html#package-manager-
method>`_.

.. _set-an-environment-variable:

Set an Environment Variable
---------------------------

This tutorial will refer frequently to the location of the virtual
environment. We set an environment variable to save typing later.

Mac OS X and Linux:

.. code-block:: bash

    $ export VENV=~/pytesting

Windows:

.. code-block:: posh

    c:\> set VENV=c:\pytesting

.. _install-setuptools:

Install ``setuptools`` (Python packaging tools)
-----------------------------------------------

The following command will download a script to install ``setuptools``, then
pipe it to your environment's version of Python.

On Mac OS X or Linux:

.. code-block:: bash

    $ wget --no-check-certificate https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/bin/python

On Windows:

.. code-block:: posh

    # Use your web browser to download this file:
    # https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py
    # ...and save it to c:\ez_setup.py
    # Then run the following command:

    c:\> %VENV%\Scripts\python ez_setup.py

.. _create-a-virtual-environment:

Create a Virtual Environment
----------------------------

``virtualenv`` is a tool to create isolated Python 2.7 environments, each with
its own Python binary and independent set of installed Python packages. Let's
install virtualenv.

Mac OS X and Linux:

.. code-block:: bash

    $ sudo easy_install virtualenv

Windows:

.. code-block:: posh

    c:\> c:\Python27\Scripts\easy_install virtualenv

Let's create a virtualenv, using the location we just specified in the
environment variable.

Mac OS X or Linux:

.. code-block:: bash

    $ virtualenv $VENV

Windows:

.. code-block:: posh

    c:\> c:\Python27\Scripts\virtualenv %VENV%

Activate Your Virtual Environment
---------------------------------

"Activate" your virtual environment so that when you type ``python``, it means
"execute my virtual environment's Python interpreter instead of the system
Python interpreter":

On Linux/Mac OS X:

.. code-block:: bash

    $ source ~/pytesting/bin/activate


On Windows:

.. code-block:: bash

    c:> c:/pytesting/Scripts/activate

Checking It's Working
---------------------

Execute:

.. code-block:: bash

   $ python -c "import sys; print sys.prefix"

It should spit out something like:

.. code-block:: text

   ``/home/chrism/pytesting``

Or, on Windows:

.. code-block:: text

    ``c:\pytesting``

If instead, it spits out anything like ``/usr`` or ``c:\``, it's not activated
properly.

Conclusion
----------

We're now ready to go.

We'll be putting all the files we create into ``~/pytesting`` (Linux/Mac) or
``c:\pytesting`` (Windows) from here on in.

There will be a ``bin`` (or ``Scripts`` on Windows) dir in the directory, a
``lib`` dir, and possibly an ``include`` dir in there.  No worries, we'll put
the files and directories we create next to those.  Just don't accidentally
delete them.

.. sidebar:: Why Not Python 3?

   Cars.com uses Python 2.7 primarily, so that's what we're using in this
   class.  That said, almost all of the examples, code snippets, and frameworks
   used in this class will work as-is under Python 3, so you won't need to
   relearn much when you move to that version.