I've been working on a project using the excellent Pinax platform, and I wanted to share some of the tricks I use to make it easier to work with. You can find out more about Pinax by visiting their site. I'm working with their recent 0.7beta3 release, so if you're still on an earlier version things may be a bit different.

Virtualenv is vital when working with Pinax, and I also highly recommend virtualenvwrapper. Virtualenvwrapper adds the workon, mkvirtualenv, and rmvirtualenv commands which add additional ease to working with virtual Python environments.

Getting Started

To begin, I create a directory that will serve as my project home. I usually name the directory based on the target domain name. We'll call this directory myproject.com. Within the myproject.com directory, I create a subdirectory called scripts. I like to keep all of my environment management scripts in their own directory, similar to how Pinax itself is organized.

Automatic Pinax Downloading and Unpacking

Within the scripts directory, I create a simple Pinax downloader. The purpose for this is to quickly and easily set up my environment on each new computer I'm using. I switch back and forth between different computers a lot, so being able to quickly build my project's environment from scratch is important to me. I create the file getpinax.py inside the scripts directory, and fill it with the following contents:

#!/usr/bin/env python

import os
import sys
import urllib
import tarfile

root_dir = os.path.realpath(os.path.join(os.path.dirname(__file__), '..'))

pinax_ver = 'pinax-0.7beta3'
pinax_url = 'http://downloads.pinaxproject.com/%s.tar.gz' % pinax_ver

def progress(count, block_size, total_size):
    percent = int(count*block_size*100/total_size)
    sys.stdout.write('\rDownloading Pinax' + "...%d%%" % percent)
    sys.stdout.flush()

def main():
    try:
        filename, msg = urllib.urlretrieve(pinax_url, reporthook=progress)
        print os.linesep + 'Done!'
    except:
        sys.exit('Unable to download Pinax.')

    tar = tarfile.open(filename)
    tar.extractall(path=root_dir)
    tar.close()

    urllib.urlcleanup()

if __name__ == '__main__':
    main()

This is a very simple script that simply downloads the latest Pinax release (configured manually inside the script using the pinax_ver variable) and unpacks it in the root directory of my project. I end up with a new directory under my project root called pinax-0.7beta3.

Establishing the Pinax Virtual Environment

I change to that directory, and then run python scripts/pinax-boot.py $WORKON_HOME/myproject-env to set up the Pinax virtual environment. The WORKON_HOME environment variable comes from virtualenvwrapper. If I'm working on a system that doesn't have virtualenvwrapper (such as a Windows box), I adjust the command to read python scripts/pinax-boot.py ../myproject-env instead to install the virtual environment to a subdirectory underneath the project root.

Next, I activate my Pinax virtual environment. If I'm using virtualenvwrapper, I simply type workon myproject-env. If I established the virtual environment underneath the project root, I switch to that directory and run the activate script. For example, in Windows (typically the only environment I work in that I don't use virtualenvwrapper for) I change to the myproject.com/myproject-env directory and run Scripts\activate.bat. If the command was successful, your prompt should now be prefixed with (myproject-env) on Unix-like environments or something ugly like (MYPROJ~1) in Windows.

Cloning the Project Template

Now I can use one of Pinax's pre-made templates to form the base of my project. I change back to my project root directory, and use the pinax-admin utility to clone a project. For instance, if I wanted to use the social_project template I would use the command pinax-admin clone_project social_project myproject from my project's root directory.

At this point, my root directory looks like the following:

myproject.com
    -myproject (The source folder for my project)
    -myproject-env (Only if I didn't use virtualenvwrapper)
    -pinax-0.7beta3
    -scripts

Version Control

Before I start hacking away on my project, though, I need to set up my version control system. I use Mercurial, but these instructions should translate easily to other systems. First off, I initialize the repository with hg init. I don't check the entire thing into version control, because a very large portion of my project folder is binary archives or files that are automatically generated each time I set up my environment on a new machine. I add myproject-env (if I didn't use virtualenvwrapper) and pinax-0.7beta3 to my version control's ignore file. For Mercurial, it's .hgignore in the project's root directory. I also add *.pyc to the .hgignore file to ignore compiled Python files.

Once I've setup my repository to ignore the virtual environment and the Pinax directory, the only directories that version control should be paying attention to are myproject and scripts. I use hg add to automatically add my desired files to version control.

Firing It Up

Next, while still in the myproject-env virtual environment, I change to the myproject directory and run python manage.py syncdb and then python manage.py runserver. I head to http://localhost:8000, and I'm now ready to start hacking!

The beauty of this is how easy it is to fire up the project on a new machine. From my projects folder on a new machine, I use the following sequence of commands:

$ hg clone http://my.coderepo.com/myproject.com
$ cd myproject.com
$ python scripts/getpinax.py
Downloading Pinax...100%
Done!

$ cd pinax*
$ python scripts/pinax-boot.py $WORKON_HOME/myproject-env
(output from the virtualenv creation)

$ cd ../myproject
$ workon myproject-env
$ python manage.py runserver

I'd love to hear about how you set up your Pinax projects and any convenience functions you've created. Thanks!