Web Development with Django Cookbook

Before getting into the usage example of virtual environments, let's install pip (the most convenient tool to install and manage Python packages), the shared Python modules Pillow and MySQLdb, and the virtualenv utility using the following commands:

$ sudo easy_install pip
$ sudo pip install Pillow
$ sudo pip install MySQL-python
$ sudo pip install virtualenv

Now, when you have your prerequisites installed, create a directory where all your Django projects will be stored, for example, virtualenvs under your home directory. Perform the following steps after creating the directory:

When you create a virtual environment, specific directories (bin, build, include, and lib) are created to store a copy of the Python installation, and some shared Python paths are defined. When the virtual environment is activated, whatever you install with pip or easy_install will be put into and used by the site packages of the virtual environment, and not the global site-packages of your Python installation.

To install Django 1.6 to your virtual environment, type the following command:

(myproject_env)$ pip install Django==1.6

If you haven't done this yet, first create the virtualenvs directory where you will keep all your virtual environments (read about this in the Working with a virtual environment recipe), and which can be created under your home directory.

Then, create the directory for your project's environment, for example, myproject_env. Start the virtual environment inside it. This will create the bin, build, include, and lib directories there. I suggest adding the commands directory for local bash scripts related to the project, the db_backups directory for database dumps, and the project directory for your Django project. Also, install Django into your virtual environment.

Follow these steps to create a file structure for your project:

The whole file structure for a complete project inside a virtual environment will look like this:

Before using this recipe, you need to have pip installed and a virtual environment activated. For more information on how to do this, read the Working with a virtual environment recipe.

Let's go to your Django project that you have under version control and create the requirements file with the following content:

#requirements.txt
Django==1.6
South==0.8.4
django-cms==2.4

Now, you can run the following command to install all required dependencies for your Django project:

(myproject_env)$ pip install -r requirements.txt

This command installs all your project dependencies into your virtual environment one after another.

When you have many dependencies in your project, it is good practice to stick to specific versions of the Python modules because you can then be sure that when you deploy your project or give it to a new developer, the integrity doesn't get broken and all the modules function without conflicts.

If you have already installed project requirements with pip manually one by one, you can generate the requirements.txt file using the following command:

(myproject_env)$ pip freeze > requirements.txt

If you need to install a Python library directly from a version control system or a local path, you can learn more about pip from the official documentation at http://pip.readthedocs.org/en/latest/reference/pip_install.html.

Start with a virtual environment with a Django project in it.

Execute the following steps one by one:

A module is meant to be under the Python path if you can run Python and import the module. One of the ways to put a module under the Python path is to modify the sys.path variable before importing a module that is in an unusual location. The value of sys.path is a list of directories starting with an empty string for the current directory, followed by the directories in the virtual environment, and finally the globally shared directories of the Python installation. You can see the value of sys.path in the Python shell, as follows:

(myproject_env)$ python
>>> import sys
>>> sys.path

When trying to import a module, Python searches for the module in this list and returns the first result found.

So, at first, we define the PROJECT_PATH variable that is the absolute path to one level higher than the settings.py file. Then, we define the variables EXTERNAL_LIBS_PATH and EXTERNAL_APPS_PATH, which are relative to PROJECT_PATH. Lastly, we modify the sys.path property, adding new paths to the beginning of the list. Note that we also add an empty string as the first path to search, which means that the current directory of any module should always be checked first before checking other Python paths.

To start with, open up settings.py.

Modify your path-related settings accordingly, instead of hardcoding paths to your local directories:

#settings.py
# -*- coding: UTF-8 -*-
import os

PROJECT_PATH = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))

MEDIA_ROOT = os.path.join(PROJECT_PATH, "myproject", "media")

STATIC_ROOT = os.path.join(PROJECT_PATH, "myproject", "static")

STATICFILES_DIRS = (
    os.path.join(PROJECT_PATH, "myproject", "site_static"),
)

TEMPLATE_DIRS = (
    os.path.join(PROJECT_PATH, "myproject", "templates"),
)

LOCALE_PATHS = (
    os.path.join(PROJECT_PATH, "locale"),
)

FILE_UPLOAD_TEMP_DIR = os.path.join(PROJECT_PATH, "myproject", "tmp")

At first, we define PROJECT_PATH, which is an absolute path to one level higher than the settings.py file. Then, we set all the paths relative to PROJECT_PATH using the os.path.join function.

Make sure that your project is under the Subversion version control and you have PROJECT_PATH defined in your settings, as shown in the Defining relative paths in the settings recipe.

Then, create the utils module in your Django project, and also create a file called misc.py there.

The procedure for putting the revision number into the STATIC_URL setting consists of the following two steps:

The get_media_svn_revision function takes the absolute_path directory as a parameter and calls the svn info shell command in that directory to find out the current revision. We pass PROJECT_PATH to the function because we are sure it is under version control. Then, the revision is parsed, returned, and included in the STATIC_URL definition.

Make sure that your project is under the Git version control and you have PROJECT_PATH defined in your settings, as shown in the Defining relative paths in the settings recipe.

If you haven't done it yet, create the utils module in your Django project, and create a file called misc.py there.

The procedure for putting the Git timestamp into the STATIC_URL setting consists of the following two steps:

The get_git_changeset function takes the absolute_path directory as a parameter and calls the git show shell command with the parameters to show the Unix timestamp of the HEAD revision in the directory. As in the previous recipe, we pass PROJECT_PATH to the function because we are sure it is under version control. The timestamp is parsed; converted to a string consisting of year, month, day, hour, minutes, and seconds; returned; and included in the definition of STATIC_URL.

Most of the settings for different environments will be shared and saved in version control. However, there will be some settings that are specific to the environment of the project instance, for example, database or e-mail settings. We will put them in the local_settings.py file.

Perform the following steps:

As you can see, the local settings are not normally imported, but rather they are included and executed in the settings.py file itself. This allows you not only to create or overwrite the existing settings, but also to adjust the tuples or lists from the settings.py file; for example, we add debug_toolbar to INSTALLED_APPS here to be able to debug the SQL queries, template context variables, and so on.

Make sure that the MySQL database management system and the MySQLdb Python module are installed and you are using the MySQL engine in your project's settings.

Open the MySQL configuration file (/etc/mysql/my.cnf) in your favorite editor, and ensure that the following settings are set in the sections [client], [mysql], and [mysqld]:

#/etc/mysql/my.cnf
[client]
default-character-set = utf8

[mysql]
default-character-set = utf8

[mysqld]
collation-server = utf8_unicode_ci
init-connect = 'SET NAMES utf8'
character-set-server = utf8

If any of the sections don't exist, create them in the file. Then, restart MySQL in your command-line tool, as follows:

/etc/init.d/mysql restart

Now, whenever you create a new MySQL database, the databases and all their tables will be set in the UTF-8 encoding by default.

Don't forget to set this in all computers where your project is developed or published.

Make sure that your Django project is under the Subversion version control.

Open your command-line tool and set your default editor as nano, vi, vim, or any other that you prefer, as follows:

$ export EDITOR=nano

Then, go to your project directory and type the following command:

$ svn propedit svn:ignore .

This will open a temporary file in the editor, where you need to put the following file and directory patterns for Subversion to ignore:

*.pyc
local_settings.py
static
media
tmp

Save the file and exit the editor. For every other Python package in your project, you will need to ignore the *.pyc files. Just go to a directory and type the following command:

$ svn propedit svn:ignore .

Then, put this in the temporary file, save it, and close the editor:

*.pyc

In Subversion, you need to define ignore properties for each directory of your project. Mainly, we don't want to track the Python-compiled files, for instance, *.pyc. We also want to ignore local_settings.py that is specific for each developer, static that replicates collected static files from different apps, media that contains uploaded files and will be changing together with the database, and tmp that is temporarily used for file uploads.

Make sure that your Django project is under Git version control.

Using your favorite text editor, create a .gitignore file at the root of your Django project and put these files and directories there:

#.gitignore
*.pyc
/myproject/local_settings.py
/myproject/static/
/myproject/tmp/
/myproject/media/

The .gitignore file specifies the paths that should intentionally be untracked by the Git version control system. The .gitignore file we created in this recipe will ignore the Python-compiled files, local settings, collected static files, temporary directory for uploads, and media directory with the uploaded files.

Use your favorite editor and edit, or create, a .bash_profile file in your home directory.

Add this alias at the end of .bash_profile:

#~/.bash_profile
alias delpyc="find . -name \"*.pyc\" -delete"

Now, to clean up the Python-compiled files, go to your project directory and type this command in the command line:

$ delpyc

At first, we create a Unix alias that searches for the *.pyc files and deletes them in the current directory and its children. The .bash_profile file is executed when you start a new session in the command-line tool.

Create a virtual environment and a Django project in it.

Use the following structure in any Python file you create. Just after the first line that defines UTF-8 as the default Python file encoding, put imports categorized into sections:

# -*- coding: UTF-8 -*-
# System libraries
import os
import re
from datetime import datetime

# Third-party libraries
import boto
from PIL import Image

# Django modules
from django.db import models
from django.conf import settings

# Django apps
from cms.models import Page

# Current-app modules
import app_settings

We have five main categories for the imports, as follows:

When coding in Python and Django, use the official style guide for Python code, PEP 8. You can find it at http://legacy.python.org/dev/peps/pep-0008/.

Create your Django app either manually or by using this command:

(myproject_env)$ django-admin.py startapp myapp1

If you have just one or two settings, you can use the following pattern in your models.py file. If the settings are extensive, and you want to have them better organized, create an app_settings.py file in the app and put the settings in the following way:

#models.py or app_settings.py
# -*- coding: UTF-8 -*-
from django.conf import settings
from django.utils.translation import ugettext_lazy as _

SETTING1 = getattr(settings, "MYAPP1_SETTING1", u"default value")
MEANING_OF_LIFE = getattr(settings, "MYAPP1_MEANING_OF_LIFE", 42)
STATUS_CHOICES = getattr(settings, "MYAPP1_STATUS_CHOICES", (
    ('draft', _("Draft")),
    ('published', _("Published")),
    ('not_listed', _("Not Listed")),
))

Then, you can use the app settings in models.py in the following way:

#models.py
# -*- coding: UTF-8 -*-
from django.db import models
from django.utils.translation import ugettext_lazy as _

from app_settings import STATUS_CHOICES

class NewsArticle(models.Model):
    # ...
    status = models.CharField(_("Status"),
        max_length=20, choices=STATUS_CHOICES
    )

If you want to overwrite the STATUS_CHOICES setting for just one project, you simply open settings.py and add this:

#settings.py
# ...
from django.utils.translation import ugettext_lazy as _
MYAPP1_STATUS_CHOICES = (
    ("imported", _("Imported")),
    ("draft", _("Draft")),
    ("published", _("Published")),
    ("not_listed", _("Not Listed")),
    ("expired", _("Expired")),
)

The Python function, getattr(object, attribute_name[, default_value]), tries to get the attribute_name attribute from object, and returns default_value if it is not found. In this case, different settings are tried to be taken from the Django project settings module, and if they are not found, the default values are assigned.