django-environments¶

Compatibility with virtualenv¶

Please note django-environments does not in any way depend on virtualenv, although it can be used together with virtualenv quite well.

When using django-environments within a single virtualenv environment, you can switch between Django projects as often as you like. If you use virtualenvwrapper, use bin/postactivate and bin/predeactivate for calling djenv and djexit respectively.

Compatibility with Python < 2.6¶

In the example settings files, from .. import * is used. You will need to change this to from <project>.settings import * for older versions of Python. The downside is that you will have to include the project name in your settings, which is a violation of the DRY principle that django-environments tries to live by.

Definining your settings¶

Instead of using a single settings.py module, django-environments expects you to organize your settings in a Python package, for example:

mysite/
    settings/
        __init__.py
        env/
            __init__.py
            development.py
            production.py
        base.py

Additionally, it suggests (but does not dictate) you use an inheritance/generalization model, simply by “inheriting” from more generic settings using from <package> import *, and overruling the settings as needed:

# mysite/settings/base.py
from djenv.settings import *

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'django.contrib.messages',
    'mysite',
)

# mysite/settings/env/development.py
from mysite.settings.base import *

DEBUG = True

INSTALLED_APPS += (
    'debug_toolbar',
)

Available settings modules¶

Using Apache mod_wsgi¶

Should you wish to use the settings in for instance settings/env/staging.py, simply copy the example mysite/deploy/development.wsgi to mysite/deploy/staging.wsgi, or make staging.wsgi a symlink (if your Apache configuration allows it, which is normally the case). Next, add something like this to your httpd.conf:

WSGIScriptAlias / /Users/spanky/repos/django-environments/mysite/deploy/staging.wsgi

And restart Apache. The identifier ‘staging’ in staging.wsgi will automatically make sure settings.env.staging is used. Create other .wsgi files for other environment settings.

Refer to the source of the provided WSGI script to see how specific directories, like a virtualenv site-packages directory, can be prepended to sys.path, overruling standard Python environment settings.

Automatic generation of local WSGI links and settings file¶

If you want your WSGI setup done as quickly as possible, activate an environment - either directly via your bin/initenv or through virtualenv - and execute bin/setup_local_wsgi.sh <environment>, e.g.:

$ bin/setup_local_wsgi.sh staging

This will create a deploy/local.wsgi symbolic link to staging.wsgi and will create a settings/env/local.py with default contents for a given environment. Now, you only need to update settings.env.local with those settings you want to keep absolutely local, like those containing user ids and passwords. Keep in mind the script will overwrite existing local.py settings files!

Directories¶

• The mysite/example/settings directory replaces settings.py and contains the default settings in generic.py, whose contents are imported in __init__.py.
• The mysite/settings/env directory contains the different settings files for every environment.
• All .wsgi files in the mysite/deploy folder are normally equal, except for the sys.path configuration. Their respective filenames are used to determine which settings to import. If your Apache configuration allows it, you could use symlinks instead of copies.

Remarks¶

• urls.py is just there to demonstrate the SERVE_MEDIA setting, which is not essential anyway.
• manage.py was removed as the generated default ignores $DJANGO_SETTINGS_MODULE, simply importing ‘settings’ instead.
• the Django startapp command will create new apps in $DJANGO_PROJECT/settings/env. Apparently, Django uses the basename of the settings __file__ as a reference point for the new app.

Remove django-environments from “hg externals”¶

Before, it was common to include django-environments as an external Mercurial repository in your project using a requirements/externals-prd.txt file, which would contain something like this:

https://bitbucket.org/goeiejongens/django-environments#bed884e334c2

If you wish to migrate to this Github “fork”, you have two options:

• Regular install from PyPI
• Development install from Github

Reverse use of .sh for shell scripts¶

The use of the .sh extension for the shell scripts has been reversed: scripts that are meant to be directly executed now do not have an extension, and scripts that are meant to be “sourced” do have an .sh extension. If you call these scripts in any of your own scripts, you should update accordingly.

Top-level “etc” symlink no longer necessary¶

Because django-environments is now setuptools-compliant, it will install itself into the Python “site-packages” directory (both if you do a standard PyPI install or an “editable” install from Github), and will therefore be automatically available on your Python path.

However, see next item.

Python “etc” package renamed to “djenv”¶

To avoid naming conflicts with other Python packages, djenv seemed like a better package name. You should probably do a global search/replace for:

• etc.settings => djenv.settings
• etc.urls => djenv.urls

g0j0 settings proxy removed¶

The template settings previously included the “g0j0.context_processors.settings_proxy” in the default list of TEMPLATE_CONTEXT_PROCESSORS. This g0j0 dependency has now been removed to keep django-environments generic, so please add it manually in your project settings if you require it.

About your global django-environments installation¶

There’s a good chance that you also have a global installation of django-environments (e.g. to activate projects using the djp command). If so, you probably currently source the Bash scripts containing the various shell functions from your .bashrc like so:

source $REPOS/django-environments/bin/djenvlib
source $REPOS/django-environments/bin/djenv.mercurial # optionally

If you want, you can simply keep working this way (replacing of course the checkout from Bitbucket with a clone from Github. Having a central checkout of django-environments also allows you to contribute to django-environments itself while using it in other projects.

However, if you simply want to have a global installation of django-environments, you could also simply install it from PyPI directly into your global site packages:

$ deactivate # make sure you are not in any activated virtualenv
$ PIP_REQUIRE_VIRTUALENV=false pip install django-environments

This installs the shell scripts into a common bin directory (the exact location depends on your Python installation):

$ which djenvlib.sh
/usr/local/bin/djenvlib.sh # Location for Homebrew Python on Mac OS X

You should then be able to simply source the scripts from your .bashrc like so:

source djenvlib.sh
source djenv.mercurial.sh