Django Integration

These functions streamline the process of initializing Django’s settings module environment variable. Once this is done, your fabfile may import from your Django project, or Django itself, without requiring the use of manage.py plugins or having to set the environment variable yourself every time you use your fabfile.

Currently, these functions only allow Fabric to interact with local-to-your-fabfile Django installations. This is not as limiting as it sounds; for example, you can use Fabric as a remote “build” tool as well as using it locally. Imagine the following fabfile:

from fabric.api import run, local, hosts, cd
from fabric.contrib import django

django.project('myproject')
from myproject.myapp.models import MyModel

def print_instances():
    for instance in MyModel.objects.all():
        print(instance)

@hosts('production-server')
def print_production_instances():
    with cd('/path/to/myproject'):
        run('fab print_instances')

With Fabric installed on both ends, you could execute print_production_instances locally, which would trigger print_instances on the production server – which would then be interacting with your production Django database.

As another example, if your local and remote settings are similar, you can use it to obtain e.g. your database settings, and then use those when executing a remote (non-Fabric) command. This would allow you some degree of freedom even if Fabric is only installed locally:

from fabric.api import run
from fabric.contrib import django

django.settings_module('myproject.settings')
from django.conf import settings

def dump_production_database():
    run('mysqldump -u %s -p=%s %s > /tmp/prod-db.sql' % (
        settings.DATABASE_USER,
        settings.DATABASE_PASSWORD,
        settings.DATABASE_NAME
    ))

The above snippet will work if run from a local, development environment, again provided your local settings.py mirrors your remote one in terms of database connection info.

fabric.contrib.django.project(name)

Sets DJANGO_SETTINGS_MODULE to '<name>.settings'.

This function provides a handy shortcut for the common case where one is using the Django default naming convention for their settings file and location.

Uses settings_module – see its documentation for details on why and how to use this functionality.

fabric.contrib.django.settings_module(module)

Set DJANGO_SETTINGS_MODULE shell environment variable to module.

Due to how Django works, imports from Django or a Django project will fail unless the shell environment variable DJANGO_SETTINGS_MODULE is correctly set (see the Django settings docs.)

This function provides a shortcut for doing so; call it near the top of your fabfile or Fabric-using code, after which point any Django imports should work correctly.

Note

This function sets a shell environment variable (via os.environ) and is unrelated to Fabric’s own internal “env” variables.