Table Of Contents

Previous topic

1. Overview

Next topic

3. Django Basics

This Page

2. Getting Ready to Tango

Let’s get set up! To tango with Django, you’ll need to ensure that you have everything you need installed on your computer and that you have a sound understanding of your development environment. This chapter walks you through what you need and what you need to know.

For this tutorial, you’ll require the following key pieces of software.

  • Python version 2.7.5
  • Django version 1.5.4

As Django is a web application framework written in the Python programming language, you will be required to have a working knowledge of Python. If you haven’t used Python before or you simply wish to brush up on your skills, then we highly recommend that you check out and work through one or more of the following guides.

2.1. Using the Terminal

In order to set up your environment learning how to use the Command Line Interpreter (CLI) provided by your Operating System is really important. Through the course of this tutorial, you will be interacting with the CLI routinely. If you are already familiar with using the command line interface you can skip directly to Installing the Software section.

UNIX-based operating systems all use a similar-looking terminal. Descendants, derivatives and clones of UNIX include Apple’s OS X and the many available Linux distributions available today. All of these operating systems contain a core set of commands which help you navigate through your filesystem and launch programs, all without the need of any graphical interface. This section provides the key commands you should familiarise yourself with.

Note

This tutorial is focused towards users of UNIX-based or UNIX-derived operating systems. While Python and Django can run in a Windows-based environment, many of the commands that we use in this book are for UNIX-based terminals. These commands can however be replicated in Windows by using the graphical user interface, using the relevant command in a Windows Command Prompt, or using Windows PowerShell which provides an CLI like similar to a UNIX terminal.

Upon launching a new terminal instance, you’ll typically be presented with something like:

sibu:~ leif$

This is called the prompt, and indicates when the system is waiting to execute your every command. The prompt you see varies depending on the operating system you are using, but all look generally very similar. In the example above, there are three key pieces of information to observe:

  • your username and computer name (username of leif and computer name of sibu);
  • your current working directory (the tilde, or ~); and
  • the privilege of your user account (the dollar sign, or $).

