Much of this document is an adaptation from an excellent blog by Saltycrane (which unfortunately appears to be down now.) See the Resources section at the bottom for the link to the site.

This is a sketch for the inner working of a pip web2py setup to be completed at some later date so please leave comments. If anyone has experience creating pip installable packages or "installer" utilities let me know, I have zero experience in creating pip packages.

Description

After insuring that our target installation system has the prerequisites at minimum we install virtualenv and mercurial which are then used to create a sandboxed Web2py in the users home directory. The future package would be best if it is os agnostic (no bash, all python). I considered using fabric as well, but I think for the time being just this would be a real help to developers who are new to Web2py.

Prerequisites

All of our prerequisites in this example are required on the host system (in other words, not in a virtualenv.)

pip & virtualenv installation

In this example we install pip and virtualenv to the hosts python installation in preparation for our work in a virtualenv.

Installing pip using Easy Install

Install Easy Install

sudo apt-get install python-setuptools python-dev build-essential

Installing pip using Easy Install

--upgrade (-U) force upgrade (searches PyPI for latest versions)

sudo easy_install -U pip

Installing virtualenv using pip

sudo pip install virtualenv==1.6.4

OR use the --upgrade switch to get the newest available version -> sudo pip install -U virtualenv

Procedures

Creating a virtual environment

We will create a directory to hold our virtual environments in called V_ENVS. Then we will create a single virtual environment inside of this directory for our installation called "Web2py".

Make a directory to hold any virtual environments

W2P_ENVS=${HOME}/V_ENVS
mkdir -p ${W2P_ENVS}
cd ${W2P_ENVS}

Create our virtual environment

cd ${W2P_ENVS}
VENV=Web2py
virtualenv --no-site-packages --distribute ${VENV}

Installing mercurial "into" our new virtual environment

Here we use pip's -E option to install a package to the specified virtual environment. (Yolk is a tool that lists Python packages.) (The working directory is /srv/python-environments.)

pip install -E ${VENV} mercurial

OR specify a specific version with pip install -E Web2py mercurial==1.9

Activate our virtual environment.

Although we installed mercurial into our virtual environment using pip, the environment is not active so we can only access our new mercurial by specifying the path to our new mercurial (./Web2py/bin/hg). To avoid this hassle we can activate our environment via the activate script. Once the environment it active you will notice (Web2py) at the beginning of your command prompt.

source Web2py/bin/activate

Check your virtual environment

Once the virtual environment is active you can run commands from the command line and the path will point to your virtual environments programs. So running the "which" command or version commands will now report on the programs in your virtual environment.

which python
which hg
hg -version

deactivate your virtual environment

To exit your virtual environment you deactivate it.

deactivate

Once the virtual environment is deactivated you will notice that the (Web2py) at the beginning of your terminal line is no longer present.

Check your system environment

Once you deactivate your virtual environment you can run the same commands and you will now see the results for yur host system

which python
which hg
hg --version

Activate a virtual environment

source Web2py/bin/activate

Clone Web2py

Make sure your virtual environment is active by checking for the (Web2py) in your terminal.

cd Web2py
hg clone https://code.google.com/p/web2py/ web2py

Launch Web2py

./bin/python ./web2py/web2py.py

Deactivate our virtualenv

Once you have completed your Web2py session stop the server and deactivate your Web2py virtual environment using the deactivate command. For confirmation the the virtual environment is no longer active see if the (Web2py) at the beginning of the terminal line is gone.

deactivate

Optional and advanced

pip environment variables for saving sources to cache.

requirements files

Create a requirements file from a "perfectly configured" Web2py virtual environment.

pip freeze my-requirements.txt

Using a requirements file for a new pip installation

It is easy to recreate a new virtualenv and it's all of the pip installed programs using a requirements file.

pip install -E venv -r cosmos-requirements.txt

The above command creates a virtual environment (in this case called "venv" and installs all of the packages listed in our requirements file automatically.

The Future

Virtualenvwrapper

Virtualenvwrapper lets you easily jump between multiple virtual environments using the workon command. Very handy but a bit too much for someone who is also new to Web2py, I would do this later for sure, but it would be a great option for developers. Allows us to replace:

source my_virtual_environment/bin/activate

with:

workon my_virtual_environment

See

http://www.doughellmann.com/docs/virtualenvwrapper/

for details.

RESOURCES:

The Hitchhiker's Guide to Packaging v1.0 documentation

http://guide.python-distribute.org/quickstart.html#lay-out-your-project

Notes on using pip and virtualenv with Django

http://www.saltycrane.com/blog/2009/05/notes-using-pip-and-virtualenv-django/

Virtualenvwrapper

http://www.doughellmann.com/docs/virtualenvwrapper/