The dollar sign ($) typically indicates that the user is a standard user account. Conversely, a hash symbol (#) may be used to signify the user logged in has root privileges. Whatever symbol is present is used to signify that the computer is awaiting your input.

Open up a terminal window and see what your prompt looks like.

When you are using the terminal, it is important to know where you are in the file system. To find out where you are, you can issue the command pwd. This will display your present working directory. For example, check the example terminal interactions below.

Last login: Mon Sep 23 11:35:44 on ttys003
sibu:~ leif$ pwd
/Users/leif
sibu:~ leif$

You can see that the present working directory in this example is: /Users/leif.

You’ll also note that the prompt indicates that my present working directory is ~. This is because the tilde (~) represents your home directory. The base directory in any UNIX-based file system is the root directory. The path of the root directory is denoted by a single forward slash (/).

If you are not in your home directory you can change directory (cd) to your home directory by issuing the following command.

$ cd ~

Let’s create a directory called code. To do thus, use the make directory command (mkdir), as shown below.

$ mkdir code

To move to the newly-created code directory, enter cd code. If you now check your current working directory, you’ll notice that you will be in ~/code/. This may also be reflected by your prompt. Note in the example below that the current working directory is printed after the sibu computer name.

Note

Whenever we refer to <workspace>, we’ll be referring to your code directory.

sibu:~ leif$ mkdir code
sibu:~ leif$ cd code
sibu:code leif$
sibu:code leif$ pwd
/Users/leif/code

To list the files that are in a directory, you can issue the command ls. You can also see hidden files or directories - if you have any - you can issue the command ls -a, where a stands for all. If you cd back to your home directory (cd ~) and then issue ls, you’ll see that you have something called code in your home directory.

To find out a bit more about what is in your directory, issue ls -l. This will provide a more detailed listing of your files and whether it is a directory or not (denoted by a d at the start of the line).

sibu:~ leif$ cd ~
sibu:~ leif$ ls -l

drwxr-xr-x   36 leif  staff    1224 23 Sep 10:42 code

The output also contains information on the permissions associated to the directory, who created it (leif), the group (staff), the size, the date/time the file was modified at, and, of course, the name.

You may also find it useful to be able to edit files within your terminal. There are many editors which you can use - some of which may already be installed on your computer. The nano editor for example is a straightforward editor - unlike vi which can take some time to learn. Below are a list of commonly-used UNIX commands that you will find useful.

2.1.1. Core Commands

All UNIX-based operating systems come with a series of built-in commands - with most focusing exclusively on file management. The commands you will use most frequently are listed below, each with a short explanation on what they do and how to use them.

  • pwd: Prints your current working directory to the terminal. The full path of where you are presently is displayed.
  • ls: Prints a list of files in the current working directory to the terminal. By default, you do not see the sizes of files - this can be achieved by appending -lh to ls, giving the command ls -lh.
  • cd: In conjunction with a path, allows you to change your current working directory. For example, the command cd /home/leif/ changes the current working directory to /home/leif/. You can also move up a directory level without having to provide the absolute path by using two dots, e.g. cd ...
  • cp: Copies files and/or directories. You must provide the source and the target. For example, to make a copy of the file input.py in the same directory, you could issue the command cp input.py input_backup.py.
  • mv: Moves files/directories. Like cp, you must provide the source and target. This command is also used to rename files. For example, to rename numbers.txt to letters.txt, issue the command mv numbers.txt letters.txt. To move a file to a different directory, you would supply either an absolute or relative path as part of the target - like mv numbers.txt /home/david/numbers.txt.
  • mkdir: Creates a directory in your current working directory. You need to supply a name for the new directory after the mkdir command. For example, if your current working directory was /home/david/ and you ran mkdir music, you would then have a directory /home/david/music/. You will need to then cd into the newly created directory to access it.
  • rm: Shorthand for remove, this command removes or deletes files from your filesystem. You must supply the filename(s) you wish to remove. Upon issuing a rm command, you will be prompted if you wish to delete the file(s) selected. You can also remove directories using the recursive switch. Be careful with this command - recovering deleted files is very difficult, if not impossible!
  • rmdir: An alternative command to remove directories from your filesystem. Provide a directory that you wish to remove. Again, be careful: you will not be prompted to confirm your intentions.
  • sudo: A program which allows you to run commands with the security privileges of another user. Typically, the program is used to run other programs as root - the superuser of any UNIX-based or UNIX-derived operating system.

Note

This is only a brief list of commands. Check out ubuntu’s documentation on Using the Terminal for a more detailed overview, or the Cheat Sheet by FOSSwire for a quick reference guide.

2.2. Installing the Software

Now that you have a decent understanding of how to interact with the terminal, you can begin to install the software required for this tutorial.

2.2.1. Installing Python

So, how do you go about installing Python 2.7.5 on your computer? You may already have Python installed on your computer - and if you are using a Linux distribution or OS X, you will definitely have it installed. Some of your operating system’s functionality is implemented in Python, hence the need for an interpreter!

Unfortunately, nearly all modern operating systems utilise a version of Python that is older than what we require for this tutorial. There’s many different ways in which you can install Python, and many of them are sadly rather tricky to accomplish. We demonstrate the most commonly used approaches, and provide links to additional reading for more information.

Warning

This section will detail how to run Python 2.7.5 alongside your current Python installation. It is regarded as poor practice to remove your operating system’s default Python installation and replace it with a newer version. Doing so could render aspects of your operating system’s functionality broken!

2.2.1.1. Apple OS X

The most simple way to get Python 2.7.5 installed on your Mac is to download and run the simple installer provided on the official Python website. You can download the installer by visiting the webpage at http://www.python.org/getit/releases/2.7.5/.

Warning

Ensure that you download the .dmg file that is relevant to your particular OS X installation!

  1. Once you have downloaded the .dmg file, double-click it in the Finder.
  2. The file mounts as a separate disk and a new Finder window is presented to you.
  3. Double-click the file Python.mpkg. This will start the Python installer.
  4. Continue through the various screens to the point where you are ready to install the software. You may have to provide your password to confirm that you wish to install the software.
  5. Upon completion, close the installer and eject the Python disk. You can now delete the downloaded .dmg file.

You should now have an updated version of Python installed, ready for Django! Easy, huh?

2.2.1.2. Linux Distributions

Unfortunately, there are many different ways in which you can download, install and run an updated version of Python on your Linux distribution. To make matters worse, methodologies vary from distribution to distribution. For example, the instructions for installing Python on Fedora may differ from those to install it on an Ubuntu installation.

However, not all hope is lost. An awesome tool (or a Python environment manager) called pythonbrew can help us address this difficulty. It provides an easy way to install and manage different versions of Python, meaning you can leave your operating system’s default Python installation alone. Hurrah!

Taken from the instructions provided from the pythonbrew GitHub page and this Stack Overflow question and answer page, the following steps will install Python 2.7.5 on your Linux distribution.

  1. Open a new terminal instance.
  2. Run the command curl -kL http://xrl.us/pythonbrewinstall | bash. This will download the installer and run it within your terminal for you. This installs pythonbrew into the directory ~/.pythonbrew. Remember, the tilde (~) represents your home directory!
  3. You then need to edit the file ~/.bashrc. In a text editor (such as gedit, nano, vi or emacs), add the following to a new line at the end of ~/.bashrc: [[ -s $HOME/.pythonbrew/etc/bashrc ]] && source $HOME/.pythonbrew/etc/bashrc
  4. Once you have saved the updated ~/.bashrc file, close your terminal and open a new one. This allows the changes you make to take effect.
  5. Run the command pythonbrew install 2.7.5 to install Python 2.7.5.
  6. You then have to switch Python 2.7.5 to the active Python installation. Do this by running the command pythonbrew switch 2.7.5.
  7. Python 2.7.5 should now be installed and ready to go.

Note

Directories and files beginning with a period or dot can be considered the equivalent of hidden files in Windows. Dot files are not normally visible to directory-browsing tools, and are commonly used for configuration files. You can use the ls command to view hidden files by adding the -a switch to the end of the command, giving the command ls -a.

2.2.1.3. Windows

By default, Microsoft Windows comes with no installations of Python. This means that you do not have to worry about leaving existing versions be; installing from scratch should work just fine. You can download a 64-bit or 32-bit version of Python from the official Python website. If you aren’t sure which one to download, you can determine if your computer is 32-bit or 64-bit by looking at the instructions provided on the Microsoft website.

  1. When the installer is downloaded, open the file from the location to which you downloaded it.
  2. Follow the on-screen prompts to install Python.
  3. Close the installer once completed, and delete the downloaded file.

Once the installer is complete, you should have a working version of Python ready to go. By default, Python 2.7.5 is installed to the folder C:\Python27. We recommend that you leave the path as it is.

Upon the completion of the installation, open a Command Prompt and enter the command python. If you see the Python prompt, installation was successful. However, in certain circumstances, the installer may not set your Windows installation’s PATH environment variable correctly. This will result in the python command not being found. Under Windows 7, you can rectify this by performing the following:

  1. Click the Start button, right click My Computer and select Properties.
  2. Click the Advanced tab.
  3. Click the Environment Variables button.
  4. In the System variables list, find the variable called Path, click it, then click the Edit button.
  5. At the end of the line, enter ;C:\python27;C:\python27\scripts. Don’t forget the semicolon - and certainly do not add a space.
  6. Click OK to save your changes in each window.
  7. Close any Command Prompt instances, open a new instance, and try run the python command again.

This should get your Python installation fully working. Windows XP, has slightly different instructions, and so do Windows 8 installationsthis.

2.2.2. Setting Up the PYTHONPATH

With Python now installed, we now need to check that the installation was successful. To do this, we need to check that the PYTHONPATH environment variable is setup correctly. PYTHONPATH provides the Python interpreter with the location of additional Python packages and modules which add extra functionality to the base Python installation. Without a correctly set PYTHONPATH, we’ll be unable to install and use Django!

First, let’s verify that our PYTHONPATH variable exists. Depending on the installation technique that you chose, this may or may not have been done for you. To do this on your UNIX-based operating system, issue the following command in a terminal.

$ echo $PYTHONPATH

On a Windows-based machine, open a Command Prompt and issue the following.

$ echo %PYTHONPATH%

If all works, you should then see output that looks something similar to the example below. On a Windows-based machine, you will obviously see a Windows path, most likely originating from the C drive.

/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages:

This is the path to your Python installation’s site-packages directory, where additional Python packages and modules are stored. If you see a path, you can continue to the next part of this tutorial. If you however do not see anything, you’ll need to do a little bit of detective work to find out the path. On a Windows installation, this should be a trivial exercise: site-packages is located within the lib folder of your Python installation directory. For example, if you installed Python to C:\Python27, site-packages will be at C:\Python27\Lib\site-packages\.

UNIX-based operating systems however require a little bit of detective work to discover the path of your site-packages installation. To do this, launch the Python interpreter. The following terminal session demonstrates the commands you should issue.

$ python

Python 2.7.5 (v2.7.5:ab05e7dd2788, May 13 2013, 13:18:45)
[GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin
Type "help", "copyright", "credits" or "license" for more information.

>>> import site
>>> print site.getsitepackages()[0]

'/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages'

>>> quit()

Calling site.getsitepackages() returns a list of paths that point to additional Python package and module stores. The first typically returns the path to your site-packages directory - changing the list index position may be required depending on your installation. If you receive an error stating that getsitepackages() is not present within the site module, verify you’re running the correct version of Python. Version 2.7.5 should include this function. Previous versions of the language do not include this function.

The string which is shown as a result of executing print site.getsitepackages()[0] is the path to your installation’s site-packages directory. Taking the path, we now need to add it to your configuration. On a UNIX-based or UNIX-derived operating system, edit your .bashrc file once more, adding the following to the bottom of the file.

export PYTHONPATH=$PYTHONPATH:<PATH_TO_SITE-PACKAGES>

Replace <PATH_TO_SITE-PACKAGES> with the path to your site-packages directory. Save the file, and quit and reopen any instances of your terminal.

On a Windows-based computer, you must follow the instructions shown in Section to bring up the environment variables settings dialog. Add a PYTHONPATH variable with the value being set to your site-packages folder, which is typically C:\Python27\Lib\site-packages\.

2.2.3. Using Setuptools and Pip

Installing and setting up your development environment is a really important part of any project. While it is possible to install Python Packages such as Django separately, this can lead to numerous problems and hassles later on. For example, how would you share your setup with another developer? How would you set up the same environment on your new machine? How would you upgrade to the latest version of the package? Using a package manager removes much of the hassle involved in setting up and configuring your environment. It will also ensure that the package you install is the correct for the version of Python you are using, along with installing any other packages that are dependent upon the one you want to install.

In this book, we will be using Pip. Pip is a user-friendly wrapper over the Setuptools Python package manager. Because Pip depends on Setuptools, we are required to ensure that both are installed on your computer.

To start, we should download Setuptools from the official Python package website. You can download the package in a compressed .tar.gz file. Using your favourite file extracting program, extract the files. They should all appear in a directory called setuptools-1.1.6 - where 1.1.6 represents the Setuptools version number. From a terminal instance, you can then change into the directory and execute the script ez_setup.py as shown below.

$ cd setuptools-1.1.6
$ sudo python ez_setup.py

In the example above, we also use sudo to allow the changes to become system-wide. The second command should install Setuptools for you. To verify that the installation was successful, you should be able to see output similar to that shown below.

Finished processing dependencies for setuptools==1.1.6

Of course, 1.1.6 is substituted with the version of Setuptools you are installing. If this line can be seen, you can move onto installing Pip. This is a trivial process, and can be completed with one simple command. From your terminal instance, enter the following.

$ sudo easy_install pip

This command should download and install Pip, again with system-wide access. You should see the following output, verifying Pip has been successfully installed.

Finished processing dependencies for pip

Upon seeing this output, you should be able to launch Pip from your terminal. To do so, just type pip. Instead of an unrecognised command error, you should be presented with a list of commands and switches that Pip accepts. If you see this, you’re ready to move on!

Note

With Windows-based computers, follow the same basic process. You won’t need to enter the sudo command, however.

2.2.4. Installing Django

Once the Python package manager Pip is successfully installed on your computer, installing Django is easy. Open a Command Prompt or terminal window, and issue the following command.

$ pip install -U django==1.5.4

If you are using a UNIX-based operating system and receive complaints about insufficient permissions, you will need to run the command with elevated privileges using the sudo command. If this is the case, you must then run the following command instead.

$ sudo pip install -U django==1.5.4

The package manager will download Django and install it in the correct location for you. Upon completion, Django should be successfully installed. Note, if you didn’t include the ==1.5.4, then a different version of Django may be installed.

2.2.5. Installing the Python Imaging Library

During the course of building Rango, we will be uploading and handling images. This means we will need support from the Python Imaging Library. To install this package issue the following command.

$ pip install pil

Again, use sudo if required.

Also note that pil may be out of date, depending on what version of Python you have installed, if this is the case, then you can install pillow instead which is a replacement for pil.

2.2.6. Installing Other Python Packages

It is worth noting that additional Python packages can be easily downloaded using the same manner. The Python Package Index provides a listing of all the packages available through Pip.

To get a list of the packages installed, you can run the following command.

$ pip list

2.2.7. Sharing your Package List

You can also get a list of the packages installed in a format that can be shared with other developers. To do this issue the following command.

$ pip freeze > requirements.txt

If you examine requirements.txt using either the command more, less or cat, you will see the same information but in a slightly different format. The requirements.txt can then use to install the same setup by issuing the following command. This is incredibly useful for setting up your environment on another computer, for example.

$ pip install -r requirements.txt

2.3. Integrated Development Environment

While not absolutely necessary, a good Python-based integrated development environment (IDE) can be very helpful to you during the development process. Several exist, with perhaps JetBrains’ PyCharm and PyDev (a plugin of the Eclipse IDE) standing out as popular choices. The Python Wiki provides an up-to-date list of Python IDEs.

Research which one is right for you, and be aware that some may require you to purchase a licence. Ideally, you’ll want to select an IDE that supports integration with Django. PyCharm and PyDev both support Django integration out of the box - though you will have to point the IDE to the version of Python that you are using.

2.4. Exercises

To get comfortable with your environment, try out the following exercises.

  • Install Python 2.7.5 and Pip.
  • Play around with your CLI and create a directory called code, which we use to create our projects in.
  • Install the Django and Pil packages.

2.4.1. Virtual Environments

We’re almost all set to go! However, before we continue, it’s worth pointing out that while this setup is fine to begin with, there are some drawbacks. What if you had another Python application that requires a different version to run? Or you wanted to switch to the new version of Django, but still wanted to maintain your Django 1.5.4 project?

The solution to this is to use virtual environments. Virtual environments allow multiple installations of Python and their relevant packages to exist in harmony, without disrupting one another. This is the generally accepted approach to configuring a Python setup nowadays. We don’t go into much detail about them in this chapter because of their complexity, but in the chapter on Deploying your Application we will go through setting up a virtual environment. If you are really keen, check out a non-magical introduction to Pip and Virtualenv for Python Beginners by Jamie Matthews.

2.4.2. Code Repository

We should also point out that when you develop code, you should always house your code within a version-controlled repository such as SVN or GIT. We won’t be going through this right now so that we can get stuck into developing an application in Django. We have however provided a crash course on GIT. We highly recommend that you set up a GIT repository for your own projects. Doing so could save you from disaster